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