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