PageRenderTime 65ms CodeModel.GetById 19ms app.highlight 35ms RepoModel.GetById 1ms app.codeStats 0ms

/Lib/distutils/ccompiler.py

http://unladen-swallow.googlecode.com/
Python | 1230 lines | 1071 code | 40 blank | 119 comment | 22 complexity | 2de337f0ffd338233b08357585051e8b MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1"""distutils.ccompiler
   2
   3Contains CCompiler, an abstract base class that defines the interface
   4for the Distutils compiler abstraction model."""
   5
   6# This module should be kept compatible with Python 2.1.
   7
   8__revision__ = "$Id: ccompiler.py 67896 2008-12-21 17:01:26Z benjamin.peterson $"
   9
  10import sys, os, re
  11from types import *
  12from copy import copy
  13from distutils.errors import *
  14from distutils.spawn import spawn
  15from distutils.file_util import move_file
  16from distutils.dir_util import mkpath
  17from distutils.dep_util import newer_pairwise, newer_group
  18from distutils.util import split_quoted, execute
  19from distutils import log
  20
  21class CCompiler:
  22    """Abstract base class to define the interface that must be implemented
  23    by real compiler classes.  Also has some utility methods used by
  24    several compiler classes.
  25
  26    The basic idea behind a compiler abstraction class is that each
  27    instance can be used for all the compile/link steps in building a
  28    single project.  Thus, attributes common to all of those compile and
  29    link steps -- include directories, macros to define, libraries to link
  30    against, etc. -- are attributes of the compiler instance.  To allow for
  31    variability in how individual files are treated, most of those
  32    attributes may be varied on a per-compilation or per-link basis.
  33    """
  34
  35    # 'compiler_type' is a class attribute that identifies this class.  It
  36    # keeps code that wants to know what kind of compiler it's dealing with
  37    # from having to import all possible compiler classes just to do an
  38    # 'isinstance'.  In concrete CCompiler subclasses, 'compiler_type'
  39    # should really, really be one of the keys of the 'compiler_class'
  40    # dictionary (see below -- used by the 'new_compiler()' factory
  41    # function) -- authors of new compiler interface classes are
  42    # responsible for updating 'compiler_class'!
  43    compiler_type = None
  44
  45    # XXX things not handled by this compiler abstraction model:
  46    #   * client can't provide additional options for a compiler,
  47    #     e.g. warning, optimization, debugging flags.  Perhaps this
  48    #     should be the domain of concrete compiler abstraction classes
  49    #     (UnixCCompiler, MSVCCompiler, etc.) -- or perhaps the base
  50    #     class should have methods for the common ones.
  51    #   * can't completely override the include or library searchg
  52    #     path, ie. no "cc -I -Idir1 -Idir2" or "cc -L -Ldir1 -Ldir2".
  53    #     I'm not sure how widely supported this is even by Unix
  54    #     compilers, much less on other platforms.  And I'm even less
  55    #     sure how useful it is; maybe for cross-compiling, but
  56    #     support for that is a ways off.  (And anyways, cross
  57    #     compilers probably have a dedicated binary with the
  58    #     right paths compiled in.  I hope.)
  59    #   * can't do really freaky things with the library list/library
  60    #     dirs, e.g. "-Ldir1 -lfoo -Ldir2 -lfoo" to link against
  61    #     different versions of libfoo.a in different locations.  I
  62    #     think this is useless without the ability to null out the
  63    #     library search path anyways.
  64
  65
  66    # Subclasses that rely on the standard filename generation methods
  67    # implemented below should override these; see the comment near
  68    # those methods ('object_filenames()' et. al.) for details:
  69    src_extensions = None               # list of strings
  70    obj_extension = None                # string
  71    static_lib_extension = None
  72    shared_lib_extension = None         # string
  73    static_lib_format = None            # format string
  74    shared_lib_format = None            # prob. same as static_lib_format
  75    exe_extension = None                # string
  76
  77    # Default language settings. language_map is used to detect a source
  78    # file or Extension target language, checking source filenames.
  79    # language_order is used to detect the language precedence, when deciding
  80    # what language to use when mixing source types. For example, if some
  81    # extension has two files with ".c" extension, and one with ".cpp", it
  82    # is still linked as c++.
  83    language_map = {".c"   : "c",
  84                    ".cc"  : "c++",
  85                    ".cpp" : "c++",
  86                    ".cxx" : "c++",
  87                    ".m"   : "objc",
  88                   }
  89    language_order = ["c++", "objc", "c"]
  90
  91    def __init__ (self,
  92                  verbose=0,
  93                  dry_run=0,
  94                  force=0):
  95
  96        self.dry_run = dry_run
  97        self.force = force
  98        self.verbose = verbose
  99
 100        # 'output_dir': a common output directory for object, library,
 101        # shared object, and shared library files
 102        self.output_dir = None
 103
 104        # 'macros': a list of macro definitions (or undefinitions).  A
 105        # macro definition is a 2-tuple (name, value), where the value is
 106        # either a string or None (no explicit value).  A macro
 107        # undefinition is a 1-tuple (name,).
 108        self.macros = []
 109
 110        # 'include_dirs': a list of directories to search for include files
 111        self.include_dirs = []
 112
 113        # 'libraries': a list of libraries to include in any link
 114        # (library names, not filenames: eg. "foo" not "libfoo.a")
 115        self.libraries = []
 116
 117        # 'library_dirs': a list of directories to search for libraries
 118        self.library_dirs = []
 119
 120        # 'runtime_library_dirs': a list of directories to search for
 121        # shared libraries/objects at runtime
 122        self.runtime_library_dirs = []
 123
 124        # 'objects': a list of object files (or similar, such as explicitly
 125        # named library files) to include on any link
 126        self.objects = []
 127
 128        for key in self.executables.keys():
 129            self.set_executable(key, self.executables[key])
 130
 131    # __init__ ()
 132
 133
 134    def set_executables (self, **args):
 135
 136        """Define the executables (and options for them) that will be run
 137        to perform the various stages of compilation.  The exact set of
 138        executables that may be specified here depends on the compiler
 139        class (via the 'executables' class attribute), but most will have:
 140          compiler      the C/C++ compiler
 141          linker_so     linker used to create shared objects and libraries
 142          linker_exe    linker used to create binary executables
 143          archiver      static library creator
 144
 145        On platforms with a command-line (Unix, DOS/Windows), each of these
 146        is a string that will be split into executable name and (optional)
 147        list of arguments.  (Splitting the string is done similarly to how
 148        Unix shells operate: words are delimited by spaces, but quotes and
 149        backslashes can override this.  See
 150        'distutils.util.split_quoted()'.)
 151        """
 152
 153        # Note that some CCompiler implementation classes will define class
 154        # attributes 'cpp', 'cc', etc. with hard-coded executable names;
 155        # this is appropriate when a compiler class is for exactly one
 156        # compiler/OS combination (eg. MSVCCompiler).  Other compiler
 157        # classes (UnixCCompiler, in particular) are driven by information
 158        # discovered at run-time, since there are many different ways to do
 159        # basically the same things with Unix C compilers.
 160
 161        for key in args.keys():
 162            if key not in self.executables:
 163                raise ValueError, \
 164                      "unknown executable '%s' for class %s" % \
 165                      (key, self.__class__.__name__)
 166            self.set_executable(key, args[key])
 167
 168    # set_executables ()
 169
 170    def set_executable(self, key, value):
 171        if type(value) is StringType:
 172            setattr(self, key, split_quoted(value))
 173        else:
 174            setattr(self, key, value)
 175
 176
 177    def _find_macro (self, name):
 178        i = 0
 179        for defn in self.macros:
 180            if defn[0] == name:
 181                return i
 182            i = i + 1
 183
 184        return None
 185
 186
 187    def _check_macro_definitions (self, definitions):
 188        """Ensures that every element of 'definitions' is a valid macro
 189        definition, ie. either (name,value) 2-tuple or a (name,) tuple.  Do
 190        nothing if all definitions are OK, raise TypeError otherwise.
 191        """
 192        for defn in definitions:
 193            if not (type (defn) is TupleType and
 194                    (len (defn) == 1 or
 195                     (len (defn) == 2 and
 196                      (type (defn[1]) is StringType or defn[1] is None))) and
 197                    type (defn[0]) is StringType):
 198                raise TypeError, \
 199                      ("invalid macro definition '%s': " % defn) + \
 200                      "must be tuple (string,), (string, string), or " + \
 201                      "(string, None)"
 202
 203
 204    # -- Bookkeeping methods -------------------------------------------
 205
 206    def define_macro (self, name, value=None):
 207        """Define a preprocessor macro for all compilations driven by this
 208        compiler object.  The optional parameter 'value' should be a
 209        string; if it is not supplied, then the macro will be defined
 210        without an explicit value and the exact outcome depends on the
 211        compiler used (XXX true? does ANSI say anything about this?)
 212        """
 213        # Delete from the list of macro definitions/undefinitions if
 214        # already there (so that this one will take precedence).
 215        i = self._find_macro (name)
 216        if i is not None:
 217            del self.macros[i]
 218
 219        defn = (name, value)
 220        self.macros.append (defn)
 221
 222
 223    def undefine_macro (self, name):
 224        """Undefine a preprocessor macro for all compilations driven by
 225        this compiler object.  If the same macro is defined by
 226        'define_macro()' and undefined by 'undefine_macro()' the last call
 227        takes precedence (including multiple redefinitions or
 228        undefinitions).  If the macro is redefined/undefined on a
 229        per-compilation basis (ie. in the call to 'compile()'), then that
 230        takes precedence.
 231        """
 232        # Delete from the list of macro definitions/undefinitions if
 233        # already there (so that this one will take precedence).
 234        i = self._find_macro (name)
 235        if i is not None:
 236            del self.macros[i]
 237
 238        undefn = (name,)
 239        self.macros.append (undefn)
 240
 241
 242    def add_include_dir (self, dir):
 243        """Add 'dir' to the list of directories that will be searched for
 244        header files.  The compiler is instructed to search directories in
 245        the order in which they are supplied by successive calls to
 246        'add_include_dir()'.
 247        """
 248        self.include_dirs.append (dir)
 249
 250    def set_include_dirs (self, dirs):
 251        """Set the list of directories that will be searched to 'dirs' (a
 252        list of strings).  Overrides any preceding calls to
 253        'add_include_dir()'; subsequence calls to 'add_include_dir()' add
 254        to the list passed to 'set_include_dirs()'.  This does not affect
 255        any list of standard include directories that the compiler may
 256        search by default.
 257        """
 258        self.include_dirs = copy (dirs)
 259
 260
 261    def add_library (self, libname):
 262        """Add 'libname' to the list of libraries that will be included in
 263        all links driven by this compiler object.  Note that 'libname'
 264        should *not* be the name of a file containing a library, but the
 265        name of the library itself: the actual filename will be inferred by
 266        the linker, the compiler, or the compiler class (depending on the
 267        platform).
 268
 269        The linker will be instructed to link against libraries in the
 270        order they were supplied to 'add_library()' and/or
 271        'set_libraries()'.  It is perfectly valid to duplicate library
 272        names; the linker will be instructed to link against libraries as
 273        many times as they are mentioned.
 274        """
 275        self.libraries.append (libname)
 276
 277    def set_libraries (self, libnames):
 278        """Set the list of libraries to be included in all links driven by
 279        this compiler object to 'libnames' (a list of strings).  This does
 280        not affect any standard system libraries that the linker may
 281        include by default.
 282        """
 283        self.libraries = copy (libnames)
 284
 285
 286    def add_library_dir (self, dir):
 287        """Add 'dir' to the list of directories that will be searched for
 288        libraries specified to 'add_library()' and 'set_libraries()'.  The
 289        linker will be instructed to search for libraries in the order they
 290        are supplied to 'add_library_dir()' and/or 'set_library_dirs()'.
 291        """
 292        self.library_dirs.append (dir)
 293
 294    def set_library_dirs (self, dirs):
 295        """Set the list of library search directories to 'dirs' (a list of
 296        strings).  This does not affect any standard library search path
 297        that the linker may search by default.
 298        """
 299        self.library_dirs = copy (dirs)
 300
 301
 302    def add_runtime_library_dir (self, dir):
 303        """Add 'dir' to the list of directories that will be searched for
 304        shared libraries at runtime.
 305        """
 306        self.runtime_library_dirs.append (dir)
 307
 308    def set_runtime_library_dirs (self, dirs):
 309        """Set the list of directories to search for shared libraries at
 310        runtime to 'dirs' (a list of strings).  This does not affect any
 311        standard search path that the runtime linker may search by
 312        default.
 313        """
 314        self.runtime_library_dirs = copy (dirs)
 315
 316
 317    def add_link_object (self, object):
 318        """Add 'object' to the list of object files (or analogues, such as
 319        explicitly named library files or the output of "resource
 320        compilers") to be included in every link driven by this compiler
 321        object.
 322        """
 323        self.objects.append (object)
 324
 325    def set_link_objects (self, objects):
 326        """Set the list of object files (or analogues) to be included in
 327        every link to 'objects'.  This does not affect any standard object
 328        files that the linker may include by default (such as system
 329        libraries).
 330        """
 331        self.objects = copy (objects)
 332
 333
 334    # -- Private utility methods --------------------------------------
 335    # (here for the convenience of subclasses)
 336
 337    # Helper method to prep compiler in subclass compile() methods
 338
 339    def _setup_compile(self, outdir, macros, incdirs, sources, depends,
 340                       extra):
 341        """Process arguments and decide which source files to compile.
 342
 343        Merges _fix_compile_args() and _prep_compile().
 344        """
 345        if outdir is None:
 346            outdir = self.output_dir
 347        elif type(outdir) is not StringType:
 348            raise TypeError, "'output_dir' must be a string or None"
 349
 350        if macros is None:
 351            macros = self.macros
 352        elif type(macros) is ListType:
 353            macros = macros + (self.macros or [])
 354        else:
 355            raise TypeError, "'macros' (if supplied) must be a list of tuples"
 356
 357        if incdirs is None:
 358            incdirs = self.include_dirs
 359        elif type(incdirs) in (ListType, TupleType):
 360            incdirs = list(incdirs) + (self.include_dirs or [])
 361        else:
 362            raise TypeError, \
 363                  "'include_dirs' (if supplied) must be a list of strings"
 364
 365        if extra is None:
 366            extra = []
 367
 368        # Get the list of expected output (object) files
 369        objects = self.object_filenames(sources,
 370                                        strip_dir=0,
 371                                        output_dir=outdir)
 372        assert len(objects) == len(sources)
 373
 374        pp_opts = gen_preprocess_options(macros, incdirs)
 375
 376        build = {}
 377        for i in range(len(sources)):
 378            src = sources[i]
 379            obj = objects[i]
 380            ext = os.path.splitext(src)[1]
 381            self.mkpath(os.path.dirname(obj))
 382            build[obj] = (src, ext)
 383
 384        return macros, objects, extra, pp_opts, build
 385
 386    def _get_cc_args(self, pp_opts, debug, before):
 387        # works for unixccompiler, emxccompiler, cygwinccompiler
 388        cc_args = pp_opts + ['-c']
 389        if debug:
 390            cc_args[:0] = ['-g']
 391        if before:
 392            cc_args[:0] = before
 393        return cc_args
 394
 395    def _fix_compile_args (self, output_dir, macros, include_dirs):
 396        """Typecheck and fix-up some of the arguments to the 'compile()'
 397        method, and return fixed-up values.  Specifically: if 'output_dir'
 398        is None, replaces it with 'self.output_dir'; ensures that 'macros'
 399        is a list, and augments it with 'self.macros'; ensures that
 400        'include_dirs' is a list, and augments it with 'self.include_dirs'.
 401        Guarantees that the returned values are of the correct type,
 402        i.e. for 'output_dir' either string or None, and for 'macros' and
 403        'include_dirs' either list or None.
 404        """
 405        if output_dir is None:
 406            output_dir = self.output_dir
 407        elif type (output_dir) is not StringType:
 408            raise TypeError, "'output_dir' must be a string or None"
 409
 410        if macros is None:
 411            macros = self.macros
 412        elif type (macros) is ListType:
 413            macros = macros + (self.macros or [])
 414        else:
 415            raise TypeError, "'macros' (if supplied) must be a list of tuples"
 416
 417        if include_dirs is None:
 418            include_dirs = self.include_dirs
 419        elif type (include_dirs) in (ListType, TupleType):
 420            include_dirs = list (include_dirs) + (self.include_dirs or [])
 421        else:
 422            raise TypeError, \
 423                  "'include_dirs' (if supplied) must be a list of strings"
 424
 425        return output_dir, macros, include_dirs
 426
 427    # _fix_compile_args ()
 428
 429
 430    def _prep_compile(self, sources, output_dir, depends=None):
 431        """Decide which souce files must be recompiled.
 432
 433        Determine the list of object files corresponding to 'sources',
 434        and figure out which ones really need to be recompiled.
 435        Return a list of all object files and a dictionary telling
 436        which source files can be skipped.
 437        """
 438        # Get the list of expected output (object) files
 439        objects = self.object_filenames(sources, output_dir=output_dir)
 440        assert len(objects) == len(sources)
 441
 442        if self.force:
 443            skip_source = {}            # rebuild everything
 444            for source in sources:
 445                skip_source[source] = 0
 446        elif depends is None:
 447            # If depends is None, figure out which source files we
 448            # have to recompile according to a simplistic check. We
 449            # just compare the source and object file, no deep
 450            # dependency checking involving header files.
 451            skip_source = {}            # rebuild everything
 452            for source in sources:      # no wait, rebuild nothing
 453                skip_source[source] = 1
 454
 455            n_sources, n_objects = newer_pairwise(sources, objects)
 456            for source in n_sources:    # no really, only rebuild what's
 457                skip_source[source] = 0 # out-of-date
 458        else:
 459            # If depends is a list of files, then do a different
 460            # simplistic check.  Assume that each object depends on
 461            # its source and all files in the depends list.
 462            skip_source = {}
 463            # L contains all the depends plus a spot at the end for a
 464            # particular source file
 465            L = depends[:] + [None]
 466            for i in range(len(objects)):
 467                source = sources[i]
 468                L[-1] = source
 469                if newer_group(L, objects[i]):
 470                    skip_source[source] = 0
 471                else:
 472                    skip_source[source] = 1
 473
 474        return objects, skip_source
 475
 476    # _prep_compile ()
 477
 478
 479    def _fix_object_args (self, objects, output_dir):
 480        """Typecheck and fix up some arguments supplied to various methods.
 481        Specifically: ensure that 'objects' is a list; if output_dir is
 482        None, replace with self.output_dir.  Return fixed versions of
 483        'objects' and 'output_dir'.
 484        """
 485        if type (objects) not in (ListType, TupleType):
 486            raise TypeError, \
 487                  "'objects' must be a list or tuple of strings"
 488        objects = list (objects)
 489
 490        if output_dir is None:
 491            output_dir = self.output_dir
 492        elif type (output_dir) is not StringType:
 493            raise TypeError, "'output_dir' must be a string or None"
 494
 495        return (objects, output_dir)
 496
 497
 498    def _fix_lib_args (self, libraries, library_dirs, runtime_library_dirs):
 499        """Typecheck and fix up some of the arguments supplied to the
 500        'link_*' methods.  Specifically: ensure that all arguments are
 501        lists, and augment them with their permanent versions
 502        (eg. 'self.libraries' augments 'libraries').  Return a tuple with
 503        fixed versions of all arguments.
 504        """
 505        if libraries is None:
 506            libraries = self.libraries
 507        elif type (libraries) in (ListType, TupleType):
 508            libraries = list (libraries) + (self.libraries or [])
 509        else:
 510            raise TypeError, \
 511                  "'libraries' (if supplied) must be a list of strings"
 512
 513        if library_dirs is None:
 514            library_dirs = self.library_dirs
 515        elif type (library_dirs) in (ListType, TupleType):
 516            library_dirs = list (library_dirs) + (self.library_dirs or [])
 517        else:
 518            raise TypeError, \
 519                  "'library_dirs' (if supplied) must be a list of strings"
 520
 521        if runtime_library_dirs is None:
 522            runtime_library_dirs = self.runtime_library_dirs
 523        elif type (runtime_library_dirs) in (ListType, TupleType):
 524            runtime_library_dirs = (list (runtime_library_dirs) +
 525                                    (self.runtime_library_dirs or []))
 526        else:
 527            raise TypeError, \
 528                  "'runtime_library_dirs' (if supplied) " + \
 529                  "must be a list of strings"
 530
 531        return (libraries, library_dirs, runtime_library_dirs)
 532
 533    # _fix_lib_args ()
 534
 535
 536    def _need_link (self, objects, output_file):
 537        """Return true if we need to relink the files listed in 'objects'
 538        to recreate 'output_file'.
 539        """
 540        if self.force:
 541            return 1
 542        else:
 543            if self.dry_run:
 544                newer = newer_group (objects, output_file, missing='newer')
 545            else:
 546                newer = newer_group (objects, output_file)
 547            return newer
 548
 549    # _need_link ()
 550
 551    def detect_language (self, sources):
 552        """Detect the language of a given file, or list of files. Uses
 553        language_map, and language_order to do the job.
 554        """
 555        if type(sources) is not ListType:
 556            sources = [sources]
 557        lang = None
 558        index = len(self.language_order)
 559        for source in sources:
 560            base, ext = os.path.splitext(source)
 561            extlang = self.language_map.get(ext)
 562            try:
 563                extindex = self.language_order.index(extlang)
 564                if extindex < index:
 565                    lang = extlang
 566                    index = extindex
 567            except ValueError:
 568                pass
 569        return lang
 570
 571    # detect_language ()
 572
 573    # -- Worker methods ------------------------------------------------
 574    # (must be implemented by subclasses)
 575
 576    def preprocess (self,
 577                    source,
 578                    output_file=None,
 579                    macros=None,
 580                    include_dirs=None,
 581                    extra_preargs=None,
 582                    extra_postargs=None):
 583        """Preprocess a single C/C++ source file, named in 'source'.
 584        Output will be written to file named 'output_file', or stdout if
 585        'output_file' not supplied.  'macros' is a list of macro
 586        definitions as for 'compile()', which will augment the macros set
 587        with 'define_macro()' and 'undefine_macro()'.  'include_dirs' is a
 588        list of directory names that will be added to the default list.
 589
 590        Raises PreprocessError on failure.
 591        """
 592        pass
 593
 594    def compile(self, sources, output_dir=None, macros=None,
 595                include_dirs=None, debug=0, extra_preargs=None,
 596                extra_postargs=None, depends=None):
 597        """Compile one or more source files.
 598
 599        'sources' must be a list of filenames, most likely C/C++
 600        files, but in reality anything that can be handled by a
 601        particular compiler and compiler class (eg. MSVCCompiler can
 602        handle resource files in 'sources').  Return a list of object
 603        filenames, one per source filename in 'sources'.  Depending on
 604        the implementation, not all source files will necessarily be
 605        compiled, but all corresponding object filenames will be
 606        returned.
 607
 608        If 'output_dir' is given, object files will be put under it, while
 609        retaining their original path component.  That is, "foo/bar.c"
 610        normally compiles to "foo/bar.o" (for a Unix implementation); if
 611        'output_dir' is "build", then it would compile to
 612        "build/foo/bar.o".
 613
 614        'macros', if given, must be a list of macro definitions.  A macro
 615        definition is either a (name, value) 2-tuple or a (name,) 1-tuple.
 616        The former defines a macro; if the value is None, the macro is
 617        defined without an explicit value.  The 1-tuple case undefines a
 618        macro.  Later definitions/redefinitions/ undefinitions take
 619        precedence.
 620
 621        'include_dirs', if given, must be a list of strings, the
 622        directories to add to the default include file search path for this
 623        compilation only.
 624
 625        'debug' is a boolean; if true, the compiler will be instructed to
 626        output debug symbols in (or alongside) the object file(s).
 627
 628        'extra_preargs' and 'extra_postargs' are implementation- dependent.
 629        On platforms that have the notion of a command-line (e.g. Unix,
 630        DOS/Windows), they are most likely lists of strings: extra
 631        command-line arguments to prepand/append to the compiler command
 632        line.  On other platforms, consult the implementation class
 633        documentation.  In any event, they are intended as an escape hatch
 634        for those occasions when the abstract compiler framework doesn't
 635        cut the mustard.
 636
 637        'depends', if given, is a list of filenames that all targets
 638        depend on.  If a source file is older than any file in
 639        depends, then the source file will be recompiled.  This
 640        supports dependency tracking, but only at a coarse
 641        granularity.
 642
 643        Raises CompileError on failure.
 644        """
 645
 646        # A concrete compiler class can either override this method
 647        # entirely or implement _compile().
 648
 649        macros, objects, extra_postargs, pp_opts, build = \
 650                self._setup_compile(output_dir, macros, include_dirs, sources,
 651                                    depends, extra_postargs)
 652        cc_args = self._get_cc_args(pp_opts, debug, extra_preargs)
 653
 654        for obj in objects:
 655            try:
 656                src, ext = build[obj]
 657            except KeyError:
 658                continue
 659            self._compile(obj, src, ext, cc_args, extra_postargs, pp_opts)
 660
 661        # Return *all* object filenames, not just the ones we just built.
 662        return objects
 663
 664    def _compile(self, obj, src, ext, cc_args, extra_postargs, pp_opts):
 665        """Compile 'src' to product 'obj'."""
 666
 667        # A concrete compiler class that does not override compile()
 668        # should implement _compile().
 669        pass
 670
 671    def create_static_lib (self,
 672                           objects,
 673                           output_libname,
 674                           output_dir=None,
 675                           debug=0,
 676                           target_lang=None):
 677        """Link a bunch of stuff together to create a static library file.
 678        The "bunch of stuff" consists of the list of object files supplied
 679        as 'objects', the extra object files supplied to
 680        'add_link_object()' and/or 'set_link_objects()', the libraries
 681        supplied to 'add_library()' and/or 'set_libraries()', and the
 682        libraries supplied as 'libraries' (if any).
 683
 684        'output_libname' should be a library name, not a filename; the
 685        filename will be inferred from the library name.  'output_dir' is
 686        the directory where the library file will be put.
 687
 688        'debug' is a boolean; if true, debugging information will be
 689        included in the library (note that on most platforms, it is the
 690        compile step where this matters: the 'debug' flag is included here
 691        just for consistency).
 692
 693        'target_lang' is the target language for which the given objects
 694        are being compiled. This allows specific linkage time treatment of
 695        certain languages.
 696
 697        Raises LibError on failure.
 698        """
 699        pass
 700
 701
 702    # values for target_desc parameter in link()
 703    SHARED_OBJECT = "shared_object"
 704    SHARED_LIBRARY = "shared_library"
 705    EXECUTABLE = "executable"
 706
 707    def link (self,
 708              target_desc,
 709              objects,
 710              output_filename,
 711              output_dir=None,
 712              libraries=None,
 713              library_dirs=None,
 714              runtime_library_dirs=None,
 715              export_symbols=None,
 716              debug=0,
 717              extra_preargs=None,
 718              extra_postargs=None,
 719              build_temp=None,
 720              target_lang=None):
 721        """Link a bunch of stuff together to create an executable or
 722        shared library file.
 723
 724        The "bunch of stuff" consists of the list of object files supplied
 725        as 'objects'.  'output_filename' should be a filename.  If
 726        'output_dir' is supplied, 'output_filename' is relative to it
 727        (i.e. 'output_filename' can provide directory components if
 728        needed).
 729
 730        'libraries' is a list of libraries to link against.  These are
 731        library names, not filenames, since they're translated into
 732        filenames in a platform-specific way (eg. "foo" becomes "libfoo.a"
 733        on Unix and "foo.lib" on DOS/Windows).  However, they can include a
 734        directory component, which means the linker will look in that
 735        specific directory rather than searching all the normal locations.
 736
 737        'library_dirs', if supplied, should be a list of directories to
 738        search for libraries that were specified as bare library names
 739        (ie. no directory component).  These are on top of the system
 740        default and those supplied to 'add_library_dir()' and/or
 741        'set_library_dirs()'.  'runtime_library_dirs' is a list of
 742        directories that will be embedded into the shared library and used
 743        to search for other shared libraries that *it* depends on at
 744        run-time.  (This may only be relevant on Unix.)
 745
 746        'export_symbols' is a list of symbols that the shared library will
 747        export.  (This appears to be relevant only on Windows.)
 748
 749        'debug' is as for 'compile()' and 'create_static_lib()', with the
 750        slight distinction that it actually matters on most platforms (as
 751        opposed to 'create_static_lib()', which includes a 'debug' flag
 752        mostly for form's sake).
 753
 754        'extra_preargs' and 'extra_postargs' are as for 'compile()' (except
 755        of course that they supply command-line arguments for the
 756        particular linker being used).
 757
 758        'target_lang' is the target language for which the given objects
 759        are being compiled. This allows specific linkage time treatment of
 760        certain languages.
 761
 762        Raises LinkError on failure.
 763        """
 764        raise NotImplementedError
 765
 766
 767    # Old 'link_*()' methods, rewritten to use the new 'link()' method.
 768
 769    def link_shared_lib (self,
 770                         objects,
 771                         output_libname,
 772                         output_dir=None,
 773                         libraries=None,
 774                         library_dirs=None,
 775                         runtime_library_dirs=None,
 776                         export_symbols=None,
 777                         debug=0,
 778                         extra_preargs=None,
 779                         extra_postargs=None,
 780                         build_temp=None,
 781                         target_lang=None):
 782        self.link(CCompiler.SHARED_LIBRARY, objects,
 783                  self.library_filename(output_libname, lib_type='shared'),
 784                  output_dir,
 785                  libraries, library_dirs, runtime_library_dirs,
 786                  export_symbols, debug,
 787                  extra_preargs, extra_postargs, build_temp, target_lang)
 788
 789
 790    def link_shared_object (self,
 791                            objects,
 792                            output_filename,
 793                            output_dir=None,
 794                            libraries=None,
 795                            library_dirs=None,
 796                            runtime_library_dirs=None,
 797                            export_symbols=None,
 798                            debug=0,
 799                            extra_preargs=None,
 800                            extra_postargs=None,
 801                            build_temp=None,
 802                            target_lang=None):
 803        self.link(CCompiler.SHARED_OBJECT, objects,
 804                  output_filename, output_dir,
 805                  libraries, library_dirs, runtime_library_dirs,
 806                  export_symbols, debug,
 807                  extra_preargs, extra_postargs, build_temp, target_lang)
 808
 809
 810    def link_executable (self,
 811                         objects,
 812                         output_progname,
 813                         output_dir=None,
 814                         libraries=None,
 815                         library_dirs=None,
 816                         runtime_library_dirs=None,
 817                         debug=0,
 818                         extra_preargs=None,
 819                         extra_postargs=None,
 820                         target_lang=None):
 821        self.link(CCompiler.EXECUTABLE, objects,
 822                  self.executable_filename(output_progname), output_dir,
 823                  libraries, library_dirs, runtime_library_dirs, None,
 824                  debug, extra_preargs, extra_postargs, None, target_lang)
 825
 826
 827    # -- Miscellaneous methods -----------------------------------------
 828    # These are all used by the 'gen_lib_options() function; there is
 829    # no appropriate default implementation so subclasses should
 830    # implement all of these.
 831
 832    def library_dir_option (self, dir):
 833        """Return the compiler option to add 'dir' to the list of
 834        directories searched for libraries.
 835        """
 836        raise NotImplementedError
 837
 838    def runtime_library_dir_option (self, dir):
 839        """Return the compiler option to add 'dir' to the list of
 840        directories searched for runtime libraries.
 841        """
 842        raise NotImplementedError
 843
 844    def library_option (self, lib):
 845        """Return the compiler option to add 'dir' to the list of libraries
 846        linked into the shared library or executable.
 847        """
 848        raise NotImplementedError
 849
 850    def has_function(self, funcname,
 851                     includes=None,
 852                     include_dirs=None,
 853                     libraries=None,
 854                     library_dirs=None):
 855        """Return a boolean indicating whether funcname is supported on
 856        the current platform.  The optional arguments can be used to
 857        augment the compilation environment.
 858        """
 859
 860        # this can't be included at module scope because it tries to
 861        # import math which might not be available at that point - maybe
 862        # the necessary logic should just be inlined?
 863        import tempfile
 864        if includes is None:
 865            includes = []
 866        if include_dirs is None:
 867            include_dirs = []
 868        if libraries is None:
 869            libraries = []
 870        if library_dirs is None:
 871            library_dirs = []
 872        fd, fname = tempfile.mkstemp(".c", funcname, text=True)
 873        f = os.fdopen(fd, "w")
 874        for incl in includes:
 875            f.write("""#include "%s"\n""" % incl)
 876        f.write("""\
 877main (int argc, char **argv) {
 878    %s();
 879}
 880""" % funcname)
 881        f.close()
 882        try:
 883            objects = self.compile([fname], include_dirs=include_dirs)
 884        except CompileError:
 885            return False
 886
 887        try:
 888            self.link_executable(objects, "a.out",
 889                                 libraries=libraries,
 890                                 library_dirs=library_dirs)
 891        except (LinkError, TypeError):
 892            return False
 893        return True
 894
 895    def find_library_file (self, dirs, lib, debug=0):
 896        """Search the specified list of directories for a static or shared
 897        library file 'lib' and return the full path to that file.  If
 898        'debug' true, look for a debugging version (if that makes sense on
 899        the current platform).  Return None if 'lib' wasn't found in any of
 900        the specified directories.
 901        """
 902        raise NotImplementedError
 903
 904    # -- Filename generation methods -----------------------------------
 905
 906    # The default implementation of the filename generating methods are
 907    # prejudiced towards the Unix/DOS/Windows view of the world:
 908    #   * object files are named by replacing the source file extension
 909    #     (eg. .c/.cpp -> .o/.obj)
 910    #   * library files (shared or static) are named by plugging the
 911    #     library name and extension into a format string, eg.
 912    #     "lib%s.%s" % (lib_name, ".a") for Unix static libraries
 913    #   * executables are named by appending an extension (possibly
 914    #     empty) to the program name: eg. progname + ".exe" for
 915    #     Windows
 916    #
 917    # To reduce redundant code, these methods expect to find
 918    # several attributes in the current object (presumably defined
 919    # as class attributes):
 920    #   * src_extensions -
 921    #     list of C/C++ source file extensions, eg. ['.c', '.cpp']
 922    #   * obj_extension -
 923    #     object file extension, eg. '.o' or '.obj'
 924    #   * static_lib_extension -
 925    #     extension for static library files, eg. '.a' or '.lib'
 926    #   * shared_lib_extension -
 927    #     extension for shared library/object files, eg. '.so', '.dll'
 928    #   * static_lib_format -
 929    #     format string for generating static library filenames,
 930    #     eg. 'lib%s.%s' or '%s.%s'
 931    #   * shared_lib_format
 932    #     format string for generating shared library filenames
 933    #     (probably same as static_lib_format, since the extension
 934    #     is one of the intended parameters to the format string)
 935    #   * exe_extension -
 936    #     extension for executable files, eg. '' or '.exe'
 937
 938    def object_filenames(self, source_filenames, strip_dir=0, output_dir=''):
 939        if output_dir is None:
 940            output_dir = ''
 941        obj_names = []
 942        for src_name in source_filenames:
 943            base, ext = os.path.splitext(src_name)
 944            base = os.path.splitdrive(base)[1] # Chop off the drive
 945            base = base[os.path.isabs(base):]  # If abs, chop off leading /
 946            if ext not in self.src_extensions:
 947                raise UnknownFileError, \
 948                      "unknown file type '%s' (from '%s')" % (ext, src_name)
 949            if strip_dir:
 950                base = os.path.basename(base)
 951            obj_names.append(os.path.join(output_dir,
 952                                          base + self.obj_extension))
 953        return obj_names
 954
 955    def shared_object_filename(self, basename, strip_dir=0, output_dir=''):
 956        assert output_dir is not None
 957        if strip_dir:
 958            basename = os.path.basename (basename)
 959        return os.path.join(output_dir, basename + self.shared_lib_extension)
 960
 961    def executable_filename(self, basename, strip_dir=0, output_dir=''):
 962        assert output_dir is not None
 963        if strip_dir:
 964            basename = os.path.basename (basename)
 965        return os.path.join(output_dir, basename + (self.exe_extension or ''))
 966
 967    def library_filename(self, libname, lib_type='static',     # or 'shared'
 968                         strip_dir=0, output_dir=''):
 969        assert output_dir is not None
 970        if lib_type not in ("static", "shared", "dylib"):
 971            raise ValueError, "'lib_type' must be \"static\", \"shared\" or \"dylib\""
 972        fmt = getattr(self, lib_type + "_lib_format")
 973        ext = getattr(self, lib_type + "_lib_extension")
 974
 975        dir, base = os.path.split (libname)
 976        filename = fmt % (base, ext)
 977        if strip_dir:
 978            dir = ''
 979
 980        return os.path.join(output_dir, dir, filename)
 981
 982
 983    # -- Utility methods -----------------------------------------------
 984
 985    def announce (self, msg, level=1):
 986        log.debug(msg)
 987
 988    def debug_print (self, msg):
 989        from distutils.debug import DEBUG
 990        if DEBUG:
 991            print msg
 992
 993    def warn (self, msg):
 994        sys.stderr.write ("warning: %s\n" % msg)
 995
 996    def execute (self, func, args, msg=None, level=1):
 997        execute(func, args, msg, self.dry_run)
 998
 999    def spawn (self, cmd):
