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