PageRenderTime 216ms CodeModel.GetById 70ms app.highlight 99ms RepoModel.GetById 32ms app.codeStats 0ms

/lib-python/2/distutils/ccompiler.py

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