Lib/distutils/ccompiler.py

   1 """distutils.ccompiler
   2
   3 Contains CCompiler, an abstract base class that defines the interface
   4 for the Distutils compiler abstraction model."""
   5
   6 # created 1999/07/05, Greg Ward
   7
   8 __revision__ = "$Id$"
   9
  10 import sys, os
  11 from types import *
  12 from copy import copy
  13 from distutils.errors import *
  14 from distutils.spawn import spawn
  15 from distutils.util import move_file, mkpath, newer_pairwise, newer_group
  16
  17
  18 class CCompiler:
  19     """Abstract base class to define the interface that must be implemented
  20        by real compiler abstraction classes.  Might have some use as a
  21        place for shared code, but it's not yet clear what code can be
  22        shared between compiler abstraction models for different platforms.
  23
  24        The basic idea behind a compiler abstraction class is that each
  25        instance can be used for all the compile/link steps in building
  26        a single project.  Thus, attributes common to all of those compile
  27        and link steps -- include directories, macros to define, libraries
  28        to link against, etc. -- are attributes of the compiler instance.
  29        To allow for variability in how individual files are treated,
  30        most (all?) of those attributes may be varied on a per-compilation
  31        or per-link basis."""
  32
  33     # 'compiler_type' is a class attribute that identifies this class.  It
  34     # keeps code that wants to know what kind of compiler it's dealing with
  35     # from having to import all possible compiler classes just to do an
  36     # 'isinstance'.  In concrete CCompiler subclasses, 'compiler_type'
  37     # should really, really be one of the keys of the 'compiler_class'
  38     # dictionary (see below -- used by the 'new_compiler()' factory
  39     # function) -- authors of new compiler interface classes are
  40     # responsible for updating 'compiler_class'!
  41     compiler_type = None
  42
  43     # XXX things not handled by this compiler abstraction model:
  44     #   * client can't provide additional options for a compiler,
  45     #     e.g. warning, optimization, debugging flags.  Perhaps this
  46     #     should be the domain of concrete compiler abstraction classes
  47     #     (UnixCCompiler, MSVCCompiler, etc.) -- or perhaps the base
  48     #     class should have methods for the common ones.
  49     #   * can't put output files (object files, libraries, whatever)
  50     #     into a separate directory from their inputs.  Should this be
  51     #     handled by an 'output_dir' attribute of the whole object, or a
  52     #     parameter to the compile/link_* methods, or both?
  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
  80     def __init__ (self,
  81                   verbose=0,
  82                   dry_run=0,
  83                   force=0):
  84
  85         self.verbose = verbose
  86         self.dry_run = dry_run
  87         self.force = force
  88
  89         # 'output_dir': a common output directory for object, library,
  90         # shared object, and shared library files
  91         self.output_dir = None
  92
  93         # 'macros': a list of macro definitions (or undefinitions).  A
  94         # macro definition is a 2-tuple (name, value), where the value is
  95         # either a string or None (no explicit value).  A macro
  96         # undefinition is a 1-tuple (name,).
  97         self.macros = []
  98
  99         # 'include_dirs': a list of directories to search for include files
 100         self.include_dirs = []
 101
 102         # 'libraries': a list of libraries to include in any link
 103         # (library names, not filenames: eg. "foo" not "libfoo.a")
 104         self.libraries = []
 105
 106         # 'library_dirs': a list of directories to search for libraries
 107         self.library_dirs = []
 108
 109         # 'runtime_library_dirs': a list of directories to search for
 110         # shared libraries/objects at runtime
 111         self.runtime_library_dirs = []
 112
 113         # 'objects': a list of object files (or similar, such as explicitly
 114         # named library files) to include on any link
 115         self.objects = []
 116
 117     # __init__ ()
 118
 119
 120     def _find_macro (self, name):
 121         i = 0
 122         for defn in self.macros:
 123             if defn[0] == name:
 124                 return i
 125             i = i + 1
 126
 127         return None
 128
 129
 130     def _check_macro_definitions (self, definitions):
 131         """Ensures that every element of 'definitions' is a valid macro
 132            definition, ie. either (name,value) 2-tuple or a (name,)
 133            tuple.  Do nothing if all definitions are OK, raise
 134            TypeError otherwise."""
 135
 136         for defn in definitions:
 137             if not (type (defn) is TupleType and
 138                     (len (defn) == 1 or
 139                      (len (defn) == 2 and
 140                       (type (defn[1]) is StringType or defn[1] is None))) and
 141                     type (defn[0]) is StringType):
 142                 raise TypeError, \
 143                       ("invalid macro definition '%s': " % defn) + \
 144                       "must be tuple (string,), (string, string), or " + \
 145                       "(string, None)"
 146
 147
 148     # -- Bookkeeping methods -------------------------------------------
 149
 150     def define_macro (self, name, value=None):
 151         """Define a preprocessor macro for all compilations driven by
 152            this compiler object.  The optional parameter 'value' should be
 153            a string; if it is not supplied, then the macro will be defined
 154            without an explicit value and the exact outcome depends on the
 155            compiler used (XXX true? does ANSI say anything about this?)"""
 156
 157         # Delete from the list of macro definitions/undefinitions if
 158         # already there (so that this one will take precedence).
 159         i = self._find_macro (name)
 160         if i is not None:
 161             del self.macros[i]
 162
 163         defn = (name, value)
 164         self.macros.append (defn)
 165
 166
 167     def undefine_macro (self, name):
 168         """Undefine a preprocessor macro for all compilations driven by
 169            this compiler object.  If the same macro is defined by
 170            'define_macro()' and undefined by 'undefine_macro()' the last
 171            call takes precedence (including multiple redefinitions or
 172            undefinitions).  If the macro is redefined/undefined on a
 173            per-compilation basis (ie. in the call to 'compile()'), then
 174            that takes precedence."""
 175
 176         # Delete from the list of macro definitions/undefinitions if
 177         # already there (so that this one will take precedence).
 178         i = self._find_macro (name)
 179         if i is not None:
 180             del self.macros[i]
 181
 182         undefn = (name,)
 183         self.macros.append (undefn)
 184
 185
 186     def add_include_dir (self, dir):
 187         """Add 'dir' to the list of directories that will be searched
 188            for header files.  The compiler is instructed to search
 189            directories in the order in which they are supplied by
 190            successive calls to 'add_include_dir()'."""
 191         self.include_dirs.append (dir)
 192
 193     def set_include_dirs (self, dirs):
 194         """Set the list of directories that will be searched to 'dirs'
 195            (a list of strings).  Overrides any preceding calls to
 196            'add_include_dir()'; subsequence calls to 'add_include_dir()'
 197            add to the list passed to 'set_include_dirs()'.  This does
 198            not affect any list of standard include directories that
 199            the compiler may search by default."""
 200         self.include_dirs = copy (dirs)
 201
 202
 203     def add_library (self, libname):
 204         """Add 'libname' to the list of libraries that will be included
 205            in all links driven by this compiler object.  Note that
 206            'libname' should *not* be the name of a file containing a
 207            library, but the name of the library itself: the actual filename
 208            will be inferred by the linker, the compiler, or the compiler
 209            abstraction class (depending on the platform).
 210
 211            The linker will be instructed to link against libraries in the
 212            order they were supplied to 'add_library()' and/or
 213            'set_libraries()'.  It is perfectly valid to duplicate library
 214            names; the linker will be instructed to link against libraries
 215            as many times as they are mentioned."""
 216         self.libraries.append (libname)
 217
 218     def set_libraries (self, libnames):
 219         """Set the list of libraries to be included in all links driven
 220            by this compiler object to 'libnames' (a list of strings).
 221            This does not affect any standard system libraries that the
 222            linker may include by default."""
 223
 224         self.libraries = copy (libnames)
 225
 226
 227     def add_library_dir (self, dir):
 228         """Add 'dir' to the list of directories that will be searched for
 229            libraries specified to 'add_library()' and 'set_libraries()'.
 230            The linker will be instructed to search for libraries in the
 231            order they are supplied to 'add_library_dir()' and/or
 232            'set_library_dirs()'."""
 233         self.library_dirs.append (dir)
 234
 235     def set_library_dirs (self, dirs):
 236         """Set the list of library search directories to 'dirs' (a list
 237            of strings).  This does not affect any standard library
 238            search path that the linker may search by default."""
 239         self.library_dirs = copy (dirs)
 240
 241
 242     def add_runtime_library_dir (self, dir):
 243         """Add 'dir' to the list of directories that will be searched for
 244            shared libraries at runtime."""
 245         self.runtime_library_dirs.append (dir)
 246
 247     def set_runtime_library_dirs (self, dirs):
 248         """Set the list of directories to search for shared libraries
 249            at runtime to 'dirs' (a list of strings).  This does not affect
 250            any standard search path that the runtime linker may search by
 251            default."""
 252         self.runtime_library_dirs = copy (dirs)
 253
 254
 255     def add_link_object (self, object):
 256         """Add 'object' to the list of object files (or analogues, such
 257            as explictly named library files or the output of "resource
 258            compilers") to be included in every link driven by this
 259            compiler object."""
 260         self.objects.append (object)
 261
 262     def set_link_objects (self, objects):
 263         """Set the list of object files (or analogues) to be included
 264            in every link to 'objects'.  This does not affect any
 265            standard object files that the linker may include by default
 266            (such as system libraries)."""
 267         self.objects = copy (objects)
 268
 269
 270     # -- Priviate utility methods --------------------------------------
 271     # (here for the convenience of subclasses)
 272
 273     def _fix_compile_args (self, output_dir, macros, include_dirs):
 274         """Typecheck and fix-up some of the arguments to the 'compile()' method,
 275            and return fixed-up values.  Specifically: if 'output_dir' is
 276            None, replaces it with 'self.output_dir'; ensures that 'macros'
 277            is a list, and augments it with 'self.macros'; ensures that
 278            'include_dirs' is a list, and augments it with
 279            'self.include_dirs'.  Guarantees that the returned values are of
 280            the correct type, i.e. for 'output_dir' either string or None,
 281            and for 'macros' and 'include_dirs' either list or None."""
 282
 283         if output_dir is None:
 284             output_dir = self.output_dir
 285         elif type (output_dir) is not StringType:
 286             raise TypeError, "'output_dir' must be a string or None"
 287
 288         if macros is None:
 289             macros = self.macros
 290         elif type (macros) is ListType:
 291             macros = macros + (self.macros or [])
 292         else:
 293             raise TypeError, \
 294                   "'macros' (if supplied) must be a list of tuples"
 295
 296         if include_dirs is None:
 297             include_dirs = self.include_dirs
 298         elif type (include_dirs) in (ListType, TupleType):
 299             include_dirs = list (include_dirs) + (self.include_dirs or [])
 300         else:
 301             raise TypeError, \
 302                   "'include_dirs' (if supplied) must be a list of strings"
 303
 304         return (output_dir, macros, include_dirs)
 305
 306     # _fix_compile_args ()
 307
 308
 309     def _prep_compile (self, sources, output_dir):
 310         """Determine the list of object files corresponding to 'sources', and
 311            figure out which ones really need to be recompiled.  Return a list
 312            of all object files and a dictionary telling which source files can
 313            be skipped."""
 314
 315         # Get the list of expected output (object) files
 316         objects = self.object_filenames (sources,
 317                                          output_dir=output_dir)
 318
 319         if self.force:
 320             skip_source = {}            # rebuild everything
 321             for source in sources:
 322                 skip_source[source] = 0
 323         else:
 324             # Figure out which source files we have to recompile according
 325             # to a simplistic check -- we just compare the source and
 326             # object file, no deep dependency checking involving header
 327             # files.
 328             skip_source = {}            # rebuild everything
 329             for source in sources:      # no wait, rebuild nothing
 330                 skip_source[source] = 1
 331
 332             (n_sources, n_objects) = newer_pairwise (sources, objects)
 333             for source in n_sources:    # no really, only rebuild what's out-of-date
 334                 skip_source[source] = 0
 335
 336         return (objects, skip_source)
 337
 338     # _prep_compile ()
 339
 340
 341     def _fix_object_args (self, objects, output_dir):
 342         """Typecheck and fix up some arguments supplied to various
 343            methods.  Specifically: ensure that 'objects' is a list; if
 344            output_dir is None, replace with self.output_dir.  Return fixed
 345            versions of 'objects' and 'output_dir'."""
 346
 347         if type (objects) not in (ListType, TupleType):
 348             raise TypeError, \
 349                   "'objects' must be a list or tuple of strings"
 350         objects = list (objects)
 351
 352         if output_dir is None:
 353             output_dir = self.output_dir
 354         elif type (output_dir) is not StringType:
 355             raise TypeError, "'output_dir' must be a string or None"
 356
 357         return (objects, output_dir)
 358
 359
 360     def _fix_lib_args (self, libraries, library_dirs, runtime_library_dirs):
 361         """Typecheck and fix up some of the arguments supplied to the
 362            'link_*' methods.  Specifically: ensure that all arguments are
 363            lists, and augment them with their permanent versions
 364            (eg. 'self.libraries' augments 'libraries').  Return a tuple
 365            with fixed versions of all arguments."""
 366
 367         if libraries is None:
 368             libraries = self.libraries
 369         elif type (libraries) in (ListType, TupleType):
 370             libraries = list (libraries) + (self.libraries or [])
 371         else:
 372             raise TypeError, \
 373                   "'libraries' (if supplied) must be a list of strings"
 374
 375         if library_dirs is None:
 376             library_dirs = self.library_dirs
 377         elif type (library_dirs) in (ListType, TupleType):
 378             library_dirs = list (library_dirs) + (self.library_dirs or [])
 379         else:
 380             raise TypeError, \
 381                   "'library_dirs' (if supplied) must be a list of strings"
 382
 383         if runtime_library_dirs is None:
 384             runtime_library_dirs = self.runtime_library_dirs
 385         elif type (runtime_library_dirs) in (ListType, TupleType):
 386             runtime_library_dirs = (list (runtime_library_dirs) +
 387                                     (self.runtime_library_dirs or []))
 388         else:
 389             raise TypeError, \
 390                   "'runtime_library_dirs' (if supplied) " + \
 391                   "must be a list of strings"
 392
 393         return (libraries, library_dirs, runtime_library_dirs)
 394
 395     # _fix_lib_args ()
 396
 397
 398     def _need_link (self, objects, output_file):
 399         """Return true if we need to relink the files listed in 'objects' to
 400            recreate 'output_file'."""
 401
 402         if self.force:
 403             return 1
 404         else:
 405             if self.dry_run:
 406                 newer = newer_group (objects, output_file, missing='newer')
 407             else:
 408                 newer = newer_group (objects, output_file)
 409             return newer
 410
 411     # _need_link ()
 412
 413
 414     # -- Worker methods ------------------------------------------------
 415     # (must be implemented by subclasses)
 416
 417     def compile (self,
 418                  sources,
 419                  output_dir=None,
 420                  macros=None,
 421                  include_dirs=None,
 422                  debug=0,
 423                  extra_preargs=None,
 424                  extra_postargs=None):
 425         """Compile one or more C/C++ source files.  'sources' must be
 426            a list of strings, each one the name of a C/C++ source
 427            file.  Return a list of object filenames, one per source
 428            filename in 'sources'.  Depending on the implementation,
 429            not all source files will necessarily be compiled, but
 430            all corresponding object filenames will be returned.
 431
 432            If 'output_dir' is given, object files will be put under it,
 433            while retaining their original path component.  That is,
 434            "foo/bar.c" normally compiles to "foo/bar.o" (for a Unix
 435            implementation); if 'output_dir' is "build", then it would
 436            compile to "build/foo/bar.o".
 437
 438            'macros', if given, must be a list of macro definitions.  A
 439            macro definition is either a (name, value) 2-tuple or a (name,)
 440            1-tuple.  The former defines a macro; if the value is None, the
 441            macro is defined without an explicit value.  The 1-tuple case
 442            undefines a macro.  Later definitions/redefinitions/
 443            undefinitions take precedence.
 444
 445            'include_dirs', if given, must be a list of strings, the
 446            directories to add to the default include file search path for
 447            this compilation only.
 448
 449            'debug' is a boolean; if true, the compiler will be instructed
 450            to output debug symbols in (or alongside) the object file(s).
 451
 452            'extra_preargs' and 'extra_postargs' are implementation-
 453            dependent.  On platforms that have the notion of a command-line
 454            (e.g. Unix, DOS/Windows), they are most likely lists of strings:
 455            extra command-line arguments to prepand/append to the compiler
 456            command line.  On other platforms, consult the implementation
 457            class documentation.  In any event, they are intended as an
 458            escape hatch for those occasions when the abstract compiler
 459            framework doesn't cut the mustard."""
 460
 461         pass
 462
 463
 464     def create_static_lib (self,
 465                            objects,
 466                            output_libname,
 467                            output_dir=None,
 468                            debug=0):
 469         """Link a bunch of stuff together to create a static library
 470            file.  The "bunch of stuff" consists of the list of object
 471            files supplied as 'objects', the extra object files supplied
 472            to 'add_link_object()' and/or 'set_link_objects()', the
 473            libraries supplied to 'add_library()' and/or
 474            'set_libraries()', and the libraries supplied as 'libraries'
 475            (if any).
 476
 477            'output_libname' should be a library name, not a filename; the
 478            filename will be inferred from the library name.  'output_dir'
 479            is the directory where the library file will be put.
 480
 481            'debug' is a boolean; if true, debugging information will be
 482            included in the library (note that on most platforms, it is the
 483            compile step where this matters: the 'debug' flag is included
 484            here just for consistency)."""
 485
 486         pass
 487
 488
 489     def link_shared_lib (self,
 490                          objects,
 491                          output_libname,
 492                          output_dir=None,
 493                          libraries=None,
 494                          library_dirs=None,
 495                          runtime_library_dirs=None,
 496                          debug=0,
 497                          extra_preargs=None,
 498                          extra_postargs=None):
 499         """Link a bunch of stuff together to create a shared library
 500            file.  Similar semantics to 'create_static_lib()', with the
 501            addition of other libraries to link against and directories to
 502            search for them.  Also, of course, the type and name of
 503            the generated file will almost certainly be different, as will
 504            the program used to create it.
 505
 506            'libraries' is a list of libraries to link against.  These are
 507            library names, not filenames, since they're translated into
 508            filenames in a platform-specific way (eg. "foo" becomes
 509            "libfoo.a" on Unix and "foo.lib" on DOS/Windows).  However, they
 510            can include a directory component, which means the linker will
 511            look in that specific directory rather than searching all the
 512            normal locations.
 513
 514            'library_dirs', if supplied, should be a list of directories to
 515            search for libraries that were specified as bare library names
 516            (ie. no directory component).  These are on top of the system
 517            default and those supplied to 'add_library_dir()' and/or
 518            'set_library_dirs()'.
 519
 520            'debug' is as for 'compile()' and 'create_static_lib()', with the
 521            slight distinction that it actually matters on most platforms
 522            (as opposed to 'create_static_lib()', which includes a 'debug'
 523            flag mostly for form's sake).
 524
 525            'extra_preargs' and 'extra_postargs' are as for 'compile()'
 526            (except of course that they supply command-line arguments
 527            for the particular linker being used)."""
 528
 529         pass
 530
 531
 532     def link_shared_object (self,
 533                             objects,
 534                             output_filename,
 535                             output_dir=None,
 536                             libraries=None,
 537                             library_dirs=None,
 538                             runtime_library_dirs=None,
 539                             debug=0,
 540                             extra_preargs=None,
 541                             extra_postargs=None):
 542         """Link a bunch of stuff together to create a shared object
 543            file.  Much like 'link_shared_lib()', except the output filename
 544            is explicitly supplied as 'output_filename'.  If 'output_dir' is
 545            supplied, 'output_filename' is relative to it
 546            (i.e. 'output_filename' can provide directory components if
 547            needed)."""
 548         pass
 549
 550
 551     def link_executable (self,
 552                          objects,
 553                          output_progname,
 554                          output_dir=None,
 555                          libraries=None,
 556                          library_dirs=None,
 557                          runtime_library_dirs=None,
 558                          debug=0,
 559                          extra_preargs=None,
 560                          extra_postargs=None):
 561         """Link a bunch of stuff together to create a binary executable
 562            file.  The "bunch of stuff" is as for 'link_shared_lib()'.
 563            'output_progname' should be the base name of the executable
 564            program--e.g. on Unix the same as the output filename, but
 565            on DOS/Windows ".exe" will be appended."""
 566         pass
 567
 568
 569
 570     # -- Filename generation methods -----------------------------------
 571
 572     # The default implementation of the filename generating methods are
 573     # prejudiced towards the Unix/DOS/Windows view of the world:
 574     #   * object files are named by replacing the source file extension
 575     #     (eg. .c/.cpp -> .o/.obj)
 576     #   * library files (shared or static) are named by plugging the
 577     #     library name and extension into a format string, eg.
 578     #     "lib%s.%s" % (lib_name, ".a") for Unix static libraries
 579     #   * executables are named by appending an extension (possibly
 580     #     empty) to the program name: eg. progname + ".exe" for
 581     #     Windows
 582     #
 583     # To reduce redundant code, these methods expect to find
 584     # several attributes in the current object (presumably defined
 585     # as class attributes):
 586     #   * src_extensions -
 587     #     list of C/C++ source file extensions, eg. ['.c', '.cpp']
 588     #   * obj_extension -
 589     #     object file extension, eg. '.o' or '.obj'
 590     #   * static_lib_extension -
 591     #     extension for static library files, eg. '.a' or '.lib'
 592     #   * shared_lib_extension -
 593     #     extension for shared library/object files, eg. '.so', '.dll'
 594     #   * static_lib_format -
 595     #     format string for generating static library filenames,
 596     #     eg. 'lib%s.%s' or '%s.%s'
 597     #   * shared_lib_format
 598     #     format string for generating shared library filenames
 599     #     (probably same as static_lib_format, since the extension
 600     #     is one of the intended parameters to the format string)
 601     #   * exe_extension -
 602     #     extension for executable files, eg. '' or '.exe'
 603
 604     def object_filenames (self,
 605                           source_filenames,
 606                           strip_dir=0,
 607                           output_dir=''):
 608         if output_dir is None: output_dir = ''
 609         obj_names = []
 610         for src_name in source_filenames:
 611             (base, ext) = os.path.splitext (src_name)
 612             if ext not in self.src_extensions:
 613                 continue
 614             if strip_dir:
 615                 base = os.path.basename (base)
 616             obj_names.append (os.path.join (output_dir,
 617                                             base + self.obj_extension))
 618         return obj_names
 619
 620     # object_filenames ()
 621
 622
 623     def shared_object_filename (self,
 624                                 basename,
 625                                 strip_dir=0,
 626                                 output_dir=''):
 627         if output_dir is None: output_dir = ''
 628         if strip_dir:
 629             basename = os.path.basename (basename)
 630         return os.path.join (output_dir, basename + self.shared_lib_extension)
 631
 632
 633     def library_filename (self,
 634                           libname,
 635                           lib_type='static',     # or 'shared'
 636                           strip_dir=0,
 637                           output_dir=''):
 638
 639         if output_dir is None: output_dir = ''
 640         if lib_type not in ("static","shared"):
 641             raise ValueError, "'lib_type' must be \"static\" or \"shared\""
 642         fmt = getattr (self, lib_type + "_lib_format")
 643         ext = getattr (self, lib_type + "_lib_extension")
 644
 645         (dir, base) = os.path.split (libname)
 646         filename = fmt % (base, ext)
 647         if strip_dir:
 648             dir = ''
 649
 650         return os.path.join (output_dir, dir, filename)
 651
 652
 653     # -- Utility methods -----------------------------------------------
 654
 655     def announce (self, msg, level=1):
 656         if self.verbose >= level:
 657             print msg
 658
 659     def warn (self, msg):
 660         sys.stderr.write ("warning: %s\n" % msg)
 661
 662     def spawn (self, cmd):
 663         spawn (cmd, verbose=self.verbose, dry_run=self.dry_run)
 664
 665     def move_file (self, src, dst):
 666         return move_file (src, dst, verbose=self.verbose, dry_run=self.dry_run)
 667
 668     def mkpath (self, name, mode=0777):
 669         mkpath (name, mode, self.verbose, self.dry_run)
 670
 671
 672 # class CCompiler
 673
 674
 675 # Map a platform ('posix', 'nt') to the default compiler type for
 676 # that platform.
 677 default_compiler = { 'posix': 'unix',
 678                      'nt': 'msvc',
 679                    }
 680
 681 # Map compiler types to (module_name, class_name) pairs -- ie. where to
 682 # find the code that implements an interface to this compiler.  (The module
 683 # is assumed to be in the 'distutils' package.)
 684 compiler_class = { 'unix': ('unixccompiler', 'UnixCCompiler'),
 685                    'msvc': ('msvccompiler', 'MSVCCompiler'),
 686                  }
 687
 688
 689 def new_compiler (plat=None,
 690                   compiler=None,
 691                   verbose=0,
 692                   dry_run=0,
 693                   force=0):
 694
 695     """Generate an instance of some CCompiler subclass for the supplied
 696        platform/compiler combination.  'plat' defaults to 'os.name'
 697        (eg. 'posix', 'nt'), and 'compiler' defaults to the default
 698        compiler for that platform.  Currently only 'posix' and 'nt'
 699        are supported, and the default compilers are "traditional Unix
 700        interface" (UnixCCompiler class) and Visual C++ (MSVCCompiler
 701        class).  Note that it's perfectly possible to ask for a Unix
 702        compiler object under Windows, and a Microsoft compiler object
 703        under Unix -- if you supply a value for 'compiler', 'plat'
 704        is ignored."""
 705
 706     if plat is None:
 707         plat = os.name
 708
 709     try:
 710         if compiler is None:
 711             compiler = default_compiler[plat]
 712
 713         (module_name, class_name) = compiler_class[compiler]
 714     except KeyError:
 715         msg = "don't know how to compile C/C++ code on platform '%s'" % plat
 716         if compiler is not None:
 717             msg = msg + " with '%s' compiler" % compiler
 718         raise DistutilsPlatformError, msg
 719
 720     try:
 721         module_name = "distutils." + module_name
 722         __import__ (module_name)
 723         module = sys.modules[module_name]
 724         klass = vars(module)[class_name]
 725     except ImportError:
 726         raise DistutilsModuleError, \
 727               "can't compile C/C++ code: unable to load module '%s'" % \
 728               module_name
 729     except KeyError:
 730         raise DistutilsModuleError, \
 731               ("can't compile C/C++ code: unable to find class '%s' " +
 732                "in module '%s'") % (class_name, module_name)
 733
 734     return klass (verbose, dry_run, force)
 735
 736
 737 def gen_preprocess_options (macros, include_dirs):
 738     """Generate C pre-processor options (-D, -U, -I) as used by at
 739        least two types of compilers: the typical Unix compiler and Visual
 740        C++.  'macros' is the usual thing, a list of 1- or 2-tuples, where
 741        (name,) means undefine (-U) macro 'name', and (name,value) means
 742        define (-D) macro 'name' to 'value'.  'include_dirs' is just a list of
 743        directory names to be added to the header file search path (-I).
 744        Returns a list of command-line options suitable for either
 745        Unix compilers or Visual C++."""
 746
 747     # XXX it would be nice (mainly aesthetic, and so we don't generate
 748     # stupid-looking command lines) to go over 'macros' and eliminate
 749     # redundant definitions/undefinitions (ie. ensure that only the
 750     # latest mention of a particular macro winds up on the command
 751     # line).  I don't think it's essential, though, since most (all?)
 752     # Unix C compilers only pay attention to the latest -D or -U
 753     # mention of a macro on their command line.  Similar situation for
 754     # 'include_dirs'.  I'm punting on both for now.  Anyways, weeding out
 755     # redundancies like this should probably be the province of
 756     # CCompiler, since the data structures used are inherited from it
 757     # and therefore common to all CCompiler classes.
 758
 759     pp_opts = []
 760     for macro in macros:
 761
 762         if not (type (macro) is TupleType and
 763                 1 <= len (macro) <= 2):
 764             raise TypeError, \
 765                   ("bad macro definition '%s': " +
 766                    "each element of 'macros' list must be a 1- or 2-tuple") % \
 767                   macro
 768
 769         if len (macro) == 1:        # undefine this macro
 770             pp_opts.append ("-U%s" % macro[0])
 771         elif len (macro) == 2:
 772             if macro[1] is None:    # define with no explicit value
 773                 pp_opts.append ("-D%s" % macro[0])
 774             else:
 775                 # XXX *don't* need to be clever about quoting the
 776                 # macro value here, because we're going to avoid the
 777                 # shell at all costs when we spawn the command!
 778                 pp_opts.append ("-D%s=%s" % macro)
 779
 780     for dir in include_dirs:
 781         pp_opts.append ("-I%s" % dir)
 782
 783     return pp_opts
 784
 785 # gen_preprocess_options ()
 786
 787
 788 def gen_lib_options (compiler, library_dirs, runtime_library_dirs, libraries):
 789     """Generate linker options for searching library directories and
 790        linking with specific libraries.  'libraries' and 'library_dirs'
 791        are, respectively, lists of library names (not filenames!) and
 792        search directories.  Returns a list of command-line options suitable
 793        for use with some compiler (depending on the two format strings
 794        passed in)."""
 795
 796     lib_opts = []
 797
 798     for dir in library_dirs:
 799         lib_opts.append (compiler.library_dir_option (dir))
 800
 801     for dir in runtime_library_dirs:
 802         lib_opts.append (compiler.runtime_library_dir_option (dir))
 803
 804     # XXX it's important that we *not* remove redundant library mentions!
 805     # sometimes you really do have to say "-lfoo -lbar -lfoo" in order to
 806     # resolve all symbols.  I just hope we never have to say "-lfoo obj.o
 807     # -lbar" to get things to work -- that's certainly a possibility, but a
 808     # pretty nasty way to arrange your C code.
 809
 810     for lib in libraries:
 811         (lib_dir, lib_name) = os.path.split (lib)
 812         if lib_dir:
 813             lib_file = compiler.find_library_file ([lib_dir], lib_name)
 814             if lib_file:
 815                 lib_opts.append (lib_file)
 816             else:
 817                 compiler.warn ("no library file corresponding to "
 818                                "'%s' found (skipping)" % lib)
 819         else:
 820             lib_opts.append (compiler.library_option (lib))
 821
 822     return lib_opts
 823
 824 # gen_lib_options ()