]> git.saurik.com Git - wxWidgets.git/blame - wxPython/distutils/ccompiler.py
Renamed the core namespace's submodules to have a leading underscore.
[wxWidgets.git] / wxPython / distutils / ccompiler.py
CommitLineData
1e4a197e
RD
1"""distutils.ccompiler
2
3Contains CCompiler, an abstract base class that defines the interface
4for the Distutils compiler abstraction model."""
5
6# This module should be kept compatible with Python 1.5.2.
7
8__revision__ = "$Id$"
9
10import sys, os, re
11from types import *
12from copy import copy
13from distutils.errors import *
14from distutils.spawn import spawn
15from distutils.file_util import move_file
16from distutils.dir_util import mkpath
17from distutils.dep_util import newer_pairwise, newer_group
18from distutils.sysconfig import python_build
19from distutils.util import split_quoted, execute
20from distutils import log
21
22class CCompiler:
23 """Abstract base class to define the interface that must be implemented
24 by real compiler classes. Also has some utility methods used by
25 several compiler classes.
26
27 The basic idea behind a compiler abstraction class is that each
28 instance can be used for all the compile/link steps in building a
29 single project. Thus, attributes common to all of those compile and
30 link steps -- include directories, macros to define, libraries to link
31 against, etc. -- are attributes of the compiler instance. To allow for
32 variability in how individual files are treated, most of those
33 attributes may be varied on a per-compilation or per-link basis.
34 """
35
36 # 'compiler_type' is a class attribute that identifies this class. It
37 # keeps code that wants to know what kind of compiler it's dealing with
38 # from having to import all possible compiler classes just to do an
39 # 'isinstance'. In concrete CCompiler subclasses, 'compiler_type'
40 # should really, really be one of the keys of the 'compiler_class'
41 # dictionary (see below -- used by the 'new_compiler()' factory
42 # function) -- authors of new compiler interface classes are
43 # responsible for updating 'compiler_class'!
44 compiler_type = None
45
46 # XXX things not handled by this compiler abstraction model:
47 # * client can't provide additional options for a compiler,
48 # e.g. warning, optimization, debugging flags. Perhaps this
49 # should be the domain of concrete compiler abstraction classes
50 # (UnixCCompiler, MSVCCompiler, etc.) -- or perhaps the base
51 # class should have methods for the common ones.
52 # * can't completely override the include or library searchg
53 # path, ie. no "cc -I -Idir1 -Idir2" or "cc -L -Ldir1 -Ldir2".
54 # I'm not sure how widely supported this is even by Unix
55 # compilers, much less on other platforms. And I'm even less
56 # sure how useful it is; maybe for cross-compiling, but
57 # support for that is a ways off. (And anyways, cross
58 # compilers probably have a dedicated binary with the
59 # right paths compiled in. I hope.)
60 # * can't do really freaky things with the library list/library
61 # dirs, e.g. "-Ldir1 -lfoo -Ldir2 -lfoo" to link against
62 # different versions of libfoo.a in different locations. I
63 # think this is useless without the ability to null out the
64 # library search path anyways.
65
66
67 # Subclasses that rely on the standard filename generation methods
68 # implemented below should override these; see the comment near
69 # those methods ('object_filenames()' et. al.) for details:
70 src_extensions = None # list of strings
71 obj_extension = None # string
72 static_lib_extension = None
73 shared_lib_extension = None # string
74 static_lib_format = None # format string
75 shared_lib_format = None # prob. same as static_lib_format
76 exe_extension = None # string
77
78 # Default language settings. language_map is used to detect a source
79 # file or Extension target language, checking source filenames.
80 # language_order is used to detect the language precedence, when deciding
81 # what language to use when mixing source types. For example, if some
82 # extension has two files with ".c" extension, and one with ".cpp", it
83 # is still linked as c++.
84 language_map = {".c" : "c",
85 ".cc" : "c++",
86 ".cpp" : "c++",
87 ".cxx" : "c++",
88 ".m" : "objc",
89 }
90 language_order = ["c++", "objc", "c"]
91
92 def __init__ (self,
93 verbose=0,
94 dry_run=0,
95 force=0):
96
97 self.dry_run = dry_run
98 self.force = force
99 self.verbose = verbose
100
101 # 'output_dir': a common output directory for object, library,
102 # shared object, and shared library files
103 self.output_dir = None
104
105 # 'macros': a list of macro definitions (or undefinitions). A
106 # macro definition is a 2-tuple (name, value), where the value is
107 # either a string or None (no explicit value). A macro
108 # undefinition is a 1-tuple (name,).
109 self.macros = []
110
111 # 'include_dirs': a list of directories to search for include files
112 self.include_dirs = []
113
114 # 'libraries': a list of libraries to include in any link
115 # (library names, not filenames: eg. "foo" not "libfoo.a")
116 self.libraries = []
117
118 # 'library_dirs': a list of directories to search for libraries
119 self.library_dirs = []
120
121 # 'runtime_library_dirs': a list of directories to search for
122 # shared libraries/objects at runtime
123 self.runtime_library_dirs = []
124
125 # 'objects': a list of object files (or similar, such as explicitly
126 # named library files) to include on any link
127 self.objects = []
128
129 for key in self.executables.keys():
130 self.set_executable(key, self.executables[key])
131
132 # __init__ ()
133
134
135 def set_executables (self, **args):
136
137 """Define the executables (and options for them) that will be run
138 to perform the various stages of compilation. The exact set of
139 executables that may be specified here depends on the compiler
140 class (via the 'executables' class attribute), but most will have:
141 compiler the C/C++ compiler
142 linker_so linker used to create shared objects and libraries
143 linker_exe linker used to create binary executables
144 archiver static library creator
145
146 On platforms with a command-line (Unix, DOS/Windows), each of these
147 is a string that will be split into executable name and (optional)
148 list of arguments. (Splitting the string is done similarly to how
149 Unix shells operate: words are delimited by spaces, but quotes and
150 backslashes can override this. See
151 'distutils.util.split_quoted()'.)
152 """
153
154 # Note that some CCompiler implementation classes will define class
155 # attributes 'cpp', 'cc', etc. with hard-coded executable names;
156 # this is appropriate when a compiler class is for exactly one
157 # compiler/OS combination (eg. MSVCCompiler). Other compiler
158 # classes (UnixCCompiler, in particular) are driven by information
159 # discovered at run-time, since there are many different ways to do
160 # basically the same things with Unix C compilers.
161
162 for key in args.keys():
163 if not self.executables.has_key(key):
164 raise ValueError, \
165 "unknown executable '%s' for class %s" % \
166 (key, self.__class__.__name__)
167 self.set_executable(key, args[key])
168
169 # set_executables ()
170
171 def set_executable(self, key, value):
172 if type(value) is StringType:
173 setattr(self, key, split_quoted(value))
174 else:
175 setattr(self, key, value)
176
177
178 def _find_macro (self, name):
179 i = 0
180 for defn in self.macros:
181 if defn[0] == name:
182 return i
183 i = i + 1
184
185 return None
186
187
188 def _check_macro_definitions (self, definitions):
189 """Ensures that every element of 'definitions' is a valid macro
190 definition, ie. either (name,value) 2-tuple or a (name,) tuple. Do
191 nothing if all definitions are OK, raise TypeError otherwise.
192 """
193 for defn in definitions:
194 if not (type (defn) is TupleType and
195 (len (defn) == 1 or
196 (len (defn) == 2 and
197 (type (defn[1]) is StringType or defn[1] is None))) and
198 type (defn[0]) is StringType):
199 raise TypeError, \
200 ("invalid macro definition '%s': " % defn) + \
201 "must be tuple (string,), (string, string), or " + \
202 "(string, None)"
203
204
205 # -- Bookkeeping methods -------------------------------------------
206
207 def define_macro (self, name, value=None):
208 """Define a preprocessor macro for all compilations driven by this
209 compiler object. The optional parameter 'value' should be a
210 string; if it is not supplied, then the macro will be defined
211 without an explicit value and the exact outcome depends on the
212 compiler used (XXX true? does ANSI say anything about this?)
213 """
214 # Delete from the list of macro definitions/undefinitions if
215 # already there (so that this one will take precedence).
216 i = self._find_macro (name)
217 if i is not None:
218 del self.macros[i]
219
220 defn = (name, value)
221 self.macros.append (defn)
222
223
224 def undefine_macro (self, name):
225 """Undefine a preprocessor macro for all compilations driven by
226 this compiler object. If the same macro is defined by
227 'define_macro()' and undefined by 'undefine_macro()' the last call
228 takes precedence (including multiple redefinitions or
229 undefinitions). If the macro is redefined/undefined on a
230 per-compilation basis (ie. in the call to 'compile()'), then that
231 takes precedence.
232 """
233 # Delete from the list of macro definitions/undefinitions if
234 # already there (so that this one will take precedence).
235 i = self._find_macro (name)
236 if i is not None:
237 del self.macros[i]
238
239 undefn = (name,)
240 self.macros.append (undefn)
241
242
243 def add_include_dir (self, dir):
244 """Add 'dir' to the list of directories that will be searched for
245 header files. The compiler is instructed to search directories in
246 the order in which they are supplied by successive calls to
247 'add_include_dir()'.
248 """
249 self.include_dirs.append (dir)
250
251 def set_include_dirs (self, dirs):
252 """Set the list of directories that will be searched to 'dirs' (a
253 list of strings). Overrides any preceding calls to
254 'add_include_dir()'; subsequence calls to 'add_include_dir()' add
255 to the list passed to 'set_include_dirs()'. This does not affect
256 any list of standard include directories that the compiler may
257 search by default.
258 """
259 self.include_dirs = copy (dirs)
260
261
262 def add_library (self, libname):
263 """Add 'libname' to the list of libraries that will be included in
264 all links driven by this compiler object. Note that 'libname'
265 should *not* be the name of a file containing a library, but the
266 name of the library itself: the actual filename will be inferred by
267 the linker, the compiler, or the compiler class (depending on the
268 platform).
269
270 The linker will be instructed to link against libraries in the
271 order they were supplied to 'add_library()' and/or
272 'set_libraries()'. It is perfectly valid to duplicate library
273 names; the linker will be instructed to link against libraries as
274 many times as they are mentioned.
275 """
276 self.libraries.append (libname)
277
278 def set_libraries (self, libnames):
279 """Set the list of libraries to be included in all links driven by
280 this compiler object to 'libnames' (a list of strings). This does
281 not affect any standard system libraries that the linker may
282 include by default.
283 """
284 self.libraries = copy (libnames)
285
286
287 def add_library_dir (self, dir):
288 """Add 'dir' to the list of directories that will be searched for
289 libraries specified to 'add_library()' and 'set_libraries()'. The
290 linker will be instructed to search for libraries in the order they
291 are supplied to 'add_library_dir()' and/or 'set_library_dirs()'.
292 """
293 self.library_dirs.append (dir)
294
295 def set_library_dirs (self, dirs):
296 """Set the list of library search directories to 'dirs' (a list of
297 strings). This does not affect any standard library search path
298 that the linker may search by default.
299 """
300 self.library_dirs = copy (dirs)
301
302
303 def add_runtime_library_dir (self, dir):
304 """Add 'dir' to the list of directories that will be searched for
305 shared libraries at runtime.
306 """
307 self.runtime_library_dirs.append (dir)
308
309 def set_runtime_library_dirs (self, dirs):
310 """Set the list of directories to search for shared libraries at
311 runtime to 'dirs' (a list of strings). This does not affect any
312 standard search path that the runtime linker may search by
313 default.
314 """
315 self.runtime_library_dirs = copy (dirs)
316
317
318 def add_link_object (self, object):
319 """Add 'object' to the list of object files (or analogues, such as
320 explicitly named library files or the output of "resource
321 compilers") to be included in every link driven by this compiler
322 object.
323 """
324 self.objects.append (object)
325
326 def set_link_objects (self, objects):
327 """Set the list of object files (or analogues) to be included in
328 every link to 'objects'. This does not affect any standard object
329 files that the linker may include by default (such as system
330 libraries).
331 """
332 self.objects = copy (objects)
333
334
335 # -- Private utility methods --------------------------------------
336 # (here for the convenience of subclasses)
337
338 # Helper method to prep compiler in subclass compile() methods
339
340 def _setup_compile(self, outdir, macros, incdirs, sources, depends,
341 extra):
342 """Process arguments and decide which source files to compile.
343
344 Merges _fix_compile_args() and _prep_compile().
345 """
346 if outdir is None:
347 outdir = self.output_dir
348 elif type(outdir) is not StringType:
349 raise TypeError, "'output_dir' must be a string or None"
350
351 if macros is None:
352 macros = self.macros
353 elif type(macros) is ListType:
354 macros = macros + (self.macros or [])
355 else:
356 raise TypeError, "'macros' (if supplied) must be a list of tuples"
357
358 if incdirs is None:
359 incdirs = self.include_dirs
360 elif type(incdirs) in (ListType, TupleType):
361 incdirs = list(incdirs) + (self.include_dirs or [])
362 else:
363 raise TypeError, \
364 "'include_dirs' (if supplied) must be a list of strings"
365
366 if extra is None:
367 extra = []
368
369 # Get the list of expected output (object) files
370 objects = self.object_filenames(sources,
371 strip_dir=python_build,
372 output_dir=outdir)
373 assert len(objects) == len(sources)
374
375 # XXX should redo this code to eliminate skip_source entirely.
376 # XXX instead create build and issue skip messages inline
377
378 if self.force:
379 skip_source = {} # rebuild everything
380 for source in sources:
381 skip_source[source] = 0
382 elif depends is None:
383 # If depends is None, figure out which source files we
384 # have to recompile according to a simplistic check. We
385 # just compare the source and object file, no deep
386 # dependency checking involving header files.
387 skip_source = {} # rebuild everything
388 for source in sources: # no wait, rebuild nothing
389 skip_source[source] = 1
390
391 n_sources, n_objects = newer_pairwise(sources, objects)
392 for source in n_sources: # no really, only rebuild what's
393 skip_source[source] = 0 # out-of-date
394 else:
395 # If depends is a list of files, then do a different
396 # simplistic check. Assume that each object depends on
397 # its source and all files in the depends list.
398 skip_source = {}
399 # L contains all the depends plus a spot at the end for a
400 # particular source file
401 L = depends[:] + [None]
402 for i in range(len(objects)):
403 source = sources[i]
404 L[-1] = source
405 if newer_group(L, objects[i]):
406 skip_source[source] = 0
407 else:
408 skip_source[source] = 1
409
410 pp_opts = gen_preprocess_options(macros, incdirs)
411
412 build = {}
413 for i in range(len(sources)):
414 src = sources[i]
415 obj = objects[i]
416 ext = os.path.splitext(src)[1]
417 self.mkpath(os.path.dirname(obj))
418 if skip_source[src]:
419 log.debug("skipping %s (%s up-to-date)", src, obj)
420 else:
421 build[obj] = src, ext
422
423 return macros, objects, extra, pp_opts, build
424
425 def _get_cc_args(self, pp_opts, debug, before):
426 # works for unixccompiler, emxccompiler, cygwinccompiler
427 cc_args = pp_opts + ['-c']
428 if debug:
429 cc_args[:0] = ['-g']
430 if before:
431 cc_args[:0] = before
432 return cc_args
433
434 def _fix_compile_args (self, output_dir, macros, include_dirs):
435 """Typecheck and fix-up some of the arguments to the 'compile()'
436 method, and return fixed-up values. Specifically: if 'output_dir'
437 is None, replaces it with 'self.output_dir'; ensures that 'macros'
438 is a list, and augments it with 'self.macros'; ensures that
439 'include_dirs' is a list, and augments it with 'self.include_dirs'.
440 Guarantees that the returned values are of the correct type,
441 i.e. for 'output_dir' either string or None, and for 'macros' and
442 'include_dirs' either list or None.
443 """
444 if output_dir is None:
445 output_dir = self.output_dir
446 elif type (output_dir) is not StringType:
447 raise TypeError, "'output_dir' must be a string or None"
448
449 if macros is None:
450 macros = self.macros
451 elif type (macros) is ListType:
452 macros = macros + (self.macros or [])
453 else:
454 raise TypeError, "'macros' (if supplied) must be a list of tuples"
455
456 if include_dirs is None:
457 include_dirs = self.include_dirs
458 elif type (include_dirs) in (ListType, TupleType):
459 include_dirs = list (include_dirs) + (self.include_dirs or [])
460 else:
461 raise TypeError, \
462 "'include_dirs' (if supplied) must be a list of strings"
463
464 return output_dir, macros, include_dirs
465
466 # _fix_compile_args ()
467
468
469 def _prep_compile(self, sources, output_dir, depends=None):
470 """Decide which souce files must be recompiled.
471
472 Determine the list of object files corresponding to 'sources',
473 and figure out which ones really need to be recompiled.
474 Return a list of all object files and a dictionary telling
475 which source files can be skipped.
476 """
477 # Get the list of expected output (object) files
478 objects = self.object_filenames(sources, strip_dir=python_build,
479 output_dir=output_dir)
480 assert len(objects) == len(sources)
481
482 if self.force:
483 skip_source = {} # rebuild everything
484 for source in sources:
485 skip_source[source] = 0
486 elif depends is None:
487 # If depends is None, figure out which source files we
488 # have to recompile according to a simplistic check. We
489 # just compare the source and object file, no deep
490 # dependency checking involving header files.
491 skip_source = {} # rebuild everything
492 for source in sources: # no wait, rebuild nothing
493 skip_source[source] = 1
494
495 n_sources, n_objects = newer_pairwise(sources, objects)
496 for source in n_sources: # no really, only rebuild what's
497 skip_source[source] = 0 # out-of-date
498 else:
499 # If depends is a list of files, then do a different
500 # simplistic check. Assume that each object depends on
501 # its source and all files in the depends list.
502 skip_source = {}
503 # L contains all the depends plus a spot at the end for a
504 # particular source file
505 L = depends[:] + [None]
506 for i in range(len(objects)):
507 source = sources[i]
508 L[-1] = source
509 if newer_group(L, objects[i]):
510 skip_source[source] = 0
511 else:
512 skip_source[source] = 1
513
514 return objects, skip_source
515
516 # _prep_compile ()
517
518
519 def _fix_object_args (self, objects, output_dir):
520 """Typecheck and fix up some arguments supplied to various methods.
521 Specifically: ensure that 'objects' is a list; if output_dir is
522 None, replace with self.output_dir. Return fixed versions of
523 'objects' and 'output_dir'.
524 """
525 if type (objects) not in (ListType, TupleType):
526 raise TypeError, \
527 "'objects' must be a list or tuple of strings"
528 objects = list (objects)
529
530 if output_dir is None:
531 output_dir = self.output_dir
532 elif type (output_dir) is not StringType:
533 raise TypeError, "'output_dir' must be a string or None"
534
535 return (objects, output_dir)
536
537
538 def _fix_lib_args (self, libraries, library_dirs, runtime_library_dirs):
539 """Typecheck and fix up some of the arguments supplied to the
540 'link_*' methods. Specifically: ensure that all arguments are
541 lists, and augment them with their permanent versions
542 (eg. 'self.libraries' augments 'libraries'). Return a tuple with
543 fixed versions of all arguments.
544 """
545 if libraries is None:
546 libraries = self.libraries
547 elif type (libraries) in (ListType, TupleType):
548 libraries = list (libraries) + (self.libraries or [])
549 else:
550 raise TypeError, \
551 "'libraries' (if supplied) must be a list of strings"
552
553 if library_dirs is None:
554 library_dirs = self.library_dirs
555 elif type (library_dirs) in (ListType, TupleType):
556 library_dirs = list (library_dirs) + (self.library_dirs or [])
557 else:
558 raise TypeError, \
559 "'library_dirs' (if supplied) must be a list of strings"
560
561 if runtime_library_dirs is None:
562 runtime_library_dirs = self.runtime_library_dirs
563 elif type (runtime_library_dirs) in (ListType, TupleType):
564 runtime_library_dirs = (list (runtime_library_dirs) +
565 (self.runtime_library_dirs or []))
566 else:
567 raise TypeError, \
568 "'runtime_library_dirs' (if supplied) " + \
569 "must be a list of strings"
570
571 return (libraries, library_dirs, runtime_library_dirs)
572
573 # _fix_lib_args ()
574
575
576 def _need_link (self, objects, output_file):
577 """Return true if we need to relink the files listed in 'objects'
578 to recreate 'output_file'.
579 """
580 if self.force:
581 return 1
582 else:
583 if self.dry_run:
584 newer = newer_group (objects, output_file, missing='newer')
585 else:
586 newer = newer_group (objects, output_file)
587 return newer
588
589 # _need_link ()
590
591 def detect_language (self, sources):
592 """Detect the language of a given file, or list of files. Uses
593 language_map, and language_order to do the job.
594 """
595 if type(sources) is not ListType:
596 sources = [sources]
597 lang = None
598 index = len(self.language_order)
599 for source in sources:
600 base, ext = os.path.splitext(source)
601 extlang = self.language_map.get(ext)
602 try:
603 extindex = self.language_order.index(extlang)
604 if extindex < index:
605 lang = extlang
606 index = extindex
607 except ValueError:
608 pass
609 return lang
610
611 # detect_language ()
612
613 # -- Worker methods ------------------------------------------------
614 # (must be implemented by subclasses)
615
616 def preprocess (self,
617 source,
618 output_file=None,
619 macros=None,
620 include_dirs=None,
621 extra_preargs=None,
622 extra_postargs=None):
623 """Preprocess a single C/C++ source file, named in 'source'.
624 Output will be written to file named 'output_file', or stdout if
625 'output_file' not supplied. 'macros' is a list of macro
626 definitions as for 'compile()', which will augment the macros set
627 with 'define_macro()' and 'undefine_macro()'. 'include_dirs' is a
628 list of directory names that will be added to the default list.
629
630 Raises PreprocessError on failure.
631 """
632 pass
633
634 def compile(self, sources, output_dir=None, macros=None,
635 include_dirs=None, debug=0, extra_preargs=None,
636 extra_postargs=None, depends=None):
637 """Compile one or more source files.
638
639 'sources' must be a list of filenames, most likely C/C++
640 files, but in reality anything that can be handled by a
641 particular compiler and compiler class (eg. MSVCCompiler can
642 handle resource files in 'sources'). Return a list of object
643 filenames, one per source filename in 'sources'. Depending on
644 the implementation, not all source files will necessarily be
645 compiled, but all corresponding object filenames will be
646 returned.
647
648 If 'output_dir' is given, object files will be put under it, while
649 retaining their original path component. That is, "foo/bar.c"
650 normally compiles to "foo/bar.o" (for a Unix implementation); if
651 'output_dir' is "build", then it would compile to
652 "build/foo/bar.o".
653
654 'macros', if given, must be a list of macro definitions. A macro
655 definition is either a (name, value) 2-tuple or a (name,) 1-tuple.
656 The former defines a macro; if the value is None, the macro is
657 defined without an explicit value. The 1-tuple case undefines a
658 macro. Later definitions/redefinitions/ undefinitions take
659 precedence.
660
661 'include_dirs', if given, must be a list of strings, the
662 directories to add to the default include file search path for this
663 compilation only.
664
665 'debug' is a boolean; if true, the compiler will be instructed to
666 output debug symbols in (or alongside) the object file(s).
667
668 'extra_preargs' and 'extra_postargs' are implementation- dependent.
669 On platforms that have the notion of a command-line (e.g. Unix,
670 DOS/Windows), they are most likely lists of strings: extra
671 command-line arguments to prepand/append to the compiler command
672 line. On other platforms, consult the implementation class
673 documentation. In any event, they are intended as an escape hatch
674 for those occasions when the abstract compiler framework doesn't
675 cut the mustard.
676
677 'depends', if given, is a list of filenames that all targets
678 depend on. If a source file is older than any file in
679 depends, then the source file will be recompiled. This
680 supports dependency tracking, but only at a coarse
681 granularity.
682
683 Raises CompileError on failure.
684 """
685
686 # A concrete compiler class can either override this method
687 # entirely or implement _compile().
688
689 macros, objects, extra_postargs, pp_opts, build = \
690 self._setup_compile(output_dir, macros, include_dirs, sources,
691 depends, extra_postargs)
692 cc_args = self._get_cc_args(pp_opts, debug, extra_preargs)
693
694 for obj, (src, ext) in build.items():
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
e55c4dd1
RD
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
1e4a197e
RD
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)
e55c4dd1
RD
980 base = os.path.splitdrive(base)[1] # Chop off the drive
981 base = base[os.path.isabs(base):] # If abs, chop off leading /
1e4a197e
RD
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, 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 ('mac', 'mwerks'),
1065
1066 )
1067
1068def get_default_compiler(osname=None, platform=None):
1069
1070 """ Determine the default compiler to use for the given platform.
1071
1072 osname should be one of the standard Python OS names (i.e. the
1073 ones returned by os.name) and platform the common value
1074 returned by sys.platform for the platform in question.
1075
1076 The default values are os.name and sys.platform in case the
1077 parameters are not given.
1078
1079 """
1080 if osname is None:
1081 osname = os.name
1082 if platform is None:
1083 platform = sys.platform
1084 for pattern, compiler in _default_compilers:
1085 if re.match(pattern, platform) is not None or \
1086 re.match(pattern, osname) is not None:
1087 return compiler
1088 # Default to Unix compiler
1089 return 'unix'
1090
1091# Map compiler types to (module_name, class_name) pairs -- ie. where to
1092# find the code that implements an interface to this compiler. (The module
1093# is assumed to be in the 'distutils' package.)
1094compiler_class = { 'unix': ('unixccompiler', 'UnixCCompiler',
1095 "standard UNIX-style compiler"),
1096 'msvc': ('msvccompiler', 'MSVCCompiler',
1097 "Microsoft Visual C++"),
1098 'cygwin': ('cygwinccompiler', 'CygwinCCompiler',
1099 "Cygwin port of GNU C Compiler for Win32"),
1100 'mingw32': ('cygwinccompiler', 'Mingw32CCompiler',
1101 "Mingw32 port of GNU C Compiler for Win32"),
1102 'bcpp': ('bcppcompiler', 'BCPPCompiler',
1103 "Borland C++ Compiler"),
1104 'mwerks': ('mwerkscompiler', 'MWerksCompiler',
1105 "MetroWerks CodeWarrior"),
1106 'emx': ('emxccompiler', 'EMXCCompiler',
1107 "EMX port of GNU C Compiler for OS/2"),
1108 }
1109
1110def show_compilers():
1111 """Print list of available compilers (used by the "--help-compiler"
1112 options to "build", "build_ext", "build_clib").
1113 """
1114 # XXX this "knows" that the compiler option it's describing is
1115 # "--compiler", which just happens to be the case for the three
1116 # commands that use it.
1117 from distutils.fancy_getopt import FancyGetopt
1118 compilers = []
1119 for compiler in compiler_class.keys():
1120 compilers.append(("compiler="+compiler, None,
1121 compiler_class[compiler][2]))
1122 compilers.sort()
1123 pretty_printer = FancyGetopt(compilers)
1124 pretty_printer.print_help("List of available compilers:")
1125
1126
1127def new_compiler (plat=None,
1128 compiler=None,
1129 verbose=0,
1130 dry_run=0,
1131 force=0):
1132 """Generate an instance of some CCompiler subclass for the supplied
1133 platform/compiler combination. 'plat' defaults to 'os.name'
1134 (eg. 'posix', 'nt'), and 'compiler' defaults to the default compiler
1135 for that platform. Currently only 'posix' and 'nt' are supported, and
1136 the default compilers are "traditional Unix interface" (UnixCCompiler
1137 class) and Visual C++ (MSVCCompiler class). Note that it's perfectly
1138 possible to ask for a Unix compiler object under Windows, and a
1139 Microsoft compiler object under Unix -- if you supply a value for
1140 'compiler', 'plat' is ignored.
1141 """
1142 if plat is None:
1143 plat = os.name
1144
1145 try:
1146 if compiler is None:
1147 compiler = get_default_compiler(plat)
1148
1149 (module_name, class_name, long_description) = compiler_class[compiler]
1150 except KeyError:
1151 msg = "don't know how to compile C/C++ code on platform '%s'" % plat
1152 if compiler is not None:
1153 msg = msg + " with '%s' compiler" % compiler
1154 raise DistutilsPlatformError, msg
1155
1156 try:
1157 module_name = "distutils." + module_name
1158 __import__ (module_name)
1159 module = sys.modules[module_name]
1160 klass = vars(module)[class_name]
1161 except ImportError:
1162 raise DistutilsModuleError, \
1163 "can't compile C/C++ code: unable to load module '%s'" % \
1164 module_name
1165 except KeyError:
1166 raise DistutilsModuleError, \
1167 ("can't compile C/C++ code: unable to find class '%s' " +
1168 "in module '%s'") % (class_name, module_name)
1169
1170 # XXX The None is necessary to preserve backwards compatibility
1171 # with classes that expect verbose to be the first positional
1172 # argument.
1173 return klass (None, dry_run, force)
1174
1175
1176def gen_preprocess_options (macros, include_dirs):
1177 """Generate C pre-processor options (-D, -U, -I) as used by at least
1178 two types of compilers: the typical Unix compiler and Visual C++.
1179 'macros' is the usual thing, a list of 1- or 2-tuples, where (name,)
1180 means undefine (-U) macro 'name', and (name,value) means define (-D)
1181 macro 'name' to 'value'. 'include_dirs' is just a list of directory
1182 names to be added to the header file search path (-I). Returns a list
1183 of command-line options suitable for either Unix compilers or Visual
1184 C++.
1185 """
1186 # XXX it would be nice (mainly aesthetic, and so we don't generate
1187 # stupid-looking command lines) to go over 'macros' and eliminate
1188 # redundant definitions/undefinitions (ie. ensure that only the
1189 # latest mention of a particular macro winds up on the command
1190 # line). I don't think it's essential, though, since most (all?)
1191 # Unix C compilers only pay attention to the latest -D or -U
1192 # mention of a macro on their command line. Similar situation for
1193 # 'include_dirs'. I'm punting on both for now. Anyways, weeding out
1194 # redundancies like this should probably be the province of
1195 # CCompiler, since the data structures used are inherited from it
1196 # and therefore common to all CCompiler classes.
1197
1198 pp_opts = []
1199 for macro in macros:
1200
1201 if not (type (macro) is TupleType and
1202 1 <= len (macro) <= 2):
1203 raise TypeError, \
1204 ("bad macro definition '%s': " +
1205 "each element of 'macros' list must be a 1- or 2-tuple") % \
1206 macro
1207
1208 if len (macro) == 1: # undefine this macro
1209 pp_opts.append ("-U%s" % macro[0])
1210 elif len (macro) == 2:
1211 if macro[1] is None: # define with no explicit value
1212 pp_opts.append ("-D%s" % macro[0])
1213 else:
1214 # XXX *don't* need to be clever about quoting the
1215 # macro value here, because we're going to avoid the
1216 # shell at all costs when we spawn the command!
1217 pp_opts.append ("-D%s=%s" % macro)
1218
1219 for dir in include_dirs:
1220 pp_opts.append ("-I%s" % dir)
1221
1222 return pp_opts
1223
1224# gen_preprocess_options ()
1225
1226
1227def gen_lib_options (compiler, library_dirs, runtime_library_dirs, libraries):
1228 """Generate linker options for searching library directories and
1229 linking with specific libraries. 'libraries' and 'library_dirs' are,
1230 respectively, lists of library names (not filenames!) and search
1231 directories. Returns a list of command-line options suitable for use
1232 with some compiler (depending on the two format strings passed in).
1233 """
1234 lib_opts = []
1235
1236 for dir in library_dirs:
1237 lib_opts.append (compiler.library_dir_option (dir))
1238
1239 for dir in runtime_library_dirs:
1240 lib_opts.append (compiler.runtime_library_dir_option (dir))
1241
1242 # XXX it's important that we *not* remove redundant library mentions!
1243 # sometimes you really do have to say "-lfoo -lbar -lfoo" in order to
1244 # resolve all symbols. I just hope we never have to say "-lfoo obj.o
1245 # -lbar" to get things to work -- that's certainly a possibility, but a
1246 # pretty nasty way to arrange your C code.
1247
1248 for lib in libraries:
1249 (lib_dir, lib_name) = os.path.split (lib)
1250 if lib_dir:
1251 lib_file = compiler.find_library_file ([lib_dir], lib_name)
1252 if lib_file:
1253 lib_opts.append (lib_file)
1254 else:
1255 compiler.warn ("no library file corresponding to "
1256 "'%s' found (skipping)" % lib)
1257 else:
1258 lib_opts.append (compiler.library_option (lib))
1259
1260 return lib_opts
1261
1262# gen_lib_options ()