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