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 __rcsid__ = "$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
  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     def __init__ (self,
  69                   verbose=0,
  70                   dry_run=0):
  71
  72         self.verbose = verbose
  73         self.dry_run = dry_run
  74
  75         # 'output_dir': a common output directory for object, library,
  76         # shared object, and shared library files
  77         self.output_dir = None
  78
  79         # 'macros': a list of macro definitions (or undefinitions).  A
  80         # macro definition is a 2-tuple (name, value), where the value is
  81         # either a string or None (no explicit value).  A macro
  82         # undefinition is a 1-tuple (name,).
  83         self.macros = []
  84
  85         # 'include_dirs': a list of directories to search for include files
  86         self.include_dirs = []
  87
  88         # 'libraries': a list of libraries to include in any link
  89         # (library names, not filenames: eg. "foo" not "libfoo.a")
  90         self.libraries = []
  91
  92         # 'library_dirs': a list of directories to search for libraries
  93         self.library_dirs = []
  94
  95         # 'runtime_library_dirs': a list of directories to search for
  96         # shared libraries/objects at runtime
  97         self.runtime_library_dirs = []
  98
  99         # 'objects': a list of object files (or similar, such as explicitly
 100         # named library files) to include on any link
 101         self.objects = []
 102
 103     # __init__ ()
 104
 105
 106     def _find_macro (self, name):
 107         i = 0
 108         for defn in self.macros:
 109             if defn[0] == name:
 110                 return i
 111             i = i + 1
 112
 113         return None
 114
 115
 116     def _check_macro_definitions (self, definitions):
 117         """Ensures that every element of 'definitions' is a valid macro
 118            definition, ie. either (name,value) 2-tuple or a (name,)
 119            tuple.  Do nothing if all definitions are OK, raise
 120            TypeError otherwise."""
 121
 122         for defn in definitions:
 123             if not (type (defn) is TupleType and
 124                     (len (defn) == 1 or
 125                      (len (defn) == 2 and
 126                       (type (defn[1]) is StringType or defn[1] is None))) and
 127                     type (defn[0]) is StringType):
 128                 raise TypeError, \
 129                       ("invalid macro definition '%s': " % defn) + \
 130                       "must be tuple (string,), (string, string), or " + \
 131                       "(string, None)"
 132
 133
 134     # -- Bookkeeping methods -------------------------------------------
 135
 136     def define_macro (self, name, value=None):
 137         """Define a preprocessor macro for all compilations driven by
 138            this compiler object.  The optional parameter 'value' should be
 139            a string; if it is not supplied, then the macro will be defined
 140            without an explicit value and the exact outcome depends on the
 141            compiler used (XXX true? does ANSI say anything about this?)"""
 142
 143         # Delete from the list of macro definitions/undefinitions if
 144         # already there (so that this one will take precedence).
 145         i = self._find_macro (name)
 146         if i is not None:
 147             del self.macros[i]
 148
 149         defn = (name, value)
 150         self.macros.append (defn)
 151
 152
 153     def undefine_macro (self, name):
 154         """Undefine a preprocessor macro for all compilations driven by
 155            this compiler object.  If the same macro is defined by
 156            'define_macro()' and undefined by 'undefine_macro()' the last
 157            call takes precedence (including multiple redefinitions or
 158            undefinitions).  If the macro is redefined/undefined on a
 159            per-compilation basis (ie. in the call to 'compile()'), then
 160            that takes precedence."""
 161
 162         # Delete from the list of macro definitions/undefinitions if
 163         # already there (so that this one will take precedence).
 164         i = self._find_macro (name)
 165         if i is not None:
 166             del self.macros[i]
 167
 168         undefn = (name,)
 169         self.macros.append (undefn)
 170
 171
 172     def add_include_dir (self, dir):
 173         """Add 'dir' to the list of directories that will be searched
 174            for header files.  The compiler is instructed to search
 175            directories in the order in which they are supplied by
 176            successive calls to 'add_include_dir()'."""
 177         self.include_dirs.append (dir)
 178
 179     def set_include_dirs (self, dirs):
 180         """Set the list of directories that will be searched to 'dirs'
 181            (a list of strings).  Overrides any preceding calls to
 182            'add_include_dir()'; subsequence calls to 'add_include_dir()'
 183            add to the list passed to 'set_include_dirs()'.  This does
 184            not affect any list of standard include directories that
 185            the compiler may search by default."""
 186         self.include_dirs = copy (dirs)
 187
 188
 189     def add_library (self, libname):
 190         """Add 'libname' to the list of libraries that will be included
 191            in all links driven by this compiler object.  Note that
 192            'libname' should *not* be the name of a file containing a
 193            library, but the name of the library itself: the actual filename
 194            will be inferred by the linker, the compiler, or the compiler
 195            abstraction class (depending on the platform).
 196
 197            The linker will be instructed to link against libraries in the
 198            order they were supplied to 'add_library()' and/or
 199            'set_libraries()'.  It is perfectly valid to duplicate library
 200            names; the linker will be instructed to link against libraries
 201            as many times as they are mentioned."""
 202         self.libraries.append (libname)
 203
 204     def set_libraries (self, libnames):
 205         """Set the list of libraries to be included in all links driven
 206            by this compiler object to 'libnames' (a list of strings).
 207            This does not affect any standard system libraries that the
 208            linker may include by default."""
 209
 210         self.libraries = copy (libnames)
 211
 212
 213     def add_library_dir (self, dir):
 214         """Add 'dir' to the list of directories that will be searched for
 215            libraries specified to 'add_library()' and 'set_libraries()'.
 216            The linker will be instructed to search for libraries in the
 217            order they are supplied to 'add_library_dir()' and/or
 218            'set_library_dirs()'."""
 219         self.library_dirs.append (dir)
 220
 221     def set_library_dirs (self, dirs):
 222         """Set the list of library search directories to 'dirs' (a list
 223            of strings).  This does not affect any standard library
 224            search path that the linker may search by default."""
 225         self.library_dirs = copy (dirs)
 226
 227
 228     def add_runtime_library_dir (self, dir):
 229         """Add 'dir' to the list of directories that will be searched for
 230            shared libraries at runtime."""
 231         self.runtime_library_dirs.append (dir)
 232
 233     def set_runtime_library_dirs (self, dirs):
 234         """Set the list of directories to search for shared libraries
 235            at runtime to 'dirs' (a list of strings).  This does not affect
 236            any standard search path that the runtime linker may search by
 237            default."""
 238         self.runtime_library_dirs = copy (dirs)
 239
 240
 241     def add_link_object (self, object):
 242         """Add 'object' to the list of object files (or analogues, such
 243            as explictly named library files or the output of "resource
 244            compilers") to be included in every link driven by this
 245            compiler object."""
 246         self.objects.append (object)
 247
 248     def set_link_objects (self, objects):
 249         """Set the list of object files (or analogues) to be included
 250            in every link to 'objects'.  This does not affect any
 251            standard object files that the linker may include by default
 252            (such as system libraries)."""
 253         self.objects = copy (objects)
 254
 255
 256     # -- Worker methods ------------------------------------------------
 257     # (must be implemented by subclasses)
 258
 259     def compile (self,
 260                  sources,
 261                  output_dir=None,
 262                  macros=None,
 263                  includes=None,
 264                  extra_preargs=None,
 265                  extra_postargs=None):
 266         """Compile one or more C/C++ source files.  'sources' must be
 267            a list of strings, each one the name of a C/C++ source
 268            file.  Return a list of the object filenames generated
 269            (one for each source filename in 'sources').
 270
 271            'macros', if given, must be a list of macro definitions.  A
 272            macro definition is either a (name, value) 2-tuple or a (name,)
 273            1-tuple.  The former defines a macro; if the value is None, the
 274            macro is defined without an explicit value.  The 1-tuple case
 275            undefines a macro.  Later definitions/redefinitions/
 276            undefinitions take precedence.
 277
 278            'includes', if given, must be a list of strings, the directories
 279            to add to the default include file search path for this
 280            compilation only.
 281
 282            'extra_preargs' and 'extra_postargs' are optional lists of extra
 283            command-line arguments that will be, respectively, prepended or
 284            appended to the generated command line immediately before
 285            execution.  These will most likely be peculiar to the particular
 286            platform and compiler being worked with, but are a necessary
 287            escape hatch for those occasions when the abstract compiler
 288            framework doesn't cut the mustard."""
 289
 290         pass
 291
 292
 293     # XXX this is kind of useless without 'link_binary()' or
 294     # 'link_executable()' or something -- or maybe 'link_static_lib()'
 295     # should not exist at all, and we just have 'link_binary()'?
 296     def link_static_lib (self,
 297                          objects,
 298                          output_libname,
 299                          output_dir=None,
 300                          libraries=None,
 301                          library_dirs=None,
 302                          extra_preargs=None,
 303                          extra_postargs=None):
 304         """Link a bunch of stuff together to create a static library
 305            file.  The "bunch of stuff" consists of the list of object
 306            files supplied as 'objects', the extra object files supplied
 307            to 'add_link_object()' and/or 'set_link_objects()', the
 308            libraries supplied to 'add_library()' and/or
 309            'set_libraries()', and the libraries supplied as 'libraries'
 310            (if any).
 311
 312            'output_libname' should be a library name, not a filename;
 313            the filename will be inferred from the library name.
 314
 315            'library_dirs', if supplied, should be a list of additional
 316            directories to search on top of the system default and those
 317            supplied to 'add_library_dir()' and/or 'set_library_dirs()'.
 318
 319            'extra_preargs' and 'extra_postargs' are as for 'compile()'
 320            (except of course that they supply command-line arguments
 321            for the particular linker being used)."""
 322
 323         pass
 324
 325
 326     def link_shared_lib (self,
 327                          objects,
 328                          output_libname,
 329                          output_dir=None,
 330                          libraries=None,
 331                          library_dirs=None,
 332                          extra_preargs=None,
 333                          extra_postargs=None):
 334         """Link a bunch of stuff together to create a shared library
 335            file.  Has the same effect as 'link_static_lib()' except
 336            that the filename inferred from 'output_libname' will most
 337            likely be different, and the type of file generated will
 338            almost certainly be different."""
 339         pass
 340
 341
 342     def link_shared_object (self,
 343                             objects,
 344                             output_filename,
 345                             output_dir=None,
 346                             libraries=None,
 347                             library_dirs=None,
 348                             extra_preargs=None,
 349                             extra_postargs=None):
 350         """Link a bunch of stuff together to create a shared object
 351            file.  Much like 'link_shared_lib()', except the output filename
 352            is explicitly supplied as 'output_filename'.  If 'output_dir' is
 353            supplied, 'output_filename' is relative to it
 354            (i.e. 'output_filename' can provide directory components if
 355            needed)."""
 356         pass
 357
 358
 359     # -- Filename mangling methods -------------------------------------
 360
 361     # General principle for the filename-mangling methods: by default,
 362     # don't include a directory component, no matter what the caller
 363     # supplies.  Eg. for UnixCCompiler, a source file of "foo/bar/baz.c"
 364     # becomes "baz.o" or "baz.so", etc.  (That way, it's easiest for the
 365     # caller to decide where it wants to put/find the output file.)  The
 366     # 'output_dir' parameter overrides this, of course -- the directory
 367     # component of the input filenames is replaced by 'output_dir'.
 368
 369     def object_filenames (self, source_filenames, output_dir=None):
 370         """Return the list of object filenames corresponding to each
 371            specified source filename."""
 372         pass
 373
 374     def shared_object_filename (self, source_filename):
 375         """Return the shared object filename corresponding to a
 376            specified source filename (assuming the same directory)."""
 377         pass
 378
 379     def library_filename (self, libname):
 380         """Return the static library filename corresponding to the
 381            specified library name."""
 382
 383         pass
 384
 385     def shared_library_filename (self, libname):
 386         """Return the shared library filename corresponding to the
 387            specified library name."""
 388         pass
 389
 390     # XXX ugh -- these should go!
 391     def object_name (self, inname):
 392         """Given a name with no extension, return the name + object extension"""
 393         return inname + self._obj_ext
 394
 395     def shared_library_name (self, inname):
 396         """Given a name with no extension, return the name + shared object extension"""
 397         return inname + self._shared_lib_ext
 398
 399     # -- Utility methods -----------------------------------------------
 400
 401     def announce (self, msg, level=1):
 402         if self.verbose >= level:
 403             print msg
 404
 405     def spawn (self, cmd):
 406         spawn (cmd, verbose=self.verbose, dry_run=self.dry_run)
 407
 408     def move_file (self, src, dst):
 409         return move_file (src, dst, verbose=self.verbose, dry_run=self.dry_run)
 410
 411
 412 # class CCompiler
 413
 414
 415 # Map a platform ('posix', 'nt') to the default compiler type for
 416 # that platform.
 417 default_compiler = { 'posix': 'unix',
 418                      'nt': 'msvc',
 419                    }
 420
 421 # Map compiler types to (module_name, class_name) pairs -- ie. where to
 422 # find the code that implements an interface to this compiler.  (The module
 423 # is assumed to be in the 'distutils' package.)
 424 compiler_class = { 'unix': ('unixccompiler', 'UnixCCompiler'),
 425                    'msvc': ('msvccompiler', 'MSVCCompiler'),
 426                  }
 427
 428
 429 def new_compiler (plat=None,
 430                   compiler=None,
 431                   verbose=0,
 432                   dry_run=0):
 433
 434     """Generate an instance of some CCompiler subclass for the supplied
 435        platform/compiler combination.  'plat' defaults to 'os.name'
 436        (eg. 'posix', 'nt'), and 'compiler' defaults to the default
 437        compiler for that platform.  Currently only 'posix' and 'nt'
 438        are supported, and the default compilers are "traditional Unix
 439        interface" (UnixCCompiler class) and Visual C++ (MSVCCompiler
 440        class).  Note that it's perfectly possible to ask for a Unix
 441        compiler object under Windows, and a Microsoft compiler object
 442        under Unix -- if you supply a value for 'compiler', 'plat'
 443        is ignored."""
 444
 445     if plat is None:
 446         plat = os.name
 447
 448     try:
 449         if compiler is None:
 450             compiler = default_compiler[plat]
 451
 452         (module_name, class_name) = compiler_class[compiler]
 453     except KeyError:
 454         msg = "don't know how to compile C/C++ code on platform '%s'" % plat
 455         if compiler is not None:
 456             msg = msg + " with '%s' compiler" % compiler
 457         raise DistutilsPlatformError, msg
 458
 459     try:
 460         module_name = "distutils." + module_name
 461         __import__ (module_name)
 462         module = sys.modules[module_name]
 463         klass = vars(module)[class_name]
 464     except ImportError:
 465         raise DistutilsModuleError, \
 466               "can't compile C/C++ code: unable to load module '%s'" % \
 467               module_name
 468     except KeyError:
 469         raise DistutilsModuleError, \
 470               ("can't compile C/C++ code: unable to find class '%s' " +
 471                "in module '%s'") % (class_name, module_name)
 472
 473     return klass (verbose, dry_run)
 474
 475
 476 def gen_preprocess_options (macros, includes):
 477     """Generate C pre-processor options (-D, -U, -I) as used by at
 478        least two types of compilers: the typical Unix compiler and Visual
 479        C++.  'macros' is the usual thing, a list of 1- or 2-tuples, where
 480        (name,) means undefine (-U) macro 'name', and (name,value) means
 481        define (-D) macro 'name' to 'value'.  'includes' is just a list of
 482        directory names to be added to the header file search path (-I).
 483        Returns a list of command-line options suitable for either
 484        Unix compilers or Visual C++."""
 485
 486     # XXX it would be nice (mainly aesthetic, and so we don't generate
 487     # stupid-looking command lines) to go over 'macros' and eliminate
 488     # redundant definitions/undefinitions (ie. ensure that only the
 489     # latest mention of a particular macro winds up on the command
 490     # line).  I don't think it's essential, though, since most (all?)
 491     # Unix C compilers only pay attention to the latest -D or -U
 492     # mention of a macro on their command line.  Similar situation for
 493     # 'includes'.  I'm punting on both for now.  Anyways, weeding out
 494     # redundancies like this should probably be the province of
 495     # CCompiler, since the data structures used are inherited from it
 496     # and therefore common to all CCompiler classes.
 497
 498     pp_opts = []
 499     for macro in macros:
 500
 501         if not (type (macro) is TupleType and
 502                 1 <= len (macro) <= 2):
 503             raise TypeError, \
 504                   ("bad macro definition '%s': " +
 505                    "each element of 'macros' list must be a 1- or 2-tuple") % \
 506                   macro
 507
 508         if len (macro) == 1:        # undefine this macro
 509             pp_opts.append ("-U%s" % macro[0])
 510         elif len (macro) == 2:
 511             if macro[1] is None:    # define with no explicit value
 512                 pp_opts.append ("-D%s" % macro[0])
 513             else:
 514                 # XXX *don't* need to be clever about quoting the
 515                 # macro value here, because we're going to avoid the
 516                 # shell at all costs when we spawn the command!
 517                 pp_opts.append ("-D%s=%s" % macro)
 518
 519     for dir in includes:
 520         pp_opts.append ("-I%s" % dir)
 521
 522     return pp_opts
 523
 524 # gen_preprocess_options ()
 525
 526
 527 def gen_lib_options (library_dirs, libraries, dir_format, lib_format):
 528     """Generate linker options for searching library directories and
 529        linking with specific libraries.  'libraries' and 'library_dirs'
 530        are, respectively, lists of library names (not filenames!) and
 531        search directories.  'lib_format' is a format string with exactly
 532        one "%s", into which will be plugged each library name in turn;
 533        'dir_format' is similar, but directory names will be plugged into
 534        it.  Returns a list of command-line options suitable for use with
 535        some compiler (depending on the two format strings passed in)."""
 536
 537     lib_opts = []
 538
 539     for dir in library_dirs:
 540         lib_opts.append (dir_format % dir)
 541
 542     # XXX it's important that we *not* remove redundant library mentions!
 543     # sometimes you really do have to say "-lfoo -lbar -lfoo" in order to
 544     # resolve all symbols.  I just hope we never have to say "-lfoo obj.o
 545     # -lbar" to get things to work -- that's certainly a possibility, but a
 546     # pretty nasty way to arrange your C code.
 547
 548     for lib in libraries:
 549         lib_opts.append (lib_format % lib)
 550
 551     return lib_opts
 552
 553 # _gen_lib_options ()