0001 """distutils.ccompiler 0002 0003 Contains CCompiler, an abstract base class that defines the interface 0004 for the Distutils compiler abstraction model.""" 0005 0006 # This module should be kept compatible with Python 1.5.2. 0007 0008 __revision__ = "$Id: ccompiler.py,v 1.60 2004/08/29 16:40:55 loewis Exp $" 0009 0010 import sys, os, re 0011 from types import * 0012 from copy import copy 0013 from distutils.errors import * 0014 from distutils.spawn import spawn 0015 from distutils.file_util import move_file 0016 from distutils.dir_util import mkpath 0017 from distutils.dep_util import newer_pairwise, newer_group 0018 from distutils.sysconfig import python_build 0019 from distutils.util import split_quoted, execute 0020 from distutils import log 0021 0022 class CCompiler: 0023 """Abstract base class to define the interface that must be implemented 0024 by real compiler classes. Also has some utility methods used by 0025 several compiler classes. 0026 0027 The basic idea behind a compiler abstraction class is that each 0028 instance can be used for all the compile/link steps in building a 0029 single project. Thus, attributes common to all of those compile and 0030 link steps -- include directories, macros to define, libraries to link 0031 against, etc. -- are attributes of the compiler instance. To allow for 0032 variability in how individual files are treated, most of those 0033 attributes may be varied on a per-compilation or per-link basis. 0034 """ 0035 0036 # 'compiler_type' is a class attribute that identifies this class. It 0037 # keeps code that wants to know what kind of compiler it's dealing with 0038 # from having to import all possible compiler classes just to do an 0039 # 'isinstance'. In concrete CCompiler subclasses, 'compiler_type' 0040 # should really, really be one of the keys of the 'compiler_class' 0041 # dictionary (see below -- used by the 'new_compiler()' factory 0042 # function) -- authors of new compiler interface classes are 0043 # responsible for updating 'compiler_class'! 0044 compiler_type = None 0045 0046 # XXX things not handled by this compiler abstraction model: 0047 # * client can't provide additional options for a compiler, 0048 # e.g. warning, optimization, debugging flags. Perhaps this 0049 # should be the domain of concrete compiler abstraction classes 0050 # (UnixCCompiler, MSVCCompiler, etc.) -- or perhaps the base 0051 # class should have methods for the common ones. 0052 # * can't completely override the include or library searchg 0053 # path, ie. no "cc -I -Idir1 -Idir2" or "cc -L -Ldir1 -Ldir2". 0054 # I'm not sure how widely supported this is even by Unix 0055 # compilers, much less on other platforms. And I'm even less 0056 # sure how useful it is; maybe for cross-compiling, but 0057 # support for that is a ways off. (And anyways, cross 0058 # compilers probably have a dedicated binary with the 0059 # right paths compiled in. I hope.) 0060 # * can't do really freaky things with the library list/library 0061 # dirs, e.g. "-Ldir1 -lfoo -Ldir2 -lfoo" to link against 0062 # different versions of libfoo.a in different locations. I 0063 # think this is useless without the ability to null out the 0064 # library search path anyways. 0065 0066 0067 # Subclasses that rely on the standard filename generation methods 0068 # implemented below should override these; see the comment near 0069 # those methods ('object_filenames()' et. al.) for details: 0070 src_extensions = None # list of strings 0071 obj_extension = None # string 0072 static_lib_extension = None 0073 shared_lib_extension = None # string 0074 static_lib_format = None # format string 0075 shared_lib_format = None # prob. same as static_lib_format 0076 exe_extension = None # string 0077 0078 # Default language settings. language_map is used to detect a source 0079 # file or Extension target language, checking source filenames. 0080 # language_order is used to detect the language precedence, when deciding 0081 # what language to use when mixing source types. For example, if some 0082 # extension has two files with ".c" extension, and one with ".cpp", it 0083 # is still linked as c++. 0084 language_map = {".c" : "c", 0085 ".cc" : "c++", 0086 ".cpp" : "c++", 0087 ".cxx" : "c++", 0088 ".m" : "objc", 0089 } 0090 language_order = ["c++", "objc", "c"] 0091 0092 def __init__ (self, 0093 verbose=0, 0094 dry_run=0, 0095 force=0): 0096 0097 self.dry_run = dry_run 0098 self.force = force 0099 self.verbose = verbose 0100 0101 # 'output_dir': a common output directory for object, library, 0102 # shared object, and shared library files 0103 self.output_dir = None 0104 0105 # 'macros': a list of macro definitions (or undefinitions). A 0106 # macro definition is a 2-tuple (name, value), where the value is 0107 # either a string or None (no explicit value). A macro 0108 # undefinition is a 1-tuple (name,). 0109 self.macros = [] 0110 0111 # 'include_dirs': a list of directories to search for include files 0112 self.include_dirs = [] 0113 0114 # 'libraries': a list of libraries to include in any link 0115 # (library names, not filenames: eg. "foo" not "libfoo.a") 0116 self.libraries = [] 0117 0118 # 'library_dirs': a list of directories to search for libraries 0119 self.library_dirs = [] 0120 0121 # 'runtime_library_dirs': a list of directories to search for 0122 # shared libraries/objects at runtime 0123 self.runtime_library_dirs = [] 0124 0125 # 'objects': a list of object files (or similar, such as explicitly 0126 # named library files) to include on any link 0127 self.objects = [] 0128 0129 for key in self.executables.keys(): 0130 self.set_executable(key, self.executables[key]) 0131 0132 # __init__ () 0133 0134 0135 def set_executables (self, **args): 0136 0137 """Define the executables (and options for them) that will be run 0138 to perform the various stages of compilation. The exact set of 0139 executables that may be specified here depends on the compiler 0140 class (via the 'executables' class attribute), but most will have: 0141 compiler the C/C++ compiler 0142 linker_so linker used to create shared objects and libraries 0143 linker_exe linker used to create binary executables 0144 archiver static library creator 0145 0146 On platforms with a command-line (Unix, DOS/Windows), each of these 0147 is a string that will be split into executable name and (optional) 0148 list of arguments. (Splitting the string is done similarly to how 0149 Unix shells operate: words are delimited by spaces, but quotes and 0150 backslashes can override this. See 0151 'distutils.util.split_quoted()'.) 0152 """ 0153 0154 # Note that some CCompiler implementation classes will define class 0155 # attributes 'cpp', 'cc', etc. with hard-coded executable names; 0156 # this is appropriate when a compiler class is for exactly one 0157 # compiler/OS combination (eg. MSVCCompiler). Other compiler 0158 # classes (UnixCCompiler, in particular) are driven by information 0159 # discovered at run-time, since there are many different ways to do 0160 # basically the same things with Unix C compilers. 0161 0162 for key in args.keys(): 0163 if not self.executables.has_key(key): 0164 raise ValueError, \ 0165 "unknown executable '%s' for class %s" % \ 0166 (key, self.__class__.__name__) 0167 self.set_executable(key, args[key]) 0168 0169 # set_executables () 0170 0171 def set_executable(self, key, value): 0172 if type(value) is StringType: 0173 setattr(self, key, split_quoted(value)) 0174 else: 0175 setattr(self, key, value) 0176 0177 0178 def _find_macro (self, name): 0179 i = 0 0180 for defn in self.macros: 0181 if defn[0] == name: 0182 return i 0183 i = i + 1 0184 0185 return None 0186 0187 0188 def _check_macro_definitions (self, definitions): 0189 """Ensures that every element of 'definitions' is a valid macro 0190 definition, ie. either (name,value) 2-tuple or a (name,) tuple. Do 0191 nothing if all definitions are OK, raise TypeError otherwise. 0192 """ 0193 for defn in definitions: 0194 if not (type (defn) is TupleType and 0195 (len (defn) == 1 or 0196 (len (defn) == 2 and 0197 (type (defn[1]) is StringType or defn[1] is None))) and 0198 type (defn[0]) is StringType): 0199 raise TypeError, \ 0200 ("invalid macro definition '%s': " % defn) + \ 0201 "must be tuple (string,), (string, string), or " + \ 0202 "(string, None)" 0203 0204 0205 # -- Bookkeeping methods ------------------------------------------- 0206 0207 def define_macro (self, name, value=None): 0208 """Define a preprocessor macro for all compilations driven by this 0209 compiler object. The optional parameter 'value' should be a 0210 string; if it is not supplied, then the macro will be defined 0211 without an explicit value and the exact outcome depends on the 0212 compiler used (XXX true? does ANSI say anything about this?) 0213 """ 0214 # Delete from the list of macro definitions/undefinitions if 0215 # already there (so that this one will take precedence). 0216 i = self._find_macro (name) 0217 if i is not None: 0218 del self.macros[i] 0219 0220 defn = (name, value) 0221 self.macros.append (defn) 0222 0223 0224 def undefine_macro (self, name): 0225 """Undefine a preprocessor macro for all compilations driven by 0226 this compiler object. If the same macro is defined by 0227 'define_macro()' and undefined by 'undefine_macro()' the last call 0228 takes precedence (including multiple redefinitions or 0229 undefinitions). If the macro is redefined/undefined on a 0230 per-compilation basis (ie. in the call to 'compile()'), then that 0231 takes precedence. 0232 """ 0233 # Delete from the list of macro definitions/undefinitions if 0234 # already there (so that this one will take precedence). 0235 i = self._find_macro (name) 0236 if i is not None: 0237 del self.macros[i] 0238 0239 undefn = (name,) 0240 self.macros.append (undefn) 0241 0242 0243 def add_include_dir (self, dir): 0244 """Add 'dir' to the list of directories that will be searched for 0245 header files. The compiler is instructed to search directories in 0246 the order in which they are supplied by successive calls to 0247 'add_include_dir()'. 0248 """ 0249 self.include_dirs.append (dir) 0250 0251 def set_include_dirs (self, dirs): 0252 """Set the list of directories that will be searched to 'dirs' (a 0253 list of strings). Overrides any preceding calls to 0254 'add_include_dir()'; subsequence calls to 'add_include_dir()' add 0255 to the list passed to 'set_include_dirs()'. This does not affect 0256 any list of standard include directories that the compiler may 0257 search by default. 0258 """ 0259 self.include_dirs = copy (dirs) 0260 0261 0262 def add_library (self, libname): 0263 """Add 'libname' to the list of libraries that will be included in 0264 all links driven by this compiler object. Note that 'libname' 0265 should *not* be the name of a file containing a library, but the 0266 name of the library itself: the actual filename will be inferred by 0267 the linker, the compiler, or the compiler class (depending on the 0268 platform). 0269 0270 The linker will be instructed to link against libraries in the 0271 order they were supplied to 'add_library()' and/or 0272 'set_libraries()'. It is perfectly valid to duplicate library 0273 names; the linker will be instructed to link against libraries as 0274 many times as they are mentioned. 0275 """ 0276 self.libraries.append (libname) 0277 0278 def set_libraries (self, libnames): 0279 """Set the list of libraries to be included in all links driven by 0280 this compiler object to 'libnames' (a list of strings). This does 0281 not affect any standard system libraries that the linker may 0282 include by default. 0283 """ 0284 self.libraries = copy (libnames) 0285 0286 0287 def add_library_dir (self, dir): 0288 """Add 'dir' to the list of directories that will be searched for 0289 libraries specified to 'add_library()' and 'set_libraries()'. The 0290 linker will be instructed to search for libraries in the order they 0291 are supplied to 'add_library_dir()' and/or 'set_library_dirs()'. 0292 """ 0293 self.library_dirs.append (dir) 0294 0295 def set_library_dirs (self, dirs): 0296 """Set the list of library search directories to 'dirs' (a list of 0297 strings). This does not affect any standard library search path 0298 that the linker may search by default. 0299 """ 0300 self.library_dirs = copy (dirs) 0301 0302 0303 def add_runtime_library_dir (self, dir): 0304 """Add 'dir' to the list of directories that will be searched for 0305 shared libraries at runtime. 0306 """ 0307 self.runtime_library_dirs.append (dir) 0308 0309 def set_runtime_library_dirs (self, dirs): 0310 """Set the list of directories to search for shared libraries at 0311 runtime to 'dirs' (a list of strings). This does not affect any 0312 standard search path that the runtime linker may search by 0313 default. 0314 """ 0315 self.runtime_library_dirs = copy (dirs) 0316 0317 0318 def add_link_object (self, object): 0319 """Add 'object' to the list of object files (or analogues, such as 0320 explicitly named library files or the output of "resource 0321 compilers") to be included in every link driven by this compiler 0322 object. 0323 """ 0324 self.objects.append (object) 0325 0326 def set_link_objects (self, objects): 0327 """Set the list of object files (or analogues) to be included in 0328 every link to 'objects'. This does not affect any standard object 0329 files that the linker may include by default (such as system 0330 libraries). 0331 """ 0332 self.objects = copy (objects) 0333 0334 0335 # -- Private utility methods -------------------------------------- 0336 # (here for the convenience of subclasses) 0337 0338 # Helper method to prep compiler in subclass compile() methods 0339 0340 def _setup_compile(self, outdir, macros, incdirs, sources, depends, 0341 extra): 0342 """Process arguments and decide which source files to compile. 0343 0344 Merges _fix_compile_args() and _prep_compile(). 0345 """ 0346 if outdir is None: 0347 outdir = self.output_dir 0348 elif type(outdir) is not StringType: 0349 raise TypeError, "'output_dir' must be a string or None" 0350 0351 if macros is None: 0352 macros = self.macros 0353 elif type(macros) is ListType: 0354 macros = macros + (self.macros or []) 0355 else: 0356 raise TypeError, "'macros' (if supplied) must be a list of tuples" 0357 0358 if incdirs is None: 0359 incdirs = self.include_dirs 0360 elif type(incdirs) in (ListType, TupleType): 0361 incdirs = list(incdirs) + (self.include_dirs or []) 0362 else: 0363 raise TypeError, \ 0364 "'include_dirs' (if supplied) must be a list of strings" 0365 0366 if extra is None: 0367 extra = [] 0368 0369 # Get the list of expected output (object) files 0370 objects = self.object_filenames(sources, 0371 strip_dir=python_build, 0372 output_dir=outdir) 0373 assert len(objects) == len(sources) 0374 0375 # XXX should redo this code to eliminate skip_source entirely. 0376 # XXX instead create build and issue skip messages inline 0377 0378 if self.force: 0379 skip_source = {} # rebuild everything 0380 for source in sources: 0381 skip_source[source] = 0 0382 elif depends is None: 0383 # If depends is None, figure out which source files we 0384 # have to recompile according to a simplistic check. We 0385 # just compare the source and object file, no deep 0386 # dependency checking involving header files. 0387 skip_source = {} # rebuild everything 0388 for source in sources: # no wait, rebuild nothing 0389 skip_source[source] = 1 0390 0391 n_sources, n_objects = newer_pairwise(sources, objects) 0392 for source in n_sources: # no really, only rebuild what's 0393 skip_source[source] = 0 # out-of-date 0394 else: 0395 # If depends is a list of files, then do a different 0396 # simplistic check. Assume that each object depends on 0397 # its source and all files in the depends list. 0398 skip_source = {} 0399 # L contains all the depends plus a spot at the end for a 0400 # particular source file 0401 L = depends[:] + [None] 0402 for i in range(len(objects)): 0403 source = sources[i] 0404 L[-1] = source 0405 if newer_group(L, objects[i]): 0406 skip_source[source] = 0 0407 else: 0408 skip_source[source] = 1 0409 0410 pp_opts = gen_preprocess_options(macros, incdirs) 0411 0412 build = {} 0413 for i in range(len(sources)): 0414 src = sources[i] 0415 obj = objects[i] 0416 ext = os.path.splitext(src)[1] 0417 self.mkpath(os.path.dirname(obj)) 0418 if skip_source[src]: 0419 log.debug("skipping %s (%s up-to-date)", src, obj) 0420 else: 0421 build[obj] = src, ext 0422 0423 return macros, objects, extra, pp_opts, build 0424 0425 def _get_cc_args(self, pp_opts, debug, before): 0426 # works for unixccompiler, emxccompiler, cygwinccompiler 0427 cc_args = pp_opts + ['-c'] 0428 if debug: 0429 cc_args[:0] = ['-g'] 0430 if before: 0431 cc_args[:0] = before 0432 return cc_args 0433 0434 def _fix_compile_args (self, output_dir, macros, include_dirs): 0435 """Typecheck and fix-up some of the arguments to the 'compile()' 0436 method, and return fixed-up values. Specifically: if 'output_dir' 0437 is None, replaces it with 'self.output_dir'; ensures that 'macros' 0438 is a list, and augments it with 'self.macros'; ensures that 0439 'include_dirs' is a list, and augments it with 'self.include_dirs'. 0440 Guarantees that the returned values are of the correct type, 0441 i.e. for 'output_dir' either string or None, and for 'macros' and 0442 'include_dirs' either list or None. 0443 """ 0444 if output_dir is None: 0445 output_dir = self.output_dir 0446 elif type (output_dir) is not StringType: 0447 raise TypeError, "'output_dir' must be a string or None" 0448 0449 if macros is None: 0450 macros = self.macros 0451 elif type (macros) is ListType: 0452 macros = macros + (self.macros or []) 0453 else: 0454 raise TypeError, "'macros' (if supplied) must be a list of tuples" 0455 0456 if include_dirs is None: 0457 include_dirs = self.include_dirs 0458 elif type (include_dirs) in (ListType, TupleType): 0459 include_dirs = list (include_dirs) + (self.include_dirs or []) 0460 else: 0461 raise TypeError, \ 0462 "'include_dirs' (if supplied) must be a list of strings" 0463 0464 return output_dir, macros, include_dirs 0465 0466 # _fix_compile_args () 0467 0468 0469 def _prep_compile(self, sources, output_dir, depends=None): 0470 """Decide which souce files must be recompiled. 0471 0472 Determine the list of object files corresponding to 'sources', 0473 and figure out which ones really need to be recompiled. 0474 Return a list of all object files and a dictionary telling 0475 which source files can be skipped. 0476 """ 0477 # Get the list of expected output (object) files 0478 objects = self.object_filenames(sources, strip_dir=python_build, 0479 output_dir=output_dir) 0480 assert len(objects) == len(sources) 0481 0482 if self.force: 0483 skip_source = {} # rebuild everything 0484 for source in sources: 0485 skip_source[source] = 0 0486 elif depends is None: 0487 # If depends is None, figure out which source files we 0488 # have to recompile according to a simplistic check. We 0489 # just compare the source and object file, no deep 0490 # dependency checking involving header files. 0491 skip_source = {} # rebuild everything 0492 for source in sources: # no wait, rebuild nothing 0493 skip_source[source] = 1 0494 0495 n_sources, n_objects = newer_pairwise(sources, objects) 0496 for source in n_sources: # no really, only rebuild what's 0497 skip_source[source] = 0 # out-of-date 0498 else: 0499 # If depends is a list of files, then do a different 0500 # simplistic check. Assume that each object depends on 0501 # its source and all files in the depends list. 0502 skip_source = {} 0503 # L contains all the depends plus a spot at the end for a 0504 # particular source file 0505 L = depends[:] + [None] 0506 for i in range(len(objects)): 0507 source = sources[i] 0508 L[-1] = source 0509 if newer_group(L, objects[i]): 0510 skip_source[source] = 0 0511 else: 0512 skip_source[source] = 1 0513 0514 return objects, skip_source 0515 0516 # _prep_compile () 0517 0518 0519 def _fix_object_args (self, objects, output_dir): 0520 """Typecheck and fix up some arguments supplied to various methods. 0521 Specifically: ensure that 'objects' is a list; if output_dir is 0522 None, replace with self.output_dir. Return fixed versions of 0523 'objects' and 'output_dir'. 0524 """ 0525 if type (objects) not in (ListType, TupleType): 0526 raise TypeError, \ 0527 "'objects' must be a list or tuple of strings" 0528 objects = list (objects) 0529 0530 if output_dir is None: 0531 output_dir = self.output_dir 0532 elif type (output_dir) is not StringType: 0533 raise TypeError, "'output_dir' must be a string or None" 0534 0535 return (objects, output_dir) 0536 0537 0538 def _fix_lib_args (self, libraries, library_dirs, runtime_library_dirs): 0539 """Typecheck and fix up some of the arguments supplied to the 0540 'link_*' methods. Specifically: ensure that all arguments are 0541 lists, and augment them with their permanent versions 0542 (eg. 'self.libraries' augments 'libraries'). Return a tuple with 0543 fixed versions of all arguments. 0544 """ 0545 if libraries is None: 0546 libraries = self.libraries 0547 elif type (libraries) in (ListType, TupleType): 0548 libraries = list (libraries) + (self.libraries or []) 0549 else: 0550 raise TypeError, \ 0551 "'libraries' (if supplied) must be a list of strings" 0552 0553 if library_dirs is None: 0554 library_dirs = self.library_dirs 0555 elif type (library_dirs) in (ListType, TupleType): 0556 library_dirs = list (library_dirs) + (self.library_dirs or []) 0557 else: 0558 raise TypeError, \ 0559 "'library_dirs' (if supplied) must be a list of strings" 0560 0561 if runtime_library_dirs is None: 0562 runtime_library_dirs = self.runtime_library_dirs 0563 elif type (runtime_library_dirs) in (ListType, TupleType): 0564 runtime_library_dirs = (list (runtime_library_dirs) + 0565 (self.runtime_library_dirs or [])) 0566 else: 0567 raise TypeError, \ 0568 "'runtime_library_dirs' (if supplied) " + \ 0569 "must be a list of strings" 0570 0571 return (libraries, library_dirs, runtime_library_dirs) 0572 0573 # _fix_lib_args () 0574 0575 0576 def _need_link (self, objects, output_file): 0577 """Return true if we need to relink the files listed in 'objects' 0578 to recreate 'output_file'. 0579 """ 0580 if self.force: 0581 return 1 0582 else: 0583 if self.dry_run: 0584 newer = newer_group (objects, output_file, missing='newer') 0585 else: 0586 newer = newer_group (objects, output_file) 0587 return newer 0588 0589 # _need_link () 0590 0591 def detect_language (self, sources): 0592 """Detect the language of a given file, or list of files. Uses 0593 language_map, and language_order to do the job. 0594 """ 0595 if type(sources) is not ListType: 0596 sources = [sources] 0597 lang = None 0598 index = len(self.language_order) 0599 for source in sources: 0600 base, ext = os.path.splitext(source) 0601 extlang = self.language_map.get(ext) 0602 try: 0603 extindex = self.language_order.index(extlang) 0604 if extindex < index: 0605 lang = extlang 0606 index = extindex 0607 except ValueError: 0608 pass 0609 return lang 0610 0611 # detect_language () 0612 0613 # -- Worker methods ------------------------------------------------ 0614 # (must be implemented by subclasses) 0615 0616 def preprocess (self, 0617 source, 0618 output_file=None, 0619 macros=None, 0620 include_dirs=None, 0621 extra_preargs=None, 0622 extra_postargs=None): 0623 """Preprocess a single C/C++ source file, named in 'source'. 0624 Output will be written to file named 'output_file', or stdout if 0625 'output_file' not supplied. 'macros' is a list of macro 0626 definitions as for 'compile()', which will augment the macros set 0627 with 'define_macro()' and 'undefine_macro()'. 'include_dirs' is a 0628 list of directory names that will be added to the default list. 0629 0630 Raises PreprocessError on failure. 0631 """ 0632 pass 0633 0634 def compile(self, sources, output_dir=None, macros=None, 0635 include_dirs=None, debug=0, extra_preargs=None, 0636 extra_postargs=None, depends=None): 0637 """Compile one or more source files. 0638 0639 'sources' must be a list of filenames, most likely C/C++ 0640 files, but in reality anything that can be handled by a 0641 particular compiler and compiler class (eg. MSVCCompiler can 0642 handle resource files in 'sources'). Return a list of object 0643 filenames, one per source filename in 'sources'. Depending on 0644 the implementation, not all source files will necessarily be 0645 compiled, but all corresponding object filenames will be 0646 returned. 0647 0648 If 'output_dir' is given, object files will be put under it, while 0649 retaining their original path component. That is, "foo/bar.c" 0650 normally compiles to "foo/bar.o" (for a Unix implementation); if 0651 'output_dir' is "build", then it would compile to 0652 "build/foo/bar.o". 0653 0654 'macros', if given, must be a list of macro definitions. A macro 0655 definition is either a (name, value) 2-tuple or a (name,) 1-tuple. 0656 The former defines a macro; if the value is None, the macro is 0657 defined without an explicit value. The 1-tuple case undefines a 0658 macro. Later definitions/redefinitions/ undefinitions take 0659 precedence. 0660 0661 'include_dirs', if given, must be a list of strings, the 0662 directories to add to the default include file search path for this 0663 compilation only. 0664 0665 'debug' is a boolean; if true, the compiler will be instructed to 0666 output debug symbols in (or alongside) the object file(s). 0667 0668 'extra_preargs' and 'extra_postargs' are implementation- dependent. 0669 On platforms that have the notion of a command-line (e.g. Unix, 0670 DOS/Windows), they are most likely lists of strings: extra 0671 command-line arguments to prepand/append to the compiler command 0672 line. On other platforms, consult the implementation class 0673 documentation. In any event, they are intended as an escape hatch 0674 for those occasions when the abstract compiler framework doesn't 0675 cut the mustard. 0676 0677 'depends', if given, is a list of filenames that all targets 0678 depend on. If a source file is older than any file in 0679 depends, then the source file will be recompiled. This 0680 supports dependency tracking, but only at a coarse 0681 granularity. 0682 0683 Raises CompileError on failure. 0684 """ 0685 0686 # A concrete compiler class can either override this method 0687 # entirely or implement _compile(). 0688 0689 macros, objects, extra_postargs, pp_opts, build = \ 0690 self._setup_compile(output_dir, macros, include_dirs, sources, 0691 depends, extra_postargs) 0692 cc_args = self._get_cc_args(pp_opts, debug, extra_preargs) 0693 0694 for obj in objects: 0695 try: 0696 src, ext = build[obj] 0697 except KeyError: 0698 continue 0699 self._compile(obj, src, ext, cc_args, extra_postargs, pp_opts) 0700 0701 # Return *all* object filenames, not just the ones we just built. 0702 return objects 0703 0704 def _compile(self, obj, src, ext, cc_args, extra_postargs, pp_opts): 0705 """Compile 'src' to product 'obj'.""" 0706 0707 # A concrete compiler class that does not override compile() 0708 # should implement _compile(). 0709 pass 0710 0711 def create_static_lib (self, 0712 objects, 0713 output_libname, 0714 output_dir=None, 0715 debug=0, 0716 target_lang=None): 0717 """Link a bunch of stuff together to create a static library file. 0718 The "bunch of stuff" consists of the list of object files supplied 0719 as 'objects', the extra object files supplied to 0720 'add_link_object()' and/or 'set_link_objects()', the libraries 0721 supplied to 'add_library()' and/or 'set_libraries()', and the 0722 libraries supplied as 'libraries' (if any). 0723 0724 'output_libname' should be a library name, not a filename; the 0725 filename will be inferred from the library name. 'output_dir' is 0726 the directory where the library file will be put. 0727 0728 'debug' is a boolean; if true, debugging information will be 0729 included in the library (note that on most platforms, it is the 0730 compile step where this matters: the 'debug' flag is included here 0731 just for consistency). 0732 0733 'target_lang' is the target language for which the given objects 0734 are being compiled. This allows specific linkage time treatment of 0735 certain languages. 0736 0737 Raises LibError on failure. 0738 """ 0739 pass 0740 0741 0742 # values for target_desc parameter in link() 0743 SHARED_OBJECT = "shared_object" 0744 SHARED_LIBRARY = "shared_library" 0745 EXECUTABLE = "executable" 0746 0747 def link (self, 0748 target_desc, 0749 objects, 0750 output_filename, 0751 output_dir=None, 0752 libraries=None, 0753 library_dirs=None, 0754 runtime_library_dirs=None, 0755 export_symbols=None, 0756 debug=0, 0757 extra_preargs=None, 0758 extra_postargs=None, 0759 build_temp=None, 0760 target_lang=None): 0761 """Link a bunch of stuff together to create an executable or 0762 shared library file. 0763 0764 The "bunch of stuff" consists of the list of object files supplied 0765 as 'objects'. 'output_filename' should be a filename. If 0766 'output_dir' is supplied, 'output_filename' is relative to it 0767 (i.e. 'output_filename' can provide directory components if 0768 needed). 0769 0770 'libraries' is a list of libraries to link against. These are 0771 library names, not filenames, since they're translated into 0772 filenames in a platform-specific way (eg. "foo" becomes "libfoo.a" 0773 on Unix and "foo.lib" on DOS/Windows). However, they can include a 0774 directory component, which means the linker will look in that 0775 specific directory rather than searching all the normal locations. 0776 0777 'library_dirs', if supplied, should be a list of directories to 0778 search for libraries that were specified as bare library names 0779 (ie. no directory component). These are on top of the system 0780 default and those supplied to 'add_library_dir()' and/or 0781 'set_library_dirs()'. 'runtime_library_dirs' is a list of 0782 directories that will be embedded into the shared library and used 0783 to search for other shared libraries that *it* depends on at 0784 run-time. (This may only be relevant on Unix.) 0785 0786 'export_symbols' is a list of symbols that the shared library will 0787 export. (This appears to be relevant only on Windows.) 0788 0789 'debug' is as for 'compile()' and 'create_static_lib()', with the 0790 slight distinction that it actually matters on most platforms (as 0791 opposed to 'create_static_lib()', which includes a 'debug' flag 0792 mostly for form's sake). 0793 0794 'extra_preargs' and 'extra_postargs' are as for 'compile()' (except 0795 of course that they supply command-line arguments for the 0796 particular linker being used). 0797 0798 'target_lang' is the target language for which the given objects 0799 are being compiled. This allows specific linkage time treatment of 0800 certain languages. 0801 0802 Raises LinkError on failure. 0803 """ 0804 raise NotImplementedError 0805 0806 0807 # Old 'link_*()' methods, rewritten to use the new 'link()' method. 0808 0809 def link_shared_lib (self, 0810 objects, 0811 output_libname, 0812 output_dir=None, 0813 libraries=None, 0814 library_dirs=None, 0815 runtime_library_dirs=None, 0816 export_symbols=None, 0817 debug=0, 0818 extra_preargs=None, 0819 extra_postargs=None, 0820 build_temp=None, 0821 target_lang=None): 0822 self.link(CCompiler.SHARED_LIBRARY, objects, 0823 self.library_filename(output_libname, lib_type='shared'), 0824 output_dir, 0825 libraries, library_dirs, runtime_library_dirs, 0826 export_symbols, debug, 0827 extra_preargs, extra_postargs, build_temp, target_lang) 0828 0829 0830 def link_shared_object (self, 0831 objects, 0832 output_filename, 0833 output_dir=None, 0834 libraries=None, 0835 library_dirs=None, 0836 runtime_library_dirs=None, 0837 export_symbols=None, 0838 debug=0, 0839 extra_preargs=None, 0840 extra_postargs=None, 0841 build_temp=None, 0842 target_lang=None): 0843 self.link(CCompiler.SHARED_OBJECT, objects, 0844 output_filename, output_dir, 0845 libraries, library_dirs, runtime_library_dirs, 0846 export_symbols, debug, 0847 extra_preargs, extra_postargs, build_temp, target_lang) 0848 0849 0850 def link_executable (self, 0851 objects, 0852 output_progname, 0853 output_dir=None, 0854 libraries=None, 0855 library_dirs=None, 0856 runtime_library_dirs=None, 0857 debug=0, 0858 extra_preargs=None, 0859 extra_postargs=None, 0860 target_lang=None): 0861 self.link(CCompiler.EXECUTABLE, objects, 0862 self.executable_filename(output_progname), output_dir, 0863 libraries, library_dirs, runtime_library_dirs, None, 0864 debug, extra_preargs, extra_postargs, None, target_lang) 0865 0866 0867 # -- Miscellaneous methods ----------------------------------------- 0868 # These are all used by the 'gen_lib_options() function; there is 0869 # no appropriate default implementation so subclasses should 0870 # implement all of these. 0871 0872 def library_dir_option (self, dir): 0873 """Return the compiler option to add 'dir' to the list of 0874 directories searched for libraries. 0875 """ 0876 raise NotImplementedError 0877 0878 def runtime_library_dir_option (self, dir): 0879 """Return the compiler option to add 'dir' to the list of 0880 directories searched for runtime libraries. 0881 """ 0882 raise NotImplementedError 0883 0884 def library_option (self, lib): 0885 """Return the compiler option to add 'dir' to the list of libraries 0886 linked into the shared library or executable. 0887 """ 0888 raise NotImplementedError 0889 0890 def has_function(self, funcname, 0891 includes=None, 0892 include_dirs=None, 0893 libraries=None, 0894 library_dirs=None): 0895 """Return a boolean indicating whether funcname is supported on 0896 the current platform. The optional arguments can be used to 0897 augment the compilation environment. 0898 """ 0899 0900 # this can't be included at module scope because it tries to 0901 # import math which might not be available at that point - maybe 0902 # the necessary logic should just be inlined? 0903 import tempfile 0904 if includes is None: 0905 includes = [] 0906 if include_dirs is None: 0907 include_dirs = [] 0908 if libraries is None: 0909 libraries = [] 0910 if library_dirs is None: 0911 library_dirs = [] 0912 fd, fname = tempfile.mkstemp(".c", funcname, text=True) 0913 f = os.fdopen(fd, "w") 0914 for incl in includes: 0915 f.write("""#include "%s"\n""" % incl) 0916 f.write("""\ 0917 main (int argc, char **argv) { 0918 %s(); 0919 } 0920 """ % funcname) 0921 f.close() 0922 try: 0923 objects = self.compile([fname], include_dirs=include_dirs) 0924 except CompileError: 0925 return False 0926 0927 try: 0928 self.link_executable(objects, "a.out", 0929 libraries=libraries, 0930 library_dirs=library_dirs) 0931 except (LinkError, TypeError): 0932 return False 0933 return True 0934 0935 def find_library_file (self, dirs, lib, debug=0): 0936 """Search the specified list of directories for a static or shared 0937 library file 'lib' and return the full path to that file. If 0938 'debug' true, look for a debugging version (if that makes sense on 0939 the current platform). Return None if 'lib' wasn't found in any of 0940 the specified directories. 0941 """ 0942 raise NotImplementedError 0943 0944 # -- Filename generation methods ----------------------------------- 0945 0946 # The default implementation of the filename generating methods are 0947 # prejudiced towards the Unix/DOS/Windows view of the world: 0948 # * object files are named by replacing the source file extension 0949 # (eg. .c/.cpp -> .o/.obj) 0950 # * library files (shared or static) are named by plugging the 0951 # library name and extension into a format string, eg. 0952 # "lib%s.%s" % (lib_name, ".a") for Unix static libraries 0953 # * executables are named by appending an extension (possibly 0954 # empty) to the program name: eg. progname + ".exe" for 0955 # Windows 0956 # 0957 # To reduce redundant code, these methods expect to find 0958 # several attributes in the current object (presumably defined 0959 # as class attributes): 0960 # * src_extensions - 0961 # list of C/C++ source file extensions, eg. ['.c', '.cpp'] 0962 # * obj_extension - 0963 # object file extension, eg. '.o' or '.obj' 0964 # * static_lib_extension - 0965 # extension for static library files, eg. '.a' or '.lib' 0966 # * shared_lib_extension - 0967 # extension for shared library/object files, eg. '.so', '.dll' 0968 # * static_lib_format - 0969 # format string for generating static library filenames, 0970 # eg. 'lib%s.%s' or '%s.%s' 0971 # * shared_lib_format 0972 # format string for generating shared library filenames 0973 # (probably same as static_lib_format, since the extension 0974 # is one of the intended parameters to the format string) 0975 # * exe_extension - 0976 # extension for executable files, eg. '' or '.exe' 0977 0978 def object_filenames(self, source_filenames, strip_dir=0, output_dir=''): 0979 if output_dir is None: 0980 output_dir = '' 0981 obj_names = [] 0982 for src_name in source_filenames: 0983 base, ext = os.path.splitext(src_name) 0984 base = os.path.splitdrive(base)[1] # Chop off the drive 0985 base = base[os.path.isabs(base):] # If abs, chop off leading / 0986 if ext not in self.src_extensions: 0987 raise UnknownFileError, \ 0988 "unknown file type '%s' (from '%s')" % (ext, src_name) 0989 if strip_dir: 0990 base = os.path.basename(base) 0991 obj_names.append(os.path.join(output_dir, 0992 base + self.obj_extension)) 0993 return obj_names 0994 0995 def shared_object_filename(self, basename, strip_dir=0, output_dir=''): 0996 assert output_dir is not None 0997 if strip_dir: 0998 basename = os.path.basename (basename) 0999 return os.path.join(output_dir, basename + self.shared_lib_extension) 1000 1001 def executable_filename(self, basename, strip_dir=0, output_dir=''): 1002 assert output_dir is not None 1003 if strip_dir: 1004 basename = os.path.basename (basename) 1005 return os.path.join(output_dir, basename + (self.exe_extension or '')) 1006 1007 def library_filename(self, libname, lib_type='static', # or 'shared' 1008 strip_dir=0, output_dir=''): 1009 assert output_dir is not None 1010 if lib_type not in ("static", "shared", "dylib"): 1011 raise ValueError, "'lib_type' must be \"static\", \"shared\" or \"dylib\"" 1012 fmt = getattr(self, lib_type + "_lib_format") 1013 ext = getattr(self, lib_type + "_lib_extension") 1014 1015 dir, base = os.path.split (libname) 1016 filename = fmt % (base, ext) 1017 if strip_dir: 1018 dir = '' 1019 1020 return os.path.join(output_dir, dir, filename) 1021 1022 1023 # -- Utility methods ----------------------------------------------- 1024 1025 def announce (self, msg, level=1): 1026 log.debug(msg) 1027 1028 def debug_print (self, msg): 1029 from distutils.debug import DEBUG 1030 if DEBUG: 1031 print msg 1032 1033 def warn (self, msg): 1034 sys.stderr.write ("warning: %s\n" % msg) 1035 1036 def execute (self, func, args, msg=None, level=1): 1037 execute(func, args, msg, self.dry_run) 1038 1039 def spawn (self, cmd): 1040 spawn (cmd, dry_run=self.dry_run) 1041 1042 def move_file (self, src, dst): 1043 return move_file (src, dst, dry_run=self.dry_run) 1044 1045 def mkpath (self, name, mode=0777): 1046 mkpath (name, mode, self.dry_run) 1047 1048 1049 # class CCompiler 1050 1051 1052 # Map a sys.platform/os.name ('posix', 'nt') to the default compiler 1053 # type for that platform. Keys are interpreted as re match 1054 # patterns. Order is important; platform mappings are preferred over 1055 # OS names. 1056 _default_compilers = ( 1057 1058 # Platform string mappings 1059 1060 # on a cygwin built python we can use gcc like an ordinary UNIXish 1061 # compiler 1062 ('cygwin.*', 'unix'), 1063 ('os2emx', 'emx'), 1064 1065 # OS name mappings 1066 ('posix', 'unix'), 1067 ('nt', 'msvc'), 1068 ('mac', 'mwerks'), 1069 1070 ) 1071 1072 def get_default_compiler(osname=None, platform=None): 1073 1074 """ Determine the default compiler to use for the given platform. 1075 1076 osname should be one of the standard Python OS names (i.e. the 1077 ones returned by os.name) and platform the common value 1078 returned by sys.platform for the platform in question. 1079 1080 The default values are os.name and sys.platform in case the 1081 parameters are not given. 1082 1083 """ 1084 if osname is None: 1085 osname = os.name 1086 if platform is None: 1087 platform = sys.platform 1088 for pattern, compiler in _default_compilers: 1089 if re.match(pattern, platform) is not None or \ 1090 re.match(pattern, osname) is not None: 1091 return compiler 1092 # Default to Unix compiler 1093 return 'unix' 1094 1095 # Map compiler types to (module_name, class_name) pairs -- ie. where to 1096 # find the code that implements an interface to this compiler. (The module 1097 # is assumed to be in the 'distutils' package.) 1098 compiler_class = { 'unix': ('unixccompiler', 'UnixCCompiler', 1099 "standard UNIX-style compiler"), 1100 'msvc': ('msvccompiler', 'MSVCCompiler', 1101 "Microsoft Visual C++"), 1102 'cygwin': ('cygwinccompiler', 'CygwinCCompiler', 1103 "Cygwin port of GNU C Compiler for Win32"), 1104 'mingw32': ('cygwinccompiler', 'Mingw32CCompiler', 1105 "Mingw32 port of GNU C Compiler for Win32"), 1106 'bcpp': ('bcppcompiler', 'BCPPCompiler', 1107 "Borland C++ Compiler"), 1108 'mwerks': ('mwerkscompiler', 'MWerksCompiler', 1109 "MetroWerks CodeWarrior"), 1110 'emx': ('emxccompiler', 'EMXCCompiler', 1111 "EMX port of GNU C Compiler for OS/2"), 1112 } 1113 1114 def show_compilers(): 1115 """Print list of available compilers (used by the "--help-compiler" 1116 options to "build", "build_ext", "build_clib"). 1117 """ 1118 # XXX this "knows" that the compiler option it's describing is 1119 # "--compiler", which just happens to be the case for the three 1120 # commands that use it. 1121 from distutils.fancy_getopt import FancyGetopt 1122 compilers = [] 1123 for compiler in compiler_class.keys(): 1124 compilers.append(("compiler="+compiler, None, 1125 compiler_class[compiler][2])) 1126 compilers.sort() 1127 pretty_printer = FancyGetopt(compilers) 1128 pretty_printer.print_help("List of available compilers:") 1129 1130 1131 def new_compiler (plat=None, 1132 compiler=None, 1133 verbose=0, 1134 dry_run=0, 1135 force=0): 1136 """Generate an instance of some CCompiler subclass for the supplied 1137 platform/compiler combination. 'plat' defaults to 'os.name' 1138 (eg. 'posix', 'nt'), and 'compiler' defaults to the default compiler 1139 for that platform. Currently only 'posix' and 'nt' are supported, and 1140 the default compilers are "traditional Unix interface" (UnixCCompiler 1141 class) and Visual C++ (MSVCCompiler class). Note that it's perfectly 1142 possible to ask for a Unix compiler object under Windows, and a 1143 Microsoft compiler object under Unix -- if you supply a value for 1144 'compiler', 'plat' is ignored. 1145 """ 1146 if plat is None: 1147 plat = os.name 1148 1149 try: 1150 if compiler is None: 1151 compiler = get_default_compiler(plat) 1152 1153 (module_name, class_name, long_description) = compiler_class[compiler] 1154 except KeyError: 1155 msg = "don't know how to compile C/C++ code on platform '%s'" % plat 1156 if compiler is not None: 1157 msg = msg + " with '%s' compiler" % compiler 1158 raise DistutilsPlatformError, msg 1159 1160 try: 1161 module_name = "distutils." + module_name 1162 __import__ (module_name) 1163 module = sys.modules[module_name] 1164 klass = vars(module)[class_name] 1165 except ImportError: 1166 raise DistutilsModuleError, \ 1167 "can't compile C/C++ code: unable to load module '%s'" % \ 1168 module_name 1169 except KeyError: 1170 raise DistutilsModuleError, \ 1171 ("can't compile C/C++ code: unable to find class '%s' " + 1172 "in module '%s'") % (class_name, module_name) 1173 1174 # XXX The None is necessary to preserve backwards compatibility 1175 # with classes that expect verbose to be the first positional 1176 # argument. 1177 return klass (None, dry_run, force) 1178 1179 1180 def gen_preprocess_options (macros, include_dirs): 1181 """Generate C pre-processor options (-D, -U, -I) as used by at least 1182 two types of compilers: the typical Unix compiler and Visual C++. 1183 'macros' is the usual thing, a list of 1- or 2-tuples, where (name,) 1184 means undefine (-U) macro 'name', and (name,value) means define (-D) 1185 macro 'name' to 'value'. 'include_dirs' is just a list of directory 1186 names to be added to the header file search path (-I). Returns a list 1187 of command-line options suitable for either Unix compilers or Visual 1188 C++. 1189 """ 1190 # XXX it would be nice (mainly aesthetic, and so we don't generate 1191 # stupid-looking command lines) to go over 'macros' and eliminate 1192 # redundant definitions/undefinitions (ie. ensure that only the 1193 # latest mention of a particular macro winds up on the command 1194 # line). I don't think it's essential, though, since most (all?) 1195 # Unix C compilers only pay attention to the latest -D or -U 1196 # mention of a macro on their command line. Similar situation for 1197 # 'include_dirs'. I'm punting on both for now. Anyways, weeding out 1198 # redundancies like this should probably be the province of 1199 # CCompiler, since the data structures used are inherited from it 1200 # and therefore common to all CCompiler classes. 1201 1202 pp_opts = [] 1203 for macro in macros: 1204 1205 if not (type (macro) is TupleType and 1206 1 <= len (macro) <= 2): 1207 raise TypeError, \ 1208 ("bad macro definition '%s': " + 1209 "each element of 'macros' list must be a 1- or 2-tuple") % \ 1210 macro 1211 1212 if len (macro) == 1: # undefine this macro 1213 pp_opts.append ("-U%s" % macro[0]) 1214 elif len (macro) == 2: 1215 if macro[1] is None: # define with no explicit value 1216 pp_opts.append ("-D%s" % macro[0]) 1217 else: 1218 # XXX *don't* need to be clever about quoting the 1219 # macro value here, because we're going to avoid the 1220 # shell at all costs when we spawn the command! 1221 pp_opts.append ("-D%s=%s" % macro) 1222 1223 for dir in include_dirs: 1224 pp_opts.append ("-I%s" % dir) 1225 1226 return pp_opts 1227 1228 # gen_preprocess_options () 1229 1230 1231 def gen_lib_options (compiler, library_dirs, runtime_library_dirs, libraries): 1232 """Generate linker options for searching library directories and 1233 linking with specific libraries. 'libraries' and 'library_dirs' are, 1234 respectively, lists of library names (not filenames!) and search 1235 directories. Returns a list of command-line options suitable for use 1236 with some compiler (depending on the two format strings passed in). 1237 """ 1238 lib_opts = [] 1239 1240 for dir in library_dirs: 1241 lib_opts.append (compiler.library_dir_option (dir)) 1242 1243 for dir in runtime_library_dirs: 1244 opt = compiler.runtime_library_dir_option (dir) 1245 if type(opt) is ListType: 1246 lib_opts = lib_opts + opt 1247 else: 1248 lib_opts.append (opt) 1249 1250 # XXX it's important that we *not* remove redundant library mentions! 1251 # sometimes you really do have to say "-lfoo -lbar -lfoo" in order to 1252 # resolve all symbols. I just hope we never have to say "-lfoo obj.o 1253 # -lbar" to get things to work -- that's certainly a possibility, but a 1254 # pretty nasty way to arrange your C code. 1255 1256 for lib in libraries: 1257 (lib_dir, lib_name) = os.path.split (lib) 1258 if lib_dir: 1259 lib_file = compiler.find_library_file ([lib_dir], lib_name) 1260 if lib_file: 1261 lib_opts.append (lib_file) 1262 else: 1263 compiler.warn ("no library file corresponding to " 1264 "'%s' found (skipping)" % lib) 1265 else: 1266 lib_opts.append (compiler.library_option (lib)) 1267 1268 return lib_opts 1269 1270 # gen_lib_options () 1271
Generated by PyXR 0.9.4