1000        spawn (cmd, dry_run=self.dry_run)
1001
1002    def move_file (self, src, dst):
1003        return move_file (src, dst, dry_run=self.dry_run)
1004
1005    def mkpath (self, name, mode=0777):
1006        mkpath (name, mode, dry_run=self.dry_run)
1007
1008
1009# class CCompiler
1010
1011
1012# Map a sys.platform/os.name ('posix', 'nt') to the default compiler
1013# type for that platform. Keys are interpreted as re match
1014# patterns. Order is important; platform mappings are preferred over
1015# OS names.
1016_default_compilers = (
1017
1018    # Platform string mappings
1019
1020    # on a cygwin built python we can use gcc like an ordinary UNIXish
1021    # compiler
1022    ('cygwin.*', 'unix'),
1023    ('os2emx', 'emx'),
1024
1025    # OS name mappings
1026    ('posix', 'unix'),
1027    ('nt', 'msvc'),
1028    ('mac', 'mwerks'),
1029
1030    )
1031
1032def get_default_compiler(osname=None, platform=None):
1033
1034    """ Determine the default compiler to use for the given platform.
1035
1036        osname should be one of the standard Python OS names (i.e. the
1037        ones returned by os.name) and platform the common value
1038        returned by sys.platform for the platform in question.
1039
1040        The default values are os.name and sys.platform in case the
1041        parameters are not given.
1042
1043    """
1044    if osname is None:
1045        osname = os.name
1046    if platform is None:
1047        platform = sys.platform
1048    for pattern, compiler in _default_compilers:
1049        if re.match(pattern, platform) is not None or \
1050           re.match(pattern, osname) is not None:
1051            return compiler
1052    # Default to Unix compiler
1053    return 'unix'
1054
1055# Map compiler types to (module_name, class_name) pairs -- ie. where to
1056# find the code that implements an interface to this compiler.  (The module
1057# is assumed to be in the 'distutils' package.)
1058compiler_class = { 'unix':    ('unixccompiler', 'UnixCCompiler',
1059                               "standard UNIX-style compiler"),
1060                   'msvc':    ('msvccompiler', 'MSVCCompiler',
1061                               "Microsoft Visual C++"),
1062                   'cygwin':  ('cygwinccompiler', 'CygwinCCompiler',
1063                               "Cygwin port of GNU C Compiler for Win32"),
1064                   'mingw32': ('cygwinccompiler', 'Mingw32CCompiler',
1065                               "Mingw32 port of GNU C Compiler for Win32"),
1066                   'bcpp':    ('bcppcompiler', 'BCPPCompiler',
1067                               "Borland C++ Compiler"),
1068                   'mwerks':  ('mwerkscompiler', 'MWerksCompiler',
1069                               "MetroWerks CodeWarrior"),
1070                   'emx':     ('emxccompiler', 'EMXCCompiler',
1071                               "EMX port of GNU C Compiler for OS/2"),
1072                 }
1073
1074def show_compilers():
1075    """Print list of available compilers (used by the "--help-compiler"
1076    options to "build", "build_ext", "build_clib").
1077    """
1078    # XXX this "knows" that the compiler option it's describing is
1079    # "--compiler", which just happens to be the case for the three
1080    # commands that use it.
1081    from distutils.fancy_getopt import FancyGetopt
1082    compilers = []
1083    for compiler in compiler_class.keys():
1084        compilers.append(("compiler="+compiler, None,
1085                          compiler_class[compiler][2]))
1086    compilers.sort()
1087    pretty_printer = FancyGetopt(compilers)
1088    pretty_printer.print_help("List of available compilers:")
1089
1090
1091def new_compiler (plat=None,
1092                  compiler=None,
1093                  verbose=0,
1094                  dry_run=0,
1095                  force=0):
1096    """Generate an instance of some CCompiler subclass for the supplied
1097    platform/compiler combination.  'plat' defaults to 'os.name'
1098    (eg. 'posix', 'nt'), and 'compiler' defaults to the default compiler
1099    for that platform.  Currently only 'posix' and 'nt' are supported, and
1100    the default compilers are "traditional Unix interface" (UnixCCompiler
1101    class) and Visual C++ (MSVCCompiler class).  Note that it's perfectly
1102    possible to ask for a Unix compiler object under Windows, and a
1103    Microsoft compiler object under Unix -- if you supply a value for
1104    'compiler', 'plat' is ignored.
1105    """
1106    if plat is None:
1107        plat = os.name
1108
1109    try:
1110        if compiler is None:
1111            compiler = get_default_compiler(plat)
1112
1113        (module_name, class_name, long_description) = compiler_class[compiler]
1114    except KeyError:
1115        msg = "don't know how to compile C/C++ code on platform '%s'" % plat
1116        if compiler is not None:
1117            msg = msg + " with '%s' compiler" % compiler
1118        raise DistutilsPlatformError, msg
1119
1120    try:
1121        module_name = "distutils." + module_name
1122        __import__ (module_name)
1123        module = sys.modules[module_name]
1124        klass = vars(module)[class_name]
1125    except ImportError:
1126        raise DistutilsModuleError, \
1127              "can't compile C/C++ code: unable to load module '%s'" % \
1128              module_name
1129    except KeyError:
1130        raise DistutilsModuleError, \
1131              ("can't compile C/C++ code: unable to find class '%s' " +
1132               "in module '%s'") % (class_name, module_name)
1133
1134    # XXX The None is necessary to preserve backwards compatibility
1135    # with classes that expect verbose to be the first positional
1136    # argument.
1137    return klass (None, dry_run, force)
1138
1139
1140def gen_preprocess_options (macros, include_dirs):
1141    """Generate C pre-processor options (-D, -U, -I) as used by at least
1142    two types of compilers: the typical Unix compiler and Visual C++.
1143    'macros' is the usual thing, a list of 1- or 2-tuples, where (name,)
1144    means undefine (-U) macro 'name', and (name,value) means define (-D)
1145    macro 'name' to 'value'.  'include_dirs' is just a list of directory
1146    names to be added to the header file search path (-I).  Returns a list
1147    of command-line options suitable for either Unix compilers or Visual
1148    C++.
1149    """
1150    # XXX it would be nice (mainly aesthetic, and so we don't generate
1151    # stupid-looking command lines) to go over 'macros' and eliminate
1152    # redundant definitions/undefinitions (ie. ensure that only the
1153    # latest mention of a particular macro winds up on the command
1154    # line).  I don't think it's essential, though, since most (all?)
1155    # Unix C compilers only pay attention to the latest -D or -U
1156    # mention of a macro on their command line.  Similar situation for
1157    # 'include_dirs'.  I'm punting on both for now.  Anyways, weeding out
1158    # redundancies like this should probably be the province of
1159    # CCompiler, since the data structures used are inherited from it
1160    # and therefore common to all CCompiler classes.
1161
1162    pp_opts = []
1163    for macro in macros:
1164
1165        if not (type (macro) is TupleType and
1166                1 <= len (macro) <= 2):
1167            raise TypeError, \
1168                  ("bad macro definition '%s': " +
1169                   "each element of 'macros' list must be a 1- or 2-tuple") % \
1170                  macro
1171
1172        if len (macro) == 1:        # undefine this macro
1173            pp_opts.append ("-U%s" % macro[0])
1174        elif len (macro) == 2:
1175            if macro[1] is None:    # define with no explicit value
1176                pp_opts.append ("-D%s" % macro[0])
1177            else:
1178                # XXX *don't* need to be clever about quoting the
1179                # macro value here, because we're going to avoid the
1180                # shell at all costs when we spawn the command!
1181                pp_opts.append ("-D%s=%s" % macro)
1182
1183    for dir in include_dirs:
1184        pp_opts.append ("-I%s" % dir)
1185
1186    return pp_opts
1187
1188# gen_preprocess_options ()
1189
1190
1191def gen_lib_options (compiler, library_dirs, runtime_library_dirs, libraries):
1192    """Generate linker options for searching library directories and
1193    linking with specific libraries.  'libraries' and 'library_dirs' are,
1194    respectively, lists of library names (not filenames!) and search
1195    directories.  Returns a list of command-line options suitable for use
1196    with some compiler (depending on the two format strings passed in).
1197    """
1198    lib_opts = []
1199
1200    for dir in library_dirs:
1201        lib_opts.append (compiler.library_dir_option (dir))
1202
1203    for dir in runtime_library_dirs:
1204        opt = compiler.runtime_library_dir_option (dir)
1205        if type(opt) is ListType:
1206            lib_opts = lib_opts + opt
1207        else:
1208            lib_opts.append (opt)
1209
1210    # XXX it's important that we *not* remove redundant library mentions!
1211    # sometimes you really do have to say "-lfoo -lbar -lfoo" in order to
1212    # resolve all symbols.  I just hope we never have to say "-lfoo obj.o
1213    # -lbar" to get things to work -- that's certainly a possibility, but a
1214    # pretty nasty way to arrange your C code.
1215
1216    for lib in libraries:
1217        (lib_dir, lib_name) = os.path.split (lib)
1218        if lib_dir:
1219            lib_file = compiler.find_library_file ([lib_dir], lib_name)
1220            if lib_file:
1221          

Large files files are truncated, but you can click here to view the full file