1 """distutils.ccompiler

     2 

     3 Contains CCompiler, an abstract base class that defines the interface

     4 for the Distutils compiler abstraction model."""

     5 

     6 # This module should be kept compatible with Python 2.1.

     7 

     8 __revision__ = "$Id: ccompiler.py 60923 2008-02-21 18:18:37Z guido.van.rossum $"

     9 

    10 import sys, os, re

    11 from types import *

    12 from copy import copy

    13 from distutils.errors import *

    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_pairwise, newer_group

    18 from distutils.util import split_quoted, execute

    19 from distutils import log

    20 

    21 class CCompiler:

    22     """Abstract base class to define the interface that must be implemented

    23     by real compiler classes.  Also has some utility methods used by

    24     several compiler classes.

    25 

    26     The basic idea behind a compiler abstraction class is that each

    27     instance can be used for all the compile/link steps in building a

    28     single project.  Thus, attributes common to all of those compile and

    29     link steps -- include directories, macros to define, libraries to link

    30     against, etc. -- are attributes of the compiler instance.  To allow for

    31     variability in how individual files are treated, most of those

    32     attributes may be varied on a per-compilation or per-link basis.

    33     """

    34 

    35     # 'compiler_type' is a class attribute that identifies this class.  It

    36     # keeps code that wants to know what kind of compiler it's dealing with

    37     # from having to import all possible compiler classes just to do an

    38     # 'isinstance'.  In concrete CCompiler subclasses, 'compiler_type'

    39     # should really, really be one of the keys of the 'compiler_class'

    40     # dictionary (see below -- used by the 'new_compiler()' factory

    41     # function) -- authors of new compiler interface classes are

    42     # responsible for updating 'compiler_class'!

    43     compiler_type = None

    44 

    45     # XXX things not handled by this compiler abstraction model:

    46     #   * client can't provide additional options for a compiler,

    47     #     e.g. warning, optimization, debugging flags.  Perhaps this

    48     #     should be the domain of concrete compiler abstraction classes

    49     #     (UnixCCompiler, MSVCCompiler, etc.) -- or perhaps the base

    50     #     class should have methods for the common ones.

    51     #   * can't completely override the include or library searchg

    52     #     path, ie. no "cc -I -Idir1 -Idir2" or "cc -L -Ldir1 -Ldir2".

    53     #     I'm not sure how widely supported this is even by Unix

    54     #     compilers, much less on other platforms.  And I'm even less

    55     #     sure how useful it is; maybe for cross-compiling, but

    56     #     support for that is a ways off.  (And anyways, cross

    57     #     compilers probably have a dedicated binary with the

    58     #     right paths compiled in.  I hope.)

    59     #   * can't do really freaky things with the library list/library

    60     #     dirs, e.g. "-Ldir1 -lfoo -Ldir2 -lfoo" to link against

    61     #     different versions of libfoo.a in different locations.  I

    62     #     think this is useless without the ability to null out the

    63     #     library search path anyways.

    64 

    65 

    66     # Subclasses that rely on the standard filename generation methods

    67     # implemented below should override these; see the comment near

    68     # those methods ('object_filenames()' et. al.) for details:

    69     src_extensions = None               # list of strings

    70     obj_extension = None                # string

    71     static_lib_extension = None

    72     shared_lib_extension = None         # string

    73     static_lib_format = None            # format string

    74     shared_lib_format = None            # prob. same as static_lib_format

    75     exe_extension = None                # string

    76 

    77     # Default language settings. language_map is used to detect a source

    78     # file or Extension target language, checking source filenames.

    79     # language_order is used to detect the language precedence, when deciding

    80     # what language to use when mixing source types. For example, if some

    81     # extension has two files with ".c" extension, and one with ".cpp", it

    82     # is still linked as c++.

    83     language_map = {".c"   : "c",

    84                     ".cc"  : "c++",

    85                     ".cpp" : "c++",

    86                     ".cxx" : "c++",

    87                     ".m"   : "objc",

    88                    }

    89     language_order = ["c++", "objc", "c"]

    90 

    91     def __init__ (self,

    92                   verbose=0,

    93                   dry_run=0,

    94                   force=0):

    95 

    96         self.dry_run = dry_run

    97         self.force = force

    98         self.verbose = verbose

    99 

   100         # 'output_dir': a common output directory for object, library,

   101         # shared object, and shared library files

   102         self.output_dir = None

   103 

   104         # 'macros': a list of macro definitions (or undefinitions).  A

   105         # macro definition is a 2-tuple (name, value), where the value is

   106         # either a string or None (no explicit value).  A macro

   107         # undefinition is a 1-tuple (name,).

   108         self.macros = []

   109 

   110         # 'include_dirs': a list of directories to search for include files

   111         self.include_dirs = []

   112 

   113         # 'libraries': a list of libraries to include in any link

   114         # (library names, not filenames: eg. "foo" not "libfoo.a")

   115         self.libraries = []

   116 

   117         # 'library_dirs': a list of directories to search for libraries

   118         self.library_dirs = []

   119 

   120         # 'runtime_library_dirs': a list of directories to search for

   121         # shared libraries/objects at runtime

   122         self.runtime_library_dirs = []

   123 

   124         # 'objects': a list of object files (or similar, such as explicitly

   125         # named library files) to include on any link

   126         self.objects = []

   127 

   128         for key in self.executables.keys():

   129             self.set_executable(key, self.executables[key])

   130 

   131     # __init__ ()

   132 

   133 

   134     def set_executables (self, **args):

   135 

   136         """Define the executables (and options for them) that will be run

   137         to perform the various stages of compilation.  The exact set of

   138         executables that may be specified here depends on the compiler

   139         class (via the 'executables' class attribute), but most will have:

   140           compiler      the C/C++ compiler

   141           linker_so     linker used to create shared objects and libraries

   142           linker_exe    linker used to create binary executables

   143           archiver      static library creator

   144 

   145         On platforms with a command-line (Unix, DOS/Windows), each of these

   146         is a string that will be split into executable name and (optional)

   147         list of arguments.  (Splitting the string is done similarly to how

   148         Unix shells operate: words are delimited by spaces, but quotes and

   149         backslashes can override this.  See

   150         'distutils.util.split_quoted()'.)

   151         """

   152 

   153         # Note that some CCompiler implementation classes will define class

   154         # attributes 'cpp', 'cc', etc. with hard-coded executable names;

   155         # this is appropriate when a compiler class is for exactly one

   156         # compiler/OS combination (eg. MSVCCompiler).  Other compiler

   157         # classes (UnixCCompiler, in particular) are driven by information

   158         # discovered at run-time, since there are many different ways to do

   159         # basically the same things with Unix C compilers.

   160 

   161         for key in args.keys():

   162             if key not in self.executables:

   163                 raise ValueError, \

   164                       "unknown executable '%s' for class %s" % \

   165                       (key, self.__class__.__name__)

   166             self.set_executable(key, args[key])

   167 

   168     # set_executables ()

   169 

   170     def set_executable(self, key, value):

   171         if type(value) is StringType:

   172             setattr(self, key, split_quoted(value))

   173         else:

   174             setattr(self, key, value)

   175 

   176 

   177     def _find_macro (self, name):

   178         i = 0

   179         for defn in self.macros:

   180             if defn[0] == name:

   181                 return i

   182             i = i + 1

   183 

   184         return None

   185 

   186 

   187     def _check_macro_definitions (self, definitions):

   188         """Ensures that every element of 'definitions' is a valid macro

   189         definition, ie. either (name,value) 2-tuple or a (name,) tuple.  Do

   190         nothing if all definitions are OK, raise TypeError otherwise.

   191         """

   192         for defn in definitions:

   193             if not (type (defn) is TupleType and

   194                     (len (defn) == 1 or

   195                      (len (defn) == 2 and

   196                       (type (defn[1]) is StringType or defn[1] is None))) and

   197                     type (defn[0]) is StringType):

   198                 raise TypeError, \

   199                       ("invalid macro definition '%s': " % defn) + \

   200                       "must be tuple (string,), (string, string), or " + \

   201                       "(string, None)"

   202 

   203 

   204     # -- Bookkeeping methods -------------------------------------------

   205 

   206     def define_macro (self, name, value=None):

   207         """Define a preprocessor macro for all compilations driven by this

   208         compiler object.  The optional parameter 'value' should be a

   209         string; if it is not supplied, then the macro will be defined

   210         without an explicit value and the exact outcome depends on the

   211         compiler used (XXX true? does ANSI say anything about this?)

   212         """

   213         # Delete from the list of macro definitions/undefinitions if

   214         # already there (so that this one will take precedence).

   215         i = self._find_macro (name)

   216         if i is not None:

   217             del self.macros[i]

   218 

   219         defn = (name, value)

   220         self.macros.append (defn)

   221 

   222 

   223     def undefine_macro (self, name):

   224         """Undefine a preprocessor macro for all compilations driven by

   225         this compiler object.  If the same macro is defined by

   226         'define_macro()' and undefined by 'undefine_macro()' the last call

   227         takes precedence (including multiple redefinitions or

   228         undefinitions).  If the macro is redefined/undefined on a

   229         per-compilation basis (ie. in the call to 'compile()'), then that

   230         takes precedence.

   231         """

   232         # Delete from the list of macro definitions/undefinitions if

   233         # already there (so that this one will take precedence).

   234         i = self._find_macro (name)

   235         if i is not None:

   236             del self.macros[i]

   237 

   238         undefn = (name,)

   239         self.macros.append (undefn)

   240 

   241 

   242     def add_include_dir (self, dir):

   243         """Add 'dir' to the list of directories that will be searched for

   244         header files.  The compiler is instructed to search directories in

   245         the order in which they are supplied by successive calls to

   246         'add_include_dir()'.

   247         """

   248         self.include_dirs.append (dir)

   249 

   250     def set_include_dirs (self, dirs):

   251         """Set the list of directories that will be searched to 'dirs' (a

   252         list of strings).  Overrides any preceding calls to

   253         'add_include_dir()'; subsequence calls to 'add_include_dir()' add

   254         to the list passed to 'set_include_dirs()'.  This does not affect

   255         any list of standard include directories that the compiler may

   256         search by default.

   257         """

   258         self.include_dirs = copy (dirs)

   259 

   260 

   261     def add_library (self, libname):

   262         """Add 'libname' to the list of libraries that will be included in

   263         all links driven by this compiler object.  Note that 'libname'

   264         should *not* be the name of a file containing a library, but the

   265         name of the library itself: the actual filename will be inferred by

   266         the linker, the compiler, or the compiler class (depending on the

   267         platform).

   268 

   269         The linker will be instructed to link against libraries in the

   270         order they were supplied to 'add_library()' and/or

   271         'set_libraries()'.  It is perfectly valid to duplicate library

   272         names; the linker will be instructed to link against libraries as

   273         many times as they are mentioned.

   274         """

   275         self.libraries.append (libname)

   276 

   277     def set_libraries (self, libnames):

   278         """Set the list of libraries to be included in all links driven by

   279         this compiler object to 'libnames' (a list of strings).  This does

   280         not affect any standard system libraries that the linker may

   281         include by default.

   282         """

   283         self.libraries = copy (libnames)

   284 

   285 

   286     def add_library_dir (self, dir):

   287         """Add 'dir' to the list of directories that will be searched for

   288         libraries specified to 'add_library()' and 'set_libraries()'.  The

   289         linker will be instructed to search for libraries in the order they

   290         are supplied to 'add_library_dir()' and/or 'set_library_dirs()'.

   291         """

   292         self.library_dirs.append (dir)

   293 

   294     def set_library_dirs (self, dirs):

   295         """Set the list of library search directories to 'dirs' (a list of

   296         strings).  This does not affect any standard library search path

   297         that the linker may search by default.

   298         """

   299         self.library_dirs = copy (dirs)

   300 

   301 

   302     def add_runtime_library_dir (self, dir):

   303         """Add 'dir' to the list of directories that will be searched for

   304         shared libraries at runtime.

   305         """

   306         self.runtime_library_dirs.append (dir)

   307 

   308     def set_runtime_library_dirs (self, dirs):

   309         """Set the list of directories to search for shared libraries at

   310         runtime to 'dirs' (a list of strings).  This does not affect any

   311         standard search path that the runtime linker may search by

   312         default.

   313         """

   314         self.runtime_library_dirs = copy (dirs)

   315 

   316 

   317     def add_link_object (self, object):

   318         """Add 'object' to the list of object files (or analogues, such as

   319         explicitly named library files or the output of "resource

   320         compilers") to be included in every link driven by this compiler

   321         object.

   322         """

   323         self.objects.append (object)

   324 

   325     def set_link_objects (self, objects):

   326         """Set the list of object files (or analogues) to be included in

   327         every link to 'objects'.  This does not affect any standard object

   328         files that the linker may include by default (such as system

   329         libraries).

   330         """

   331         self.objects = copy (objects)

   332 

   333 

   334     # -- Private utility methods --------------------------------------

   335     # (here for the convenience of subclasses)

   336 

   337     # Helper method to prep compiler in subclass compile() methods

   338 

   339     def _setup_compile(self, outdir, macros, incdirs, sources, depends,

   340                        extra):

   341         """Process arguments and decide which source files to compile.

   342 

   343         Merges _fix_compile_args() and _prep_compile().

   344         """

   345         if outdir is None:

   346             outdir = self.output_dir

   347         elif type(outdir) is not StringType:

   348             raise TypeError, "'output_dir' must be a string or None"

   349 

   350         if macros is None:

   351             macros = self.macros

   352         elif type(macros) is ListType:

   353             macros = macros + (self.macros or [])

   354         else:

   355             raise TypeError, "'macros' (if supplied) must be a list of tuples"

   356 

   357         if incdirs is None:

   358             incdirs = self.include_dirs

   359         elif type(incdirs) in (ListType, TupleType):

   360             incdirs = list(incdirs) + (self.include_dirs or [])

   361         else:

   362             raise TypeError, \

   363                   "'include_dirs' (if supplied) must be a list of strings"

   364 

   365         if extra is None:

   366             extra = []

   367 

   368         # Get the list of expected output (object) files

   369         objects = self.object_filenames(sources,

   370                                         strip_dir=0,

   371                                         output_dir=outdir)

   372         assert len(objects) == len(sources)

   373 

   374         # XXX should redo this code to eliminate skip_source entirely.

   375         # XXX instead create build and issue skip messages inline

   376 

   377         if self.force:

   378             skip_source = {}            # rebuild everything

   379             for source in sources:

   380                 skip_source[source] = 0

   381         elif depends is None:

   382             # If depends is None, figure out which source files we

   383             # have to recompile according to a simplistic check. We

   384             # just compare the source and object file, no deep

   385             # dependency checking involving header files.

   386             skip_source = {}            # rebuild everything

   387             for source in sources:      # no wait, rebuild nothing

   388                 skip_source[source] = 1

   389 

   390             n_sources, n_objects = newer_pairwise(sources, objects)

   391             for source in n_sources:    # no really, only rebuild what's

   392                 skip_source[source] = 0 # out-of-date

   393         else:

   394             # If depends is a list of files, then do a different

   395             # simplistic check.  Assume that each object depends on

   396             # its source and all files in the depends list.

   397             skip_source = {}

   398             # L contains all the depends plus a spot at the end for a

   399             # particular source file

   400             L = depends[:] + [None]

   401             for i in range(len(objects)):

   402                 source = sources[i]

   403                 L[-1] = source

   404                 if newer_group(L, objects[i]):

   405                     skip_source[source] = 0

   406                 else:

   407                     skip_source[source] = 1

   408 

   409         pp_opts = gen_preprocess_options(macros, incdirs)

   410 

   411         build = {}

   412         for i in range(len(sources)):

   413             src = sources[i]

   414             obj = objects[i]

   415             ext = os.path.splitext(src)[1]

   416             self.mkpath(os.path.dirname(obj))

   417             if skip_source[src]:

   418                 log.debug("skipping %s (%s up-to-date)", src, obj)

   419             else:

   420                 build[obj] = src, ext

   421 

   422         return macros, objects, extra, pp_opts, build

   423 

   424     def _get_cc_args(self, pp_opts, debug, before):

   425         # works for unixccompiler, emxccompiler, cygwinccompiler

   426         cc_args = pp_opts + ['-c']

   427         if debug:

   428             cc_args[:0] = ['-g']

   429         if before:

   430             cc_args[:0] = before

   431         return cc_args

   432 

   433     def _fix_compile_args (self, output_dir, macros, include_dirs):

   434         """Typecheck and fix-up some of the arguments to the 'compile()'

   435         method, and return fixed-up values.  Specifically: if 'output_dir'

   436         is None, replaces it with 'self.output_dir'; ensures that 'macros'

   437         is a list, and augments it with 'self.macros'; ensures that

   438         'include_dirs' is a list, and augments it with 'self.include_dirs'.

   439         Guarantees that the returned values are of the correct type,

   440         i.e. for 'output_dir' either string or None, and for 'macros' and

   441         'include_dirs' either list or None.

   442         """

   443         if output_dir is None:

   444             output_dir = self.output_dir

   445         elif type (output_dir) is not StringType:

   446             raise TypeError, "'output_dir' must be a string or None"

   447 

   448         if macros is None:

   449             macros = self.macros

   450         elif type (macros) is ListType:

   451             macros = macros + (self.macros or [])

   452         else:

   453             raise TypeError, "'macros' (if supplied) must be a list of tuples"

   454 

   455         if include_dirs is None:

   456             include_dirs = self.include_dirs

   457         elif type (include_dirs) in (ListType, TupleType):

   458             include_dirs = list (include_dirs) + (self.include_dirs or [])

   459         else:

   460             raise TypeError, \

   461                   "'include_dirs' (if supplied) must be a list of strings"

   462 

   463         return output_dir, macros, include_dirs

   464 

   465     # _fix_compile_args ()

   466 

   467 

   468     def _prep_compile(self, sources, output_dir, depends=None):

   469         """Decide which souce files must be recompiled.

   470 

   471         Determine the list of object files corresponding to 'sources',

   472         and figure out which ones really need to be recompiled.

   473         Return a list of all object files and a dictionary telling

   474         which source files can be skipped.

   475         """

   476         # Get the list of expected output (object) files

   477         objects = self.object_filenames(sources, output_dir=output_dir)

   478         assert len(objects) == len(sources)

   479 

   480         if self.force:

   481             skip_source = {}            # rebuild everything

   482             for source in sources:

   483                 skip_source[source] = 0

   484         elif depends is None:

   485             # If depends is None, figure out which source files we

   486             # have to recompile according to a simplistic check. We

   487             # just compare the source and object file, no deep

   488             # dependency checking involving header files.

   489             skip_source = {}            # rebuild everything

   490             for source in sources:      # no wait, rebuild nothing

   491                 skip_source[source] = 1

   492 

   493             n_sources, n_objects = newer_pairwise(sources, objects)

   494             for source in n_sources:    # no really, only rebuild what's

   495                 skip_source[source] = 0 # out-of-date

   496         else:

   497             # If depends is a list of files, then do a different

   498             # simplistic check.  Assume that each object depends on

   499             # its source and all files in the depends list.

   500             skip_source = {}

   501             # L contains all the depends plus a spot at the end for a

   502             # particular source file

   503             L = depends[:] + [None]

   504             for i in range(len(objects)):

   505                 source = sources[i]

   506                 L[-1] = source

   507                 if newer_group(L, objects[i]):

   508                     skip_source[source] = 0

   509                 else:

   510                     skip_source[source] = 1

   511 

   512         return objects, skip_source

   513 

   514     # _prep_compile ()

   515 

   516 

   517     def _fix_object_args (self, objects, output_dir):

   518         """Typecheck and fix up some arguments supplied to various methods.

   519         Specifically: ensure that 'objects' is a list; if output_dir is

   520         None, replace with self.output_dir.  Return fixed versions of

   521         'objects' and 'output_dir'.

   522         """

   523         if type (objects) not in (ListType, TupleType):

   524             raise TypeError, \

   525                   "'objects' must be a list or tuple of strings"

   526         objects = list (objects)

   527 

   528         if output_dir is None:

   529             output_dir = self.output_dir

   530         elif type (output_dir) is not StringType:

   531             raise TypeError, "'output_dir' must be a string or None"

   532 

   533         return (objects, output_dir)

   534 

   535 

   536     def _fix_lib_args (self, libraries, library_dirs, runtime_library_dirs):

   537         """Typecheck and fix up some of the arguments supplied to the

   538         'link_*' methods.  Specifically: ensure that all arguments are

   539         lists, and augment them with their permanent versions

   540         (eg. 'self.libraries' augments 'libraries').  Return a tuple with

   541         fixed versions of all arguments.

   542         """

   543         if libraries is None:

   544             libraries = self.libraries

   545         elif type (libraries) in (ListType, TupleType):

   546             libraries = list (libraries) + (self.libraries or [])

   547         else:

   548             raise TypeError, \

   549                   "'libraries' (if supplied) must be a list of strings"

   550 

   551         if library_dirs is None:

   552             library_dirs = self.library_dirs

   553         elif type (library_dirs) in (ListType, TupleType):

   554             library_dirs = list (library_dirs) + (self.library_dirs or [])

   555         else:

   556             raise TypeError, \

   557                   "'library_dirs' (if supplied) must be a list of strings"

   558 

   559         if runtime_library_dirs is None:

   560             runtime_library_dirs = self.runtime_library_dirs

   561         elif type (runtime_library_dirs) in (ListType, TupleType):

   562             runtime_library_dirs = (list (runtime_library_dirs) +

   563                                     (self.runtime_library_dirs or []))

   564         else:

   565             raise TypeError, \

   566                   "'runtime_library_dirs' (if supplied) " + \

   567                   "must be a list of strings"

   568 

   569         return (libraries, library_dirs, runtime_library_dirs)

   570 

   571     # _fix_lib_args ()

   572 

   573 

   574     def _need_link (self, objects, output_file):

   575         """Return true if we need to relink the files listed in 'objects'

   576         to recreate 'output_file'.

   577         """

   578         if self.force:

   579             return 1

   580         else:

   581             if self.dry_run:

   582                 newer = newer_group (objects, output_file, missing='newer')

   583             else:

   584                 newer = newer_group (objects, output_file)

   585             return newer

   586 

   587     # _need_link ()

   588 

   589     def detect_language (self, sources):

   590         """Detect the language of a given file, or list of files. Uses

   591         language_map, and language_order to do the job.

   592         """

   593         if type(sources) is not ListType:

   594             sources = [sources]

   595         lang = None

   596         index = len(self.language_order)

   597         for source in sources:

   598             base, ext = os.path.splitext(source)

   599             extlang = self.language_map.get(ext)

   600             try:

   601                 extindex = self.language_order.index(extlang)

   602                 if extindex < index:

   603                     lang = extlang

   604                     index = extindex

   605             except ValueError:

   606                 pass

   607         return lang

   608 

   609     # detect_language ()

   610 

   611     # -- Worker methods ------------------------------------------------

   612     # (must be implemented by subclasses)

   613 

   614     def preprocess (self,

   615                     source,

   616                     output_file=None,

   617                     macros=None,

   618                     include_dirs=None,

   619                     extra_preargs=None,

   620                     extra_postargs=None):

   621         """Preprocess a single C/C++ source file, named in 'source'.

   622         Output will be written to file named 'output_file', or stdout if

   623         'output_file' not supplied.  'macros' is a list of macro

   624         definitions as for 'compile()', which will augment the macros set

   625         with 'define_macro()' and 'undefine_macro()'.  'include_dirs' is a

   626         list of directory names that will be added to the default list.

   627 

   628         Raises PreprocessError on failure.

   629         """

   630         pass

   631 

   632     def compile(self, sources, output_dir=None, macros=None,

   633                 include_dirs=None, debug=0, extra_preargs=None,

   634                 extra_postargs=None, depends=None):

   635         """Compile one or more source files.

   636 

   637         'sources' must be a list of filenames, most likely C/C++

   638         files, but in reality anything that can be handled by a

   639         particular compiler and compiler class (eg. MSVCCompiler can

   640         handle resource files in 'sources').  Return a list of object

   641         filenames, one per source filename in 'sources'.  Depending on

   642         the implementation, not all source files will necessarily be

   643         compiled, but all corresponding object filenames will be

   644         returned.

   645 

   646         If 'output_dir' is given, object files will be put under it, while

   647         retaining their original path component.  That is, "foo/bar.c"

   648         normally compiles to "foo/bar.o" (for a Unix implementation); if

   649         'output_dir' is "build", then it would compile to

   650         "build/foo/bar.o".

   651 

   652         'macros', if given, must be a list of macro definitions.  A macro

   653         definition is either a (name, value) 2-tuple or a (name,) 1-tuple.

   654         The former defines a macro; if the value is None, the macro is

   655         defined without an explicit value.  The 1-tuple case undefines a

   656         macro.  Later definitions/redefinitions/ undefinitions take

   657         precedence.

   658 

   659         'include_dirs', if given, must be a list of strings, the

   660         directories to add to the default include file search path for this

   661         compilation only.

   662 

   663         'debug' is a boolean; if true, the compiler will be instructed to

   664         output debug symbols in (or alongside) the object file(s).

   665 

   666         'extra_preargs' and 'extra_postargs' are implementation- dependent.

   667         On platforms that have the notion of a command-line (e.g. Unix,

   668         DOS/Windows), they are most likely lists of strings: extra

   669         command-line arguments to prepand/append to the compiler command

   670         line.  On other platforms, consult the implementation class

   671         documentation.  In any event, they are intended as an escape hatch

   672         for those occasions when the abstract compiler framework doesn't

   673         cut the mustard.

   674 

   675         'depends', if given, is a list of filenames that all targets

   676         depend on.  If a source file is older than any file in

   677         depends, then the source file will be recompiled.  This

   678         supports dependency tracking, but only at a coarse

   679         granularity.

   680 

   681         Raises CompileError on failure.

   682         """

   683 

   684         # A concrete compiler class can either override this method

   685         # entirely or implement _compile().

   686 

   687         macros, objects, extra_postargs, pp_opts, build = \

   688                 self._setup_compile(output_dir, macros, include_dirs, sources,

   689                                     depends, extra_postargs)

   690         cc_args = self._get_cc_args(pp_opts, debug, extra_preargs)

   691 

   692         for obj in objects:

   693             try:

   694                 src, ext = build[obj]

   695             except KeyError:

   696                 continue

   697             self._compile(obj, src, ext, cc_args, extra_postargs, pp_opts)

   698 

   699         # Return *all* object filenames, not just the ones we just built.

   700         return objects

   701 

   702     def _compile(self, obj, src, ext, cc_args, extra_postargs, pp_opts):

   703         """Compile 'src' to product 'obj'."""

   704 

   705         # A concrete compiler class that does not override compile()

   706         # should implement _compile().

   707         pass

   708 

   709     def create_static_lib (self,

   710                            objects,

   711                            output_libname,

   712                            output_dir=None,

   713                            debug=0,

   714                            target_lang=None):

   715         """Link a bunch of stuff together to create a static library file.

   716         The "bunch of stuff" consists of the list of object files supplied

   717         as 'objects', the extra object files supplied to

   718         'add_link_object()' and/or 'set_link_objects()', the libraries

   719         supplied to 'add_library()' and/or 'set_libraries()', and the

   720         libraries supplied as 'libraries' (if any).

   721 

   722         'output_libname' should be a library name, not a filename; the

   723         filename will be inferred from the library name.  'output_dir' is

   724         the directory where the library file will be put.

   725 

   726         'debug' is a boolean; if true, debugging information will be

   727         included in the library (note that on most platforms, it is the

   728         compile step where this matters: the 'debug' flag is included here

   729         just for consistency).

   730 

   731         'target_lang' is the target language for which the given objects

   732         are being compiled. This allows specific linkage time treatment of

   733         certain languages.

   734 

   735         Raises LibError on failure.

   736         """

   737         pass

   738 

   739 

   740     # values for target_desc parameter in link()

   741     SHARED_OBJECT = "shared_object"

   742     SHARED_LIBRARY = "shared_library"

   743     EXECUTABLE = "executable"

   744 

   745     def link (self,

   746               target_desc,

   747               objects,

   748               output_filename,

   749               output_dir=None,

   750               libraries=None,

   751               library_dirs=None,

   752               runtime_library_dirs=None,

   753               export_symbols=None,

   754               debug=0,

   755               extra_preargs=None,

   756               extra_postargs=None,

   757               build_temp=None,

   758               target_lang=None):

   759         """Link a bunch of stuff together to create an executable or

   760         shared library file.

   761 

   762         The "bunch of stuff" consists of the list of object files supplied

   763         as 'objects'.  'output_filename' should be a filename.  If

   764         'output_dir' is supplied, 'output_filename' is relative to it

   765         (i.e. 'output_filename' can provide directory components if

   766         needed).

   767 

   768         'libraries' is a list of libraries to link against.  These are

   769         library names, not filenames, since they're translated into

   770         filenames in a platform-specific way (eg. "foo" becomes "libfoo.a"

   771         on Unix and "foo.lib" on DOS/Windows).  However, they can include a

   772         directory component, which means the linker will look in that

   773         specific directory rather than searching all the normal locations.

   774 

   775         'library_dirs', if supplied, should be a list of directories to

   776         search for libraries that were specified as bare library names

   777         (ie. no directory component).  These are on top of the system

   778         default and those supplied to 'add_library_dir()' and/or

   779         'set_library_dirs()'.  'runtime_library_dirs' is a list of

   780         directories that will be embedded into the shared library and used

   781         to search for other shared libraries that *it* depends on at

   782         run-time.  (This may only be relevant on Unix.)

   783 

   784         'export_symbols' is a list of symbols that the shared library will

   785         export.  (This appears to be relevant only on Windows.)

   786 

   787         'debug' is as for 'compile()' and 'create_static_lib()', with the

   788         slight distinction that it actually matters on most platforms (as

   789         opposed to 'create_static_lib()', which includes a 'debug' flag

   790         mostly for form's sake).

   791 

   792         'extra_preargs' and 'extra_postargs' are as for 'compile()' (except

   793         of course that they supply command-line arguments for the

   794         particular linker being used).

   795 

   796         'target_lang' is the target language for which the given objects

   797         are being compiled. This allows specific linkage time treatment of

   798         certain languages.

   799 

   800         Raises LinkError on failure.

   801         """

   802         raise NotImplementedError

   803 

   804 

   805     # Old 'link_*()' methods, rewritten to use the new 'link()' method.

   806 

   807     def link_shared_lib (self,

   808                          objects,

   809                          output_libname,

   810                          output_dir=None,

   811                          libraries=None,

   812                          library_dirs=None,

   813                          runtime_library_dirs=None,

   814                          export_symbols=None,

   815                          debug=0,

   816                          extra_preargs=None,

   817                          extra_postargs=None,

   818                          build_temp=None,

   819                          target_lang=None):

   820         self.link(CCompiler.SHARED_LIBRARY, objects,

   821                   self.library_filename(output_libname, lib_type='shared'),

   822                   output_dir,

   823                   libraries, library_dirs, runtime_library_dirs,

   824                   export_symbols, debug,

   825                   extra_preargs, extra_postargs, build_temp, target_lang)

   826 

   827 

   828     def link_shared_object (self,

   829                             objects,

   830                             output_filename,

   831                             output_dir=None,

   832                             libraries=None,

   833                             library_dirs=None,

   834                             runtime_library_dirs=None,

   835                             export_symbols=None,

   836                             debug=0,

   837                             extra_preargs=None,

   838                             extra_postargs=None,

   839                             build_temp=None,

   840                             target_lang=None):

   841         self.link(CCompiler.SHARED_OBJECT, objects,

   842                   output_filename, output_dir,

   843                   libraries, library_dirs, runtime_library_dirs,

   844                   export_symbols, debug,

   845                   extra_preargs, extra_postargs, build_temp, target_lang)

   846 

   847 

   848     def link_executable (self,

   849                          objects,

   850                          output_progname,

   851                          output_dir=None,

   852                          libraries=None,

   853                          library_dirs=None,

   854                          runtime_library_dirs=None,

   855                          debug=0,

   856                          extra_preargs=None,

   857                          extra_postargs=None,

   858                          target_lang=None):

   859         self.link(CCompiler.EXECUTABLE, objects,

   860                   self.executable_filename(output_progname), output_dir,

   861                   libraries, library_dirs, runtime_library_dirs, None,

   862                   debug, extra_preargs, extra_postargs, None, target_lang)

   863 

   864 

   865     # -- Miscellaneous methods -----------------------------------------

   866     # These are all used by the 'gen_lib_options() function; there is

   867     # no appropriate default implementation so subclasses should

   868     # implement all of these.

   869 

   870     def library_dir_option (self, dir):

   871         """Return the compiler option to add 'dir' to the list of

   872         directories searched for libraries.

   873         """

   874         raise NotImplementedError

   875 

   876     def runtime_library_dir_option (self, dir):

   877         """Return the compiler option to add 'dir' to the list of

   878         directories searched for runtime libraries.

   879         """

   880         raise NotImplementedError

   881 

   882     def library_option (self, lib):

   883         """Return the compiler option to add 'dir' to the list of libraries

   884         linked into the shared library or executable.

   885         """

   886         raise NotImplementedError

   887 

   888     def has_function(self, funcname,

   889                      includes=None,

   890                      include_dirs=None,

   891                      libraries=None,

   892                      library_dirs=None):

   893         """Return a boolean indicating whether funcname is supported on

   894         the current platform.  The optional arguments can be used to

   895         augment the compilation environment.

   896         """

   897 

   898         # this can't be included at module scope because it tries to

   899         # import math which might not be available at that point - maybe

   900         # the necessary logic should just be inlined?

   901         import tempfile

   902         if includes is None:

   903             includes = []

   904         if include_dirs is None:

   905             include_dirs = []

   906         if libraries is None:

   907             libraries = []

   908         if library_dirs is None:

   909             library_dirs = []

   910         fd, fname = tempfile.mkstemp(".c", funcname, text=True)

   911         f = os.fdopen(fd, "w")

   912         for incl in includes:

   913             f.write("""#include "%s"\n""" % incl)

   914         f.write("""\

   915 main (int argc, char **argv) {

   916     %s();

   917 }

   918 """ % funcname)

   919         f.close()

   920         try:

   921             objects = self.compile([fname], include_dirs=include_dirs)

   922         except CompileError:

   923             return False

   924 

   925         try:

   926             self.link_executable(objects, "a.out",

   927                                  libraries=libraries,

   928                                  library_dirs=library_dirs)

   929         except (LinkError, TypeError):

   930             return False

   931         return True

   932 

   933     def find_library_file (self, dirs, lib, debug=0):

   934         """Search the specified list of directories for a static or shared

   935         library file 'lib' and return the full path to that file.  If

   936         'debug' true, look for a debugging version (if that makes sense on

   937         the current platform).  Return None if 'lib' wasn't found in any of

   938         the specified directories.

   939         """

   940         raise NotImplementedError

   941 

   942     # -- Filename generation methods -----------------------------------

   943 

   944     # The default implementation of the filename generating methods are

   945     # prejudiced towards the Unix/DOS/Windows view of the world:

   946     #   * object files are named by replacing the source file extension

   947     #     (eg. .c/.cpp -> .o/.obj)

   948     #   * library files (shared or static) are named by plugging the

   949     #     library name and extension into a format string, eg.

   950     #     "lib%s.%s" % (lib_name, ".a") for Unix static libraries

   951     #   * executables are named by appending an extension (possibly

   952     #     empty) to the program name: eg. progname + ".exe" for

   953     #     Windows

   954     #

   955     # To reduce redundant code, these methods expect to find

   956     # several attributes in the current object (presumably defined

   957     # as class attributes):

   958     #   * src_extensions -

   959     #     list of C/C++ source file extensions, eg. ['.c', '.cpp']

   960     #   * obj_extension -

   961     #     object file extension, eg. '.o' or '.obj'

   962     #   * static_lib_extension -

   963     #     extension for static library files, eg. '.a' or '.lib'

   964     #   * shared_lib_extension -

   965     #     extension for shared library/object files, eg. '.so', '.dll'

   966     #   * static_lib_format -

   967     #     format string for generating static library filenames,

   968     #     eg. 'lib%s.%s' or '%s.%s'

   969     #   * shared_lib_format

   970     #     format string for generating shared library filenames

   971     #     (probably same as static_lib_format, since the extension

   972     #     is one of the intended parameters to the format string)

   973     #   * exe_extension -

   974     #     extension for executable files, eg. '' or '.exe'

   975 

   976     def object_filenames(self, source_filenames, strip_dir=0, output_dir=''):

   977         if output_dir is None:

   978             output_dir = ''

   979         obj_names = []

   980         for src_name in source_filenames:

   981             base, ext = os.path.splitext(src_name)

   982             base = os.path.splitdrive(base)[1] # Chop off the drive

   983             base = base[os.path.isabs(base):]  # If abs, chop off leading /

   984             if ext not in self.src_extensions:

   985                 raise UnknownFileError, \

   986                       "unknown file type '%s' (from '%s')" % (ext, src_name)

   987             if strip_dir:

   988                 base = os.path.basename(base)

   989             obj_names.append(os.path.join(output_dir,

   990                                           base + self.obj_extension))

   991         return obj_names

   992 

   993     def shared_object_filename(self, basename, strip_dir=0, output_dir=''):

   994         assert output_dir is not None

   995         if strip_dir:

   996             basename = os.path.basename (basename)

   997         return os.path.join(output_dir, basename + self.shared_lib_extension)

   998 

   999     def executable_filename(self, basename, strip_dir=0, output_dir=''):

  1000         assert output_dir is not None

  1001         if strip_dir:

  1002             basename = os.path.basename (basename)

  1003         return os.path.join(output_dir, basename + (self.exe_extension or ''))

  1004 

  1005     def library_filename(self, libname, lib_type='static',     # or 'shared'

  1006                          strip_dir=0, output_dir=''):

  1007         assert output_dir is not None

  1008         if lib_type not in ("static", "shared", "dylib"):

  1009             raise ValueError, "'lib_type' must be \"static\", \"shared\" or \"dylib\""

  1010         fmt = getattr(self, lib_type + "_lib_format")

  1011         ext = getattr(self, lib_type + "_lib_extension")

  1012 

  1013         dir, base = os.path.split (libname)

  1014         filename = fmt % (base, ext)

  1015         if strip_dir:

  1016             dir = ''

  1017 

  1018         return os.path.join(output_dir, dir, filename)

  1019 

  1020 

  1021     # -- Utility methods -----------------------------------------------

  1022 

  1023     def announce (self, msg, level=1):

  1024         log.debug(msg)

  1025 

  1026     def debug_print (self, msg):

  1027         from distutils.debug import DEBUG

  1028         if DEBUG:

  1029             print msg

  1030 

  1031     def warn (self, msg):

  1032         sys.stderr.write ("warning: %s\n" % msg)

  1033 

  1034     def execute (self, func, args, msg=None, level=1):

  1035         execute(func, args, msg, self.dry_run)

  1036 

  1037     def spawn (self, cmd):

  1038         spawn (cmd, dry_run=self.dry_run)

  1039 

  1040     def move_file (self, src, dst):

  1041         return move_file (src, dst, dry_run=self.dry_run)

  1042 

  1043     def mkpath (self, name, mode=0777):

  1044         mkpath (name, mode, self.dry_run)

  1045 

  1046 

  1047 # class CCompiler

  1048 

  1049 

  1050 # Map a sys.platform/os.name ('posix', 'nt') to the default compiler

  1051 # type for that platform. Keys are interpreted as re match

  1052 # patterns. Order is important; platform mappings are preferred over

  1053 # OS names.

  1054 _default_compilers = (

  1055 

  1056     # Platform string mappings

  1057 

  1058     # on a cygwin built python we can use gcc like an ordinary UNIXish

  1059     # compiler

  1060     ('cygwin.*', 'unix'),

  1061     ('os2emx', 'emx'),

  1062 

  1063     # OS name mappings

  1064     ('posix', 'unix'),

  1065     ('nt', 'msvc'),

  1066     ('mac', 'mwerks'),

  1067 

  1068     )

  1069 

  1070 def get_default_compiler(osname=None, platform=None):

  1071 

  1072     """ Determine the default compiler to use for the given platform.

  1073 

  1074         osname should be one of the standard Python OS names (i.e. the

  1075         ones returned by os.name) and platform the common value

  1076         returned by sys.platform for the platform in question.

  1077 

  1078         The default values are os.name and sys.platform in case the

  1079         parameters are not given.

  1080 

  1081     """

  1082     if osname is None:

  1083         osname = os.name

  1084     if platform is None:

  1085         platform = sys.platform

  1086     for pattern, compiler in _default_compilers:

  1087         if re.match(pattern, platform) is not None or \

  1088            re.match(pattern, osname) is not None:

  1089             return compiler

  1090     # Default to Unix compiler

  1091     return 'unix'

  1092 

  1093 # Map compiler types to (module_name, class_name) pairs -- ie. where to

  1094 # find the code that implements an interface to this compiler.  (The module

  1095 # is assumed to be in the 'distutils' package.)

  1096 compiler_class = { 'unix':    ('unixccompiler', 'UnixCCompiler',

  1097                                "standard UNIX-style compiler"),

  1098                    'msvc':    ('msvccompiler', 'MSVCCompiler',

  1099                                "Microsoft Visual C++"),

  1100                    'cygwin':  ('cygwinccompiler', 'CygwinCCompiler',

  1101                                "Cygwin port of GNU C Compiler for Win32"),

  1102                    'mingw32': ('cygwinccompiler', 'Mingw32CCompiler',

  1103                                "Mingw32 port of GNU C Compiler for Win32"),

  1104                    'bcpp':    ('bcppcompiler', 'BCPPCompiler',

  1105                                "Borland C++ Compiler"),

  1106                    'mwerks':  ('mwerkscompiler', 'MWerksCompiler',

  1107                                "MetroWerks CodeWarrior"),

  1108                    'emx':     ('emxccompiler', 'EMXCCompiler',

  1109                                "EMX port of GNU C Compiler for OS/2"),

  1110                  }

  1111 

  1112 def show_compilers():

  1113     """Print list of available compilers (used by the "--help-compiler"

  1114     options to "build", "build_ext", "build_clib").

  1115     """

  1116     # XXX this "knows" that the compiler option it's describing is

  1117     # "--compiler", which just happens to be the case for the three

  1118     # commands that use it.

  1119     from distutils.fancy_getopt import FancyGetopt

  1120     compilers = []

  1121     for compiler in compiler_class.keys():

  1122         compilers.append(("compiler="+compiler, None,

  1123                           compiler_class[compiler][2]))

  1124     compilers.sort()

  1125     pretty_printer = FancyGetopt(compilers)

  1126     pretty_printer.print_help("List of available compilers:")

  1127 

  1128 

  1129 def new_compiler (plat=None,

  1130                   compiler=None,

  1131                   verbose=0,

  1132                   dry_run=0,

  1133                   force=0):

  1134     """Generate an instance of some CCompiler subclass for the supplied

  1135     platform/compiler combination.  'plat' defaults to 'os.name'