1"""distutils.ccompiler 2 3Contains CCompiler, an abstract base class that defines the interface 4for the Distutils compiler abstraction model.""" 5 6import sys, os, re 7from distutils.errors import ( 8 DistutilsModuleError, DistutilsPlatformError, 9) 10from distutils.util import split_quoted 11 12class CCompiler: 13 """Abstract base class to define the interface that must be implemented 14 by real compiler classes. Also has some utility methods used by 15 several compiler classes. 16 17 The basic idea behind a compiler abstraction class is that each 18 instance can be used for all the compile/link steps in building a 19 single project. Thus, attributes common to all of those compile and 20 link steps -- include directories, macros to define, libraries to link 21 against, etc. -- are attributes of the compiler instance. To allow for 22 variability in how individual files are treated, most of those 23 attributes may be varied on a per-compilation or per-link basis. 24 """ 25 26 # 'compiler_type' is a class attribute that identifies this class. It 27 # keeps code that wants to know what kind of compiler it's dealing with 28 # from having to import all possible compiler classes just to do an 29 # 'isinstance'. In concrete CCompiler subclasses, 'compiler_type' 30 # should really, really be one of the keys of the 'compiler_class' 31 # dictionary (see below -- used by the 'new_compiler()' factory 32 # function) -- authors of new compiler interface classes are 33 # responsible for updating 'compiler_class'! 34 compiler_type = None 35 36 # XXX things not handled by this compiler abstraction model: 37 # * client can't provide additional options for a compiler, 38 # e.g. warning, optimization, debugging flags. Perhaps this 39 # should be the domain of concrete compiler abstraction classes 40 # (UnixCCompiler, MSVCCompiler, etc.) -- or perhaps the base 41 # class should have methods for the common ones. 42 # * can't completely override the include or library searchg 43 # path, ie. no "cc -I -Idir1 -Idir2" or "cc -L -Ldir1 -Ldir2". 44 # I'm not sure how widely supported this is even by Unix 45 # compilers, much less on other platforms. And I'm even less 46 # sure how useful it is; maybe for cross-compiling, but 47 # support for that is a ways off. (And anyways, cross 48 # compilers probably have a dedicated binary with the 49 # right paths compiled in. I hope.) 50 # * can't do really freaky things with the library list/library 51 # dirs, e.g. "-Ldir1 -lfoo -Ldir2 -lfoo" to link against 52 # different versions of libfoo.a in different locations. I 53 # think this is useless without the ability to null out the 54 # library search path anyways. 55 56 57 # Subclasses that rely on the standard filename generation methods 58 # implemented below should override these; see the comment near 59 # those methods ('object_filenames()' et. al.) for details: 60 src_extensions = None # list of strings 61 obj_extension = None # string 62 static_lib_extension = None 63 shared_lib_extension = None # string 64 static_lib_format = None # format string 65 shared_lib_format = None # prob. same as static_lib_format 66 exe_extension = None # string 67 68 # Default language settings. language_map is used to detect a source 69 # file or Extension target language, checking source filenames. 70 # language_order is used to detect the language precedence, when deciding 71 # what language to use when mixing source types. For example, if some 72 # extension has two files with ".c" extension, and one with ".cpp", it 73 # is still linked as c++. 74 language_map = {".c" : "c", 75 ".cc" : "c++", 76 ".cpp" : "c++", 77 ".cxx" : "c++", 78 ".m" : "objc", 79 } 80 language_order = ["c++", "objc", "c"] 81 82 def __init__(self, verbose=0, dry_run=0, force=0): 83 self.dry_run = dry_run 84 self.force = force 85 self.verbose = verbose 86 87 # 'output_dir': a common output directory for object, library, 88 # shared object, and shared library files 89 self.output_dir = None 90 91 # 'macros': a list of macro definitions (or undefinitions). A 92 # macro definition is a 2-tuple (name, value), where the value is 93 # either a string or None (no explicit value). A macro 94 # undefinition is a 1-tuple (name,). 95 self.macros = [] 96 97 # 'include_dirs': a list of directories to search for include files 98 self.include_dirs = [] 99 100 # 'libraries': a list of libraries to include in any link 101 # (library names, not filenames: eg. "foo" not "libfoo.a") 102 self.libraries = [] 103 104 # 'library_dirs': a list of directories to search for libraries 105 self.library_dirs = [] 106 107 # 'runtime_library_dirs': a list of directories to search for 108 # shared libraries/objects at runtime 109 self.runtime_library_dirs = [] 110 111 # 'objects': a list of object files (or similar, such as explicitly 112 # named library files) to include on any link 113 self.objects = [] 114 115 for key in self.executables.keys(): 116 self.set_executable(key, self.executables[key]) 117 118 def set_executables(self, **kwargs): 119 """Define the executables (and options for them) that will be run 120 to perform the various stages of compilation. The exact set of 121 executables that may be specified here depends on the compiler 122 class (via the 'executables' class attribute), but most will have: 123 compiler the C/C++ compiler 124 linker_so linker used to create shared objects and libraries 125 linker_exe linker used to create binary executables 126 archiver static library creator 127 128 On platforms with a command-line (Unix, DOS/Windows), each of these 129 is a string that will be split into executable name and (optional) 130 list of arguments. (Splitting the string is done similarly to how 131 Unix shells operate: words are delimited by spaces, but quotes and 132 backslashes can override this. See 133 'distutils.util.split_quoted()'.) 134 """ 135 136 # Note that some CCompiler implementation classes will define class 137 # attributes 'cpp', 'cc', etc. with hard-coded executable names; 138 # this is appropriate when a compiler class is for exactly one 139 # compiler/OS combination (eg. MSVCCompiler). Other compiler 140 # classes (UnixCCompiler, in particular) are driven by information 141 # discovered at run-time, since there are many different ways to do 142 # basically the same things with Unix C compilers. 143 144 for key in kwargs: 145 if key not in self.executables: 146 raise ValueError("unknown executable '%s' for class %s" % 147 (key, self.__class__.__name__)) 148 self.set_executable(key, kwargs[key]) 149 150 def set_executable(self, key, value): 151 if isinstance(value, str): 152 setattr(self, key, split_quoted(value)) 153 else: 154 setattr(self, key, value) 155 156 def _find_macro(self, name): 157 i = 0 158 for defn in self.macros: 159 if defn[0] == name: 160 return i 161 i += 1 162 return None 163 164 def _check_macro_definitions(self, definitions): 165 """Ensures that every element of 'definitions' is a valid macro 166 definition, ie. either (name,value) 2-tuple or a (name,) tuple. Do 167 nothing if all definitions are OK, raise TypeError otherwise. 168 """ 169 for defn in definitions: 170 if not (isinstance(defn, tuple) and 171 (len(defn) in (1, 2) and 172 (isinstance (defn[1], str) or defn[1] is None)) and 173 isinstance (defn[0], str)): 174 raise TypeError(("invalid macro definition '%s': " % defn) + \ 175 "must be tuple (string,), (string, string), or " + \ 176 "(string, None)") 177 178 179 # -- Bookkeeping methods ------------------------------------------- 180 181 def define_macro(self, name, value=None): 182 """Define a preprocessor macro for all compilations driven by this 183 compiler object. The optional parameter 'value' should be a 184 string; if it is not supplied, then the macro will be defined 185 without an explicit value and the exact outcome depends on the 186 compiler used (XXX true? does ANSI say anything about this?) 187 """ 188 # Delete from the list of macro definitions/undefinitions if 189 # already there (so that this one will take precedence). 190 i = self._find_macro (name) 191 if i is not None: 192 del self.macros[i] 193 194 self.macros.append((name, value)) 195 196 def undefine_macro(self, name): 197 """Undefine a preprocessor macro for all compilations driven by 198 this compiler object. If the same macro is defined by 199 'define_macro()' and undefined by 'undefine_macro()' the last call 200 takes precedence (including multiple redefinitions or 201 undefinitions). If the macro is redefined/undefined on a 202 per-compilation basis (ie. in the call to 'compile()'), then that 203 takes precedence. 204 """ 205 # Delete from the list of macro definitions/undefinitions if 206 # already there (so that this one will take precedence). 207 i = self._find_macro (name) 208 if i is not None: 209 del self.macros[i] 210 211 undefn = (name,) 212 self.macros.append(undefn) 213 214 def add_include_dir(self, dir): 215 """Add 'dir' to the list of directories that will be searched for 216 header files. The compiler is instructed to search directories in 217 the order in which they are supplied by successive calls to 218 'add_include_dir()'. 219 """ 220 self.include_dirs.append(dir) 221 222 def set_include_dirs(self, dirs): 223 """Set the list of directories that will be searched to 'dirs' (a 224 list of strings). Overrides any preceding calls to 225 'add_include_dir()'; subsequence calls to 'add_include_dir()' add 226 to the list passed to 'set_include_dirs()'. This does not affect 227 any list of standard include directories that the compiler may 228 search by default. 229 """ 230 self.include_dirs = dirs[:] 231 232 233 # -- Private utility methods -------------------------------------- 234 # (here for the convenience of subclasses) 235 236 # Helper method to prep compiler in subclass compile() methods 237 238 def _fix_compile_args(self, output_dir, macros, include_dirs): 239 """Typecheck and fix-up some of the arguments to the 'compile()' 240 method, and return fixed-up values. Specifically: if 'output_dir' 241 is None, replaces it with 'self.output_dir'; ensures that 'macros' 242 is a list, and augments it with 'self.macros'; ensures that 243 'include_dirs' is a list, and augments it with 'self.include_dirs'. 244 Guarantees that the returned values are of the correct type, 245 i.e. for 'output_dir' either string or None, and for 'macros' and 246 'include_dirs' either list or None. 247 """ 248 if output_dir is None: 249 output_dir = self.output_dir 250 elif not isinstance(output_dir, str): 251 raise TypeError("'output_dir' must be a string or None") 252 253 if macros is None: 254 macros = self.macros 255 elif isinstance(macros, list): 256 macros = macros + (self.macros or []) 257 else: 258 raise TypeError("'macros' (if supplied) must be a list of tuples") 259 260 if include_dirs is None: 261 include_dirs = self.include_dirs 262 elif isinstance(include_dirs, (list, tuple)): 263 include_dirs = list(include_dirs) + (self.include_dirs or []) 264 else: 265 raise TypeError( 266 "'include_dirs' (if supplied) must be a list of strings") 267 268 return output_dir, macros, include_dirs 269 270 271 # -- Worker methods ------------------------------------------------ 272 # (must be implemented by subclasses) 273 274 def preprocess(self, source, output_file=None, macros=None, 275 include_dirs=None, extra_preargs=None, extra_postargs=None): 276 """Preprocess a single C/C++ source file, named in 'source'. 277 Output will be written to file named 'output_file', or stdout if 278 'output_file' not supplied. 'macros' is a list of macro 279 definitions as for 'compile()', which will augment the macros set 280 with 'define_macro()' and 'undefine_macro()'. 'include_dirs' is a 281 list of directory names that will be added to the default list. 282 283 Raises PreprocessError on failure. 284 """ 285 pass 286 287 288 # -- Miscellaneous methods ----------------------------------------- 289 # These are all used by the 'gen_lib_options() function; there is 290 # no appropriate default implementation so subclasses should 291 # implement all of these. 292 293# def library_dir_option(self, dir): 294# """Return the compiler option to add 'dir' to the list of 295# directories searched for libraries. 296# """ 297# raise NotImplementedError 298# 299# def runtime_library_dir_option(self, dir): 300# """Return the compiler option to add 'dir' to the list of 301# directories searched for runtime libraries. 302# """ 303# raise NotImplementedError 304# 305# def library_option(self, lib): 306# """Return the compiler option to add 'lib' to the list of libraries 307# linked into the shared library or executable. 308# """ 309# raise NotImplementedError 310# 311# def find_library_file (self, dirs, lib, debug=0): 312# """Search the specified list of directories for a static or shared 313# library file 'lib' and return the full path to that file. If 314# 'debug' true, look for a debugging version (if that makes sense on 315# the current platform). Return None if 'lib' wasn't found in any of 316# the specified directories. 317# """ 318# raise NotImplementedError 319 320 321 # -- Utility methods ----------------------------------------------- 322 323 def spawn(self, cmd): 324 raise NotImplementedError 325 326 327# Map a sys.platform/os.name ('posix', 'nt') to the default compiler 328# type for that platform. Keys are interpreted as re match 329# patterns. Order is important; platform mappings are preferred over 330# OS names. 331_default_compilers = ( 332 333 # Platform string mappings 334 335 # on a cygwin built python we can use gcc like an ordinary UNIXish 336 # compiler 337 ('cygwin.*', 'unix'), 338 339 # OS name mappings 340 ('posix', 'unix'), 341 ('nt', 'msvc'), 342 343 ) 344 345def get_default_compiler(osname=None, platform=None): 346 """Determine the default compiler to use for the given platform. 347 348 osname should be one of the standard Python OS names (i.e. the 349 ones returned by os.name) and platform the common value 350 returned by sys.platform for the platform in question. 351 352 The default values are os.name and sys.platform in case the 353 parameters are not given. 354 """ 355 if osname is None: 356 osname = os.name 357 if platform is None: 358 platform = sys.platform 359 for pattern, compiler in _default_compilers: 360 if re.match(pattern, platform) is not None or \ 361 re.match(pattern, osname) is not None: 362 return compiler 363 # Default to Unix compiler 364 return 'unix' 365 366# Map compiler types to (module_name, class_name) pairs -- ie. where to 367# find the code that implements an interface to this compiler. (The module 368# is assumed to be in the 'distutils' package.) 369compiler_class = { 'unix': ('unixccompiler', 'UnixCCompiler', 370 "standard UNIX-style compiler"), 371 'msvc': ('_msvccompiler', 'MSVCCompiler', 372 "Microsoft Visual C++"), 373 'cygwin': ('cygwinccompiler', 'CygwinCCompiler', 374 "Cygwin port of GNU C Compiler for Win32"), 375 'mingw32': ('cygwinccompiler', 'Mingw32CCompiler', 376 "Mingw32 port of GNU C Compiler for Win32"), 377 'bcpp': ('bcppcompiler', 'BCPPCompiler', 378 "Borland C++ Compiler"), 379 } 380 381 382def new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0): 383 """Generate an instance of some CCompiler subclass for the supplied 384 platform/compiler combination. 'plat' defaults to 'os.name' 385 (eg. 'posix', 'nt'), and 'compiler' defaults to the default compiler 386 for that platform. Currently only 'posix' and 'nt' are supported, and 387 the default compilers are "traditional Unix interface" (UnixCCompiler 388 class) and Visual C++ (MSVCCompiler class). Note that it's perfectly 389 possible to ask for a Unix compiler object under Windows, and a 390 Microsoft compiler object under Unix -- if you supply a value for 391 'compiler', 'plat' is ignored. 392 """ 393 if plat is None: 394 plat = os.name 395 396 try: 397 if compiler is None: 398 compiler = get_default_compiler(plat) 399 400 (module_name, class_name, long_description) = compiler_class[compiler] 401 except KeyError: 402 msg = "don't know how to compile C/C++ code on platform '%s'" % plat 403 if compiler is not None: 404 msg = msg + " with '%s' compiler" % compiler 405 raise DistutilsPlatformError(msg) 406 407 try: 408 module_name = "distutils." + module_name 409 __import__ (module_name) 410 module = sys.modules[module_name] 411 klass = vars(module)[class_name] 412 except ImportError: 413 raise 414 raise DistutilsModuleError( 415 "can't compile C/C++ code: unable to load module '%s'" % \ 416 module_name) 417 except KeyError: 418 raise DistutilsModuleError( 419 "can't compile C/C++ code: unable to find class '%s' " 420 "in module '%s'" % (class_name, module_name)) 421 422 # XXX The None is necessary to preserve backwards compatibility 423 # with classes that expect verbose to be the first positional 424 # argument. 425 return klass(None, dry_run, force) 426 427 428def gen_preprocess_options(macros, include_dirs): 429 """Generate C pre-processor options (-D, -U, -I) as used by at least 430 two types of compilers: the typical Unix compiler and Visual C++. 431 'macros' is the usual thing, a list of 1- or 2-tuples, where (name,) 432 means undefine (-U) macro 'name', and (name,value) means define (-D) 433 macro 'name' to 'value'. 'include_dirs' is just a list of directory 434 names to be added to the header file search path (-I). Returns a list 435 of command-line options suitable for either Unix compilers or Visual 436 C++. 437 """ 438 # XXX it would be nice (mainly aesthetic, and so we don't generate 439 # stupid-looking command lines) to go over 'macros' and eliminate 440 # redundant definitions/undefinitions (ie. ensure that only the 441 # latest mention of a particular macro winds up on the command 442 # line). I don't think it's essential, though, since most (all?) 443 # Unix C compilers only pay attention to the latest -D or -U 444 # mention of a macro on their command line. Similar situation for 445 # 'include_dirs'. I'm punting on both for now. Anyways, weeding out 446 # redundancies like this should probably be the province of 447 # CCompiler, since the data structures used are inherited from it 448 # and therefore common to all CCompiler classes. 449 pp_opts = [] 450 for macro in macros: 451 if not (isinstance(macro, tuple) and 1 <= len(macro) <= 2): 452 raise TypeError( 453 "bad macro definition '%s': " 454 "each element of 'macros' list must be a 1- or 2-tuple" 455 % macro) 456 457 if len(macro) == 1: # undefine this macro 458 pp_opts.append("-U%s" % macro[0]) 459 elif len(macro) == 2: 460 if macro[1] is None: # define with no explicit value 461 pp_opts.append("-D%s" % macro[0]) 462 else: 463 # XXX *don't* need to be clever about quoting the 464 # macro value here, because we're going to avoid the 465 # shell at all costs when we spawn the command! 466 pp_opts.append("-D%s=%s" % macro) 467 468 for dir in include_dirs: 469 pp_opts.append("-I%s" % dir) 470 return pp_opts 471