3
Contains CCompiler, an abstract base class that defines the interface
4
for the Distutils compiler abstraction model."""
6
__revision__ = "$Id: ccompiler.py 68931 2009-01-25 18:27:45Z tarek.ziade $"
10
from distutils.errors import *
11
from distutils.spawn import spawn
12
from distutils.file_util import move_file
13
from distutils.dir_util import mkpath
14
from distutils.dep_util import newer_pairwise, newer_group
15
from distutils.util import split_quoted, execute
16
from distutils import log
19
"""Abstract base class to define the interface that must be implemented
20
by real compiler classes. Also has some utility methods used by
21
several compiler classes.
23
The basic idea behind a compiler abstraction class is that each
24
instance can be used for all the compile/link steps in building a
25
single project. Thus, attributes common to all of those compile and
26
link steps -- include directories, macros to define, libraries to link
27
against, etc. -- are attributes of the compiler instance. To allow for
28
variability in how individual files are treated, most of those
29
attributes may be varied on a per-compilation or per-link basis.
32
# 'compiler_type' is a class attribute that identifies this class. It
33
# keeps code that wants to know what kind of compiler it's dealing with
34
# from having to import all possible compiler classes just to do an
35
# 'isinstance'. In concrete CCompiler subclasses, 'compiler_type'
36
# should really, really be one of the keys of the 'compiler_class'
37
# dictionary (see below -- used by the 'new_compiler()' factory
38
# function) -- authors of new compiler interface classes are
39
# responsible for updating 'compiler_class'!
42
# XXX things not handled by this compiler abstraction model:
43
# * client can't provide additional options for a compiler,
44
# e.g. warning, optimization, debugging flags. Perhaps this
45
# should be the domain of concrete compiler abstraction classes
46
# (UnixCCompiler, MSVCCompiler, etc.) -- or perhaps the base
47
# class should have methods for the common ones.
48
# * can't completely override the include or library searchg
49
# path, ie. no "cc -I -Idir1 -Idir2" or "cc -L -Ldir1 -Ldir2".
50
# I'm not sure how widely supported this is even by Unix
51
# compilers, much less on other platforms. And I'm even less
52
# sure how useful it is; maybe for cross-compiling, but
53
# support for that is a ways off. (And anyways, cross
54
# compilers probably have a dedicated binary with the
55
# right paths compiled in. I hope.)
56
# * can't do really freaky things with the library list/library
57
# dirs, e.g. "-Ldir1 -lfoo -Ldir2 -lfoo" to link against
58
# different versions of libfoo.a in different locations. I
59
# think this is useless without the ability to null out the
60
# library search path anyways.
63
# Subclasses that rely on the standard filename generation methods
64
# implemented below should override these; see the comment near
65
# those methods ('object_filenames()' et. al.) for details:
66
src_extensions = None # list of strings
67
obj_extension = None # string
68
static_lib_extension = None
69
shared_lib_extension = None # string
70
static_lib_format = None # format string
71
shared_lib_format = None # prob. same as static_lib_format
72
exe_extension = None # string
74
# Default language settings. language_map is used to detect a source
75
# file or Extension target language, checking source filenames.
76
# language_order is used to detect the language precedence, when deciding
77
# what language to use when mixing source types. For example, if some
78
# extension has two files with ".c" extension, and one with ".cpp", it
79
# is still linked as c++.
80
language_map = {".c" : "c",
86
language_order = ["c++", "objc", "c"]
88
def __init__(self, verbose=0, dry_run=0, force=0):
89
self.dry_run = dry_run
91
self.verbose = verbose
93
# 'output_dir': a common output directory for object, library,
94
# shared object, and shared library files
95
self.output_dir = None
97
# 'macros': a list of macro definitions (or undefinitions). A
98
# macro definition is a 2-tuple (name, value), where the value is
99
# either a string or None (no explicit value). A macro
100
# undefinition is a 1-tuple (name,).
103
# 'include_dirs': a list of directories to search for include files
104
self.include_dirs = []
106
# 'libraries': a list of libraries to include in any link
107
# (library names, not filenames: eg. "foo" not "libfoo.a")
110
# 'library_dirs': a list of directories to search for libraries
111
self.library_dirs = []
113
# 'runtime_library_dirs': a list of directories to search for
114
# shared libraries/objects at runtime
115
self.runtime_library_dirs = []
117
# 'objects': a list of object files (or similar, such as explicitly
118
# named library files) to include on any link
121
for key in self.executables.keys():
122
self.set_executable(key, self.executables[key])
124
def set_executables(self, **kwargs):
125
"""Define the executables (and options for them) that will be run
126
to perform the various stages of compilation. The exact set of
127
executables that may be specified here depends on the compiler
128
class (via the 'executables' class attribute), but most will have:
129
compiler the C/C++ compiler
130
linker_so linker used to create shared objects and libraries
131
linker_exe linker used to create binary executables
132
archiver static library creator
134
On platforms with a command-line (Unix, DOS/Windows), each of these
135
is a string that will be split into executable name and (optional)
136
list of arguments. (Splitting the string is done similarly to how
137
Unix shells operate: words are delimited by spaces, but quotes and
138
backslashes can override this. See
139
'distutils.util.split_quoted()'.)
142
# Note that some CCompiler implementation classes will define class
143
# attributes 'cpp', 'cc', etc. with hard-coded executable names;
144
# this is appropriate when a compiler class is for exactly one
145
# compiler/OS combination (eg. MSVCCompiler). Other compiler
146
# classes (UnixCCompiler, in particular) are driven by information
147
# discovered at run-time, since there are many different ways to do
148
# basically the same things with Unix C compilers.
151
if key not in self.executables:
152
raise ValueError("unknown executable '%s' for class %s" %
153
(key, self.__class__.__name__))
154
self.set_executable(key, kwargs[key])
156
def set_executable(self, key, value):
157
if isinstance(value, str):
158
setattr(self, key, split_quoted(value))
160
setattr(self, key, value)
162
def _find_macro(self, name):
164
for defn in self.macros:
170
def _check_macro_definitions(self, definitions):
171
"""Ensures that every element of 'definitions' is a valid macro
172
definition, ie. either (name,value) 2-tuple or a (name,) tuple. Do
173
nothing if all definitions are OK, raise TypeError otherwise.
175
for defn in definitions:
176
if not (isinstance(defn, tuple) and
177
(len(defn) in (1, 2) and
178
(isinstance (defn[1], str) or defn[1] is None)) and
179
isinstance (defn[0], str)):
180
raise TypeError(("invalid macro definition '%s': " % defn) + \
181
"must be tuple (string,), (string, string), or " + \
185
# -- Bookkeeping methods -------------------------------------------
187
def define_macro(self, name, value=None):
188
"""Define a preprocessor macro for all compilations driven by this
189
compiler object. The optional parameter 'value' should be a
190
string; if it is not supplied, then the macro will be defined
191
without an explicit value and the exact outcome depends on the
192
compiler used (XXX true? does ANSI say anything about this?)
194
# Delete from the list of macro definitions/undefinitions if
195
# already there (so that this one will take precedence).
196
i = self._find_macro (name)
200
self.macros.append((name, value))
202
def undefine_macro(self, name):
203
"""Undefine a preprocessor macro for all compilations driven by
204
this compiler object. If the same macro is defined by
205
'define_macro()' and undefined by 'undefine_macro()' the last call
206
takes precedence (including multiple redefinitions or
207
undefinitions). If the macro is redefined/undefined on a
208
per-compilation basis (ie. in the call to 'compile()'), then that
211
# Delete from the list of macro definitions/undefinitions if
212
# already there (so that this one will take precedence).
213
i = self._find_macro (name)
218
self.macros.append(undefn)
220
def add_include_dir(self, dir):
221
"""Add 'dir' to the list of directories that will be searched for
222
header files. The compiler is instructed to search directories in
223
the order in which they are supplied by successive calls to
226
self.include_dirs.append(dir)
228
def set_include_dirs(self, dirs):
229
"""Set the list of directories that will be searched to 'dirs' (a
230
list of strings). Overrides any preceding calls to
231
'add_include_dir()'; subsequence calls to 'add_include_dir()' add
232
to the list passed to 'set_include_dirs()'. This does not affect
233
any list of standard include directories that the compiler may
236
self.include_dirs = copy(dirs)
238
def add_library(self, libname):
239
"""Add 'libname' to the list of libraries that will be included in
240
all links driven by this compiler object. Note that 'libname'
241
should *not* be the name of a file containing a library, but the
242
name of the library itself: the actual filename will be inferred by
243
the linker, the compiler, or the compiler class (depending on the
246
The linker will be instructed to link against libraries in the
247
order they were supplied to 'add_library()' and/or
248
'set_libraries()'. It is perfectly valid to duplicate library
249
names; the linker will be instructed to link against libraries as
250
many times as they are mentioned.
252
self.libraries.append(libname)
254
def set_libraries(self, libnames):
255
"""Set the list of libraries to be included in all links driven by
256
this compiler object to 'libnames' (a list of strings). This does
257
not affect any standard system libraries that the linker may
260
self.libraries = copy(libnames)
262
def add_library_dir(self, dir):
263
"""Add 'dir' to the list of directories that will be searched for
264
libraries specified to 'add_library()' and 'set_libraries()'. The
265
linker will be instructed to search for libraries in the order they
266
are supplied to 'add_library_dir()' and/or 'set_library_dirs()'.
268
self.library_dirs.append(dir)
270
def set_library_dirs(self, dirs):
271
"""Set the list of library search directories to 'dirs' (a list of
272
strings). This does not affect any standard library search path
273
that the linker may search by default.
275
self.library_dirs = copy(dirs)
277
def add_runtime_library_dir(self, dir):
278
"""Add 'dir' to the list of directories that will be searched for
279
shared libraries at runtime.
281
self.runtime_library_dirs.append(dir)
283
def set_runtime_library_dirs(self, dirs):
284
"""Set the list of directories to search for shared libraries at
285
runtime to 'dirs' (a list of strings). This does not affect any
286
standard search path that the runtime linker may search by
289
self.runtime_library_dirs = copy(dirs)
291
def add_link_object(self, object):
292
"""Add 'object' to the list of object files (or analogues, such as
293
explicitly named library files or the output of "resource
294
compilers") to be included in every link driven by this compiler
297
self.objects.append(object)
299
def set_link_objects(self, objects):
300
"""Set the list of object files (or analogues) to be included in
301
every link to 'objects'. This does not affect any standard object
302
files that the linker may include by default (such as system
305
self.objects = copy(objects)
308
# -- Private utility methods --------------------------------------
309
# (here for the convenience of subclasses)
311
# Helper method to prep compiler in subclass compile() methods
313
def _setup_compile(self, outdir, macros, incdirs, sources, depends,
315
"""Process arguments and decide which source files to compile.
317
Merges _fix_compile_args() and _prep_compile().
320
outdir = self.output_dir
321
elif not isinstance(outdir, str):
322
raise TypeError("'output_dir' must be a string or None")
326
elif isinstance(macros, list):
327
macros = macros + (self.macros or [])
329
raise TypeError("'macros' (if supplied) must be a list of tuples")
332
incdirs = self.include_dirs
333
elif isinstance(incdirs, (list, tuple)):
334
incdirs = list(incdirs) + (self.include_dirs or [])
337
"'include_dirs' (if supplied) must be a list of strings")
342
# Get the list of expected output (object) files
343
objects = self.object_filenames(sources, strip_dir=0,
345
assert len(objects) == len(sources)
347
# XXX should redo this code to eliminate skip_source entirely.
348
# XXX instead create build and issue skip messages inline
351
skip_source = {} # rebuild everything
352
for source in sources:
353
skip_source[source] = 0
354
elif depends is None:
355
# If depends is None, figure out which source files we
356
# have to recompile according to a simplistic check. We
357
# just compare the source and object file, no deep
358
# dependency checking involving header files.
359
skip_source = {} # rebuild everything
360
for source in sources: # no wait, rebuild nothing
361
skip_source[source] = 1
363
n_sources, n_objects = newer_pairwise(sources, objects)
364
for source in n_sources: # no really, only rebuild what's
365
skip_source[source] = 0 # out-of-date
367
# If depends is a list of files, then do a different
368
# simplistic check. Assume that each object depends on
369
# its source and all files in the depends list.
371
# L contains all the depends plus a spot at the end for a
372
# particular source file
373
L = depends[:] + [None]
374
for i in range(len(objects)):
377
if newer_group(L, objects[i]):
378
skip_source[source] = 0
380
skip_source[source] = 1
382
pp_opts = gen_preprocess_options(macros, incdirs)
385
for i in range(len(sources)):
388
ext = os.path.splitext(src)[1]
389
self.mkpath(os.path.dirname(obj))
391
log.debug("skipping %s (%s up-to-date)", src, obj)
393
build[obj] = src, ext
395
return macros, objects, extra, pp_opts, build
397
def _get_cc_args(self, pp_opts, debug, before):
398
# works for unixccompiler, emxccompiler, cygwinccompiler
399
cc_args = pp_opts + ['-c']
406
def _fix_compile_args(self, output_dir, macros, include_dirs):
407
"""Typecheck and fix-up some of the arguments to the 'compile()'
408
method, and return fixed-up values. Specifically: if 'output_dir'
409
is None, replaces it with 'self.output_dir'; ensures that 'macros'
410
is a list, and augments it with 'self.macros'; ensures that
411
'include_dirs' is a list, and augments it with 'self.include_dirs'.
412
Guarantees that the returned values are of the correct type,
413
i.e. for 'output_dir' either string or None, and for 'macros' and
414
'include_dirs' either list or None.
416
if output_dir is None:
417
output_dir = self.output_dir
418
elif not isinstance(output_dir, str):
419
raise TypeError("'output_dir' must be a string or None")
423
elif isinstance(macros, list):
424
macros = macros + (self.macros or [])
426
raise TypeError("'macros' (if supplied) must be a list of tuples")
428
if include_dirs is None:
429
include_dirs = self.include_dirs
430
elif isinstance(include_dirs, (list, tuple)):
431
include_dirs = list(include_dirs) + (self.include_dirs or [])
434
"'include_dirs' (if supplied) must be a list of strings")
436
return output_dir, macros, include_dirs
438
def _prep_compile(self, sources, output_dir, depends=None):
439
"""Decide which souce files must be recompiled.
441
Determine the list of object files corresponding to 'sources',
442
and figure out which ones really need to be recompiled.
443
Return a list of all object files and a dictionary telling
444
which source files can be skipped.
446
# Get the list of expected output (object) files
447
objects = self.object_filenames(sources, output_dir=output_dir)
448
assert len(objects) == len(sources)
451
skip_source = {} # rebuild everything
452
for source in sources:
453
skip_source[source] = 0
454
elif depends is None:
455
# If depends is None, figure out which source files we
456
# have to recompile according to a simplistic check. We
457
# just compare the source and object file, no deep
458
# dependency checking involving header files.
459
skip_source = {} # rebuild everything
460
for source in sources: # no wait, rebuild nothing
461
skip_source[source] = 1
463
n_sources, n_objects = newer_pairwise(sources, objects)
464
for source in n_sources: # no really, only rebuild what's
465
skip_source[source] = 0 # out-of-date
467
# If depends is a list of files, then do a different
468
# simplistic check. Assume that each object depends on
469
# its source and all files in the depends list.
471
# L contains all the depends plus a spot at the end for a
472
# particular source file
473
L = depends[:] + [None]
474
for i in range(len(objects)):
477
if newer_group(L, objects[i]):
478
skip_source[source] = 0
480
skip_source[source] = 1
482
return objects, skip_source
485
def _fix_object_args(self, objects, output_dir):
486
"""Typecheck and fix up some arguments supplied to various methods.
487
Specifically: ensure that 'objects' is a list; if output_dir is
488
None, replace with self.output_dir. Return fixed versions of
489
'objects' and 'output_dir'.
491
if not isinstance(objects, (list, tuple)):
492
raise TypeError("'objects' must be a list or tuple of strings")
493
objects = list(objects)
495
if output_dir is None:
496
output_dir = self.output_dir
497
elif not isinstance(output_dir, str):
498
raise TypeError("'output_dir' must be a string or None")
500
return (objects, output_dir)
502
def _fix_lib_args(self, libraries, library_dirs, runtime_library_dirs):
503
"""Typecheck and fix up some of the arguments supplied to the
504
'link_*' methods. Specifically: ensure that all arguments are
505
lists, and augment them with their permanent versions
506
(eg. 'self.libraries' augments 'libraries'). Return a tuple with
507
fixed versions of all arguments.
509
if libraries is None:
510
libraries = self.libraries
511
elif isinstance(libraries, (list, tuple)):
512
libraries = list (libraries) + (self.libraries or [])
515
"'libraries' (if supplied) must be a list of strings")
517
if library_dirs is None:
518
library_dirs = self.library_dirs
519
elif isinstance(library_dirs, (list, tuple)):
520
library_dirs = list (library_dirs) + (self.library_dirs or [])
523
"'library_dirs' (if supplied) must be a list of strings")
525
if runtime_library_dirs is None:
526
runtime_library_dirs = self.runtime_library_dirs
527
elif isinstance(runtime_library_dirs, (list, tuple)):
528
runtime_library_dirs = (list(runtime_library_dirs) +
529
(self.runtime_library_dirs or []))
531
raise TypeError("'runtime_library_dirs' (if supplied) "
532
"must be a list of strings")
534
return (libraries, library_dirs, runtime_library_dirs)
536
def _need_link(self, objects, output_file):
537
"""Return true if we need to relink the files listed in 'objects'
538
to recreate 'output_file'.
544
newer = newer_group (objects, output_file, missing='newer')
546
newer = newer_group (objects, output_file)
549
def detect_language(self, sources):
550
"""Detect the language of a given file, or list of files. Uses
551
language_map, and language_order to do the job.
553
if not isinstance(sources, list):
556
index = len(self.language_order)
557
for source in sources:
558
base, ext = os.path.splitext(source)
559
extlang = self.language_map.get(ext)
561
extindex = self.language_order.index(extlang)
570
# -- Worker methods ------------------------------------------------
571
# (must be implemented by subclasses)
573
def preprocess(self, source, output_file=None, macros=None,
574
include_dirs=None, extra_preargs=None, extra_postargs=None):
575
"""Preprocess a single C/C++ source file, named in 'source'.
576
Output will be written to file named 'output_file', or stdout if
577
'output_file' not supplied. 'macros' is a list of macro
578
definitions as for 'compile()', which will augment the macros set
579
with 'define_macro()' and 'undefine_macro()'. 'include_dirs' is a
580
list of directory names that will be added to the default list.
582
Raises PreprocessError on failure.
586
def compile(self, sources, output_dir=None, macros=None,
587
include_dirs=None, debug=0, extra_preargs=None,
588
extra_postargs=None, depends=None):
589
"""Compile one or more source files.
591
'sources' must be a list of filenames, most likely C/C++
592
files, but in reality anything that can be handled by a
593
particular compiler and compiler class (eg. MSVCCompiler can
594
handle resource files in 'sources'). Return a list of object
595
filenames, one per source filename in 'sources'. Depending on
596
the implementation, not all source files will necessarily be
597
compiled, but all corresponding object filenames will be
600
If 'output_dir' is given, object files will be put under it, while
601
retaining their original path component. That is, "foo/bar.c"
602
normally compiles to "foo/bar.o" (for a Unix implementation); if
603
'output_dir' is "build", then it would compile to
606
'macros', if given, must be a list of macro definitions. A macro
607
definition is either a (name, value) 2-tuple or a (name,) 1-tuple.
608
The former defines a macro; if the value is None, the macro is
609
defined without an explicit value. The 1-tuple case undefines a
610
macro. Later definitions/redefinitions/ undefinitions take
613
'include_dirs', if given, must be a list of strings, the
614
directories to add to the default include file search path for this
617
'debug' is a boolean; if true, the compiler will be instructed to
618
output debug symbols in (or alongside) the object file(s).
620
'extra_preargs' and 'extra_postargs' are implementation- dependent.
621
On platforms that have the notion of a command-line (e.g. Unix,
622
DOS/Windows), they are most likely lists of strings: extra
623
command-line arguments to prepand/append to the compiler command
624
line. On other platforms, consult the implementation class
625
documentation. In any event, they are intended as an escape hatch
626
for those occasions when the abstract compiler framework doesn't
629
'depends', if given, is a list of filenames that all targets
630
depend on. If a source file is older than any file in
631
depends, then the source file will be recompiled. This
632
supports dependency tracking, but only at a coarse
635
Raises CompileError on failure.
637
# A concrete compiler class can either override this method
638
# entirely or implement _compile().
639
macros, objects, extra_postargs, pp_opts, build = \
640
self._setup_compile(output_dir, macros, include_dirs, sources,
641
depends, extra_postargs)
642
cc_args = self._get_cc_args(pp_opts, debug, extra_preargs)
646
src, ext = build[obj]
649
self._compile(obj, src, ext, cc_args, extra_postargs, pp_opts)
651
# Return *all* object filenames, not just the ones we just built.
654
def _compile(self, obj, src, ext, cc_args, extra_postargs, pp_opts):
655
"""Compile 'src' to product 'obj'."""
656
# A concrete compiler class that does not override compile()
657
# should implement _compile().
660
def create_static_lib(self, objects, output_libname, output_dir=None,
661
debug=0, target_lang=None):
662
"""Link a bunch of stuff together to create a static library file.
663
The "bunch of stuff" consists of the list of object files supplied
664
as 'objects', the extra object files supplied to
665
'add_link_object()' and/or 'set_link_objects()', the libraries
666
supplied to 'add_library()' and/or 'set_libraries()', and the
667
libraries supplied as 'libraries' (if any).
669
'output_libname' should be a library name, not a filename; the
670
filename will be inferred from the library name. 'output_dir' is
671
the directory where the library file will be put.
673
'debug' is a boolean; if true, debugging information will be
674
included in the library (note that on most platforms, it is the
675
compile step where this matters: the 'debug' flag is included here
676
just for consistency).
678
'target_lang' is the target language for which the given objects
679
are being compiled. This allows specific linkage time treatment of
682
Raises LibError on failure.
687
# values for target_desc parameter in link()
688
SHARED_OBJECT = "shared_object"
689
SHARED_LIBRARY = "shared_library"
690
EXECUTABLE = "executable"
699
runtime_library_dirs=None,
706
"""Link a bunch of stuff together to create an executable or
709
The "bunch of stuff" consists of the list of object files supplied
710
as 'objects'. 'output_filename' should be a filename. If
711
'output_dir' is supplied, 'output_filename' is relative to it
712
(i.e. 'output_filename' can provide directory components if
715
'libraries' is a list of libraries to link against. These are
716
library names, not filenames, since they're translated into
717
filenames in a platform-specific way (eg. "foo" becomes "libfoo.a"
718
on Unix and "foo.lib" on DOS/Windows). However, they can include a
719
directory component, which means the linker will look in that
720
specific directory rather than searching all the normal locations.
722
'library_dirs', if supplied, should be a list of directories to
723
search for libraries that were specified as bare library names
724
(ie. no directory component). These are on top of the system
725
default and those supplied to 'add_library_dir()' and/or
726
'set_library_dirs()'. 'runtime_library_dirs' is a list of
727
directories that will be embedded into the shared library and used
728
to search for other shared libraries that *it* depends on at
729
run-time. (This may only be relevant on Unix.)
731
'export_symbols' is a list of symbols that the shared library will
732
export. (This appears to be relevant only on Windows.)
734
'debug' is as for 'compile()' and 'create_static_lib()', with the
735
slight distinction that it actually matters on most platforms (as
736
opposed to 'create_static_lib()', which includes a 'debug' flag
737
mostly for form's sake).
739
'extra_preargs' and 'extra_postargs' are as for 'compile()' (except
740
of course that they supply command-line arguments for the
741
particular linker being used).
743
'target_lang' is the target language for which the given objects
744
are being compiled. This allows specific linkage time treatment of
747
Raises LinkError on failure.
749
raise NotImplementedError
752
# Old 'link_*()' methods, rewritten to use the new 'link()' method.
754
def link_shared_lib(self,
760
runtime_library_dirs=None,
767
self.link(CCompiler.SHARED_LIBRARY, objects,
768
self.library_filename(output_libname, lib_type='shared'),
770
libraries, library_dirs, runtime_library_dirs,
771
export_symbols, debug,
772
extra_preargs, extra_postargs, build_temp, target_lang)
775
def link_shared_object(self,
781
runtime_library_dirs=None,
788
self.link(CCompiler.SHARED_OBJECT, objects,
789
output_filename, output_dir,
790
libraries, library_dirs, runtime_library_dirs,
791
export_symbols, debug,
792
extra_preargs, extra_postargs, build_temp, target_lang)
795
def link_executable(self,
801
runtime_library_dirs=None,
806
self.link(CCompiler.EXECUTABLE, objects,
807
self.executable_filename(output_progname), output_dir,
808
libraries, library_dirs, runtime_library_dirs, None,
809
debug, extra_preargs, extra_postargs, None, target_lang)
812
# -- Miscellaneous methods -----------------------------------------
813
# These are all used by the 'gen_lib_options() function; there is
814
# no appropriate default implementation so subclasses should
815
# implement all of these.
817
def library_dir_option(self, dir):
818
"""Return the compiler option to add 'dir' to the list of
819
directories searched for libraries.
821
raise NotImplementedError
823
def runtime_library_dir_option(self, dir):
824
"""Return the compiler option to add 'dir' to the list of
825
directories searched for runtime libraries.
827
raise NotImplementedError
829
def library_option(self, lib):
830
"""Return the compiler option to add 'dir' to the list of libraries
831
linked into the shared library or executable.
833
raise NotImplementedError
835
def has_function(self, funcname, includes=None, include_dirs=None,
836
libraries=None, library_dirs=None):
837
"""Return a boolean indicating whether funcname is supported on
838
the current platform. The optional arguments can be used to
839
augment the compilation environment.
841
# this can't be included at module scope because it tries to
842
# import math which might not be available at that point - maybe
843
# the necessary logic should just be inlined?
847
if include_dirs is None:
849
if libraries is None:
851
if library_dirs is None:
853
fd, fname = tempfile.mkstemp(".c", funcname, text=True)
854
f = os.fdopen(fd, "w")
855
for incl in includes:
856
f.write("""#include "%s"\n""" % incl)
858
main (int argc, char **argv) {
864
objects = self.compile([fname], include_dirs=include_dirs)
869
self.link_executable(objects, "a.out",
871
library_dirs=library_dirs)
872
except (LinkError, TypeError):
876
def find_library_file (self, dirs, lib, debug=0):
877
"""Search the specified list of directories for a static or shared
878
library file 'lib' and return the full path to that file. If
879
'debug' true, look for a debugging version (if that makes sense on
880
the current platform). Return None if 'lib' wasn't found in any of
881
the specified directories.
883
raise NotImplementedError
885
# -- Filename generation methods -----------------------------------
887
# The default implementation of the filename generating methods are
888
# prejudiced towards the Unix/DOS/Windows view of the world:
889
# * object files are named by replacing the source file extension
890
# (eg. .c/.cpp -> .o/.obj)
891
# * library files (shared or static) are named by plugging the
892
# library name and extension into a format string, eg.
893
# "lib%s.%s" % (lib_name, ".a") for Unix static libraries
894
# * executables are named by appending an extension (possibly
895
# empty) to the program name: eg. progname + ".exe" for
898
# To reduce redundant code, these methods expect to find
899
# several attributes in the current object (presumably defined
900
# as class attributes):
902
# list of C/C++ source file extensions, eg. ['.c', '.cpp']
904
# object file extension, eg. '.o' or '.obj'
905
# * static_lib_extension -
906
# extension for static library files, eg. '.a' or '.lib'
907
# * shared_lib_extension -
908
# extension for shared library/object files, eg. '.so', '.dll'
909
# * static_lib_format -
910
# format string for generating static library filenames,
911
# eg. 'lib%s.%s' or '%s.%s'
912
# * shared_lib_format
913
# format string for generating shared library filenames
914
# (probably same as static_lib_format, since the extension
915
# is one of the intended parameters to the format string)
917
# extension for executable files, eg. '' or '.exe'
919
def object_filenames(self, source_filenames, strip_dir=0, output_dir=''):
920
if output_dir is None:
923
for src_name in source_filenames:
924
base, ext = os.path.splitext(src_name)
925
base = os.path.splitdrive(base)[1] # Chop off the drive
926
base = base[os.path.isabs(base):] # If abs, chop off leading /
927
if ext not in self.src_extensions:
928
raise UnknownFileError(
929
"unknown file type '%s' (from '%s')" % (ext, src_name))
931
base = os.path.basename(base)
932
obj_names.append(os.path.join(output_dir,
933
base + self.obj_extension))
936
def shared_object_filename(self, basename, strip_dir=0, output_dir=''):
937
assert output_dir is not None
939
basename = os.path.basename(basename)
940
return os.path.join(output_dir, basename + self.shared_lib_extension)
942
def executable_filename(self, basename, strip_dir=0, output_dir=''):
943
assert output_dir is not None
945
basename = os.path.basename(basename)
946
return os.path.join(output_dir, basename + (self.exe_extension or ''))
948
def library_filename(self, libname, lib_type='static', # or 'shared'
949
strip_dir=0, output_dir=''):
950
assert output_dir is not None
951
if lib_type not in ("static", "shared", "dylib"):
953
"'lib_type' must be \"static\", \"shared\" or \"dylib\"")
954
fmt = getattr(self, lib_type + "_lib_format")
955
ext = getattr(self, lib_type + "_lib_extension")
957
dir, base = os.path.split(libname)
958
filename = fmt % (base, ext)
962
return os.path.join(output_dir, dir, filename)
965
# -- Utility methods -----------------------------------------------
967
def announce(self, msg, level=1):
970
def debug_print(self, msg):
971
from distutils.debug import DEBUG
976
sys.stderr.write("warning: %s\n" % msg)
978
def execute(self, func, args, msg=None, level=1):
979
execute(func, args, msg, self.dry_run)
981
def spawn(self, cmd):
982
spawn(cmd, dry_run=self.dry_run)
984
def move_file(self, src, dst):
985
return move_file(src, dst, dry_run=self.dry_run)
987
def mkpath (self, name, mode=0o777):
988
mkpath(name, mode, dry_run=self.dry_run)
991
# Map a sys.platform/os.name ('posix', 'nt') to the default compiler
992
# type for that platform. Keys are interpreted as re match
993
# patterns. Order is important; platform mappings are preferred over
995
_default_compilers = (
997
# Platform string mappings
999
# on a cygwin built python we can use gcc like an ordinary UNIXish
1001
('cygwin.*', 'unix'),
1010
def get_default_compiler(osname=None, platform=None):
1011
"""Determine the default compiler to use for the given platform.
1013
osname should be one of the standard Python OS names (i.e. the
1014
ones returned by os.name) and platform the common value
1015
returned by sys.platform for the platform in question.
1017
The default values are os.name and sys.platform in case the
1018
parameters are not given.
1022
if platform is None:
1023
platform = sys.platform
1024
for pattern, compiler in _default_compilers:
1025
if re.match(pattern, platform) is not None or \
1026
re.match(pattern, osname) is not None:
1028
# Default to Unix compiler
1031
# Map compiler types to (module_name, class_name) pairs -- ie. where to
1032
# find the code that implements an interface to this compiler. (The module
1033
# is assumed to be in the 'distutils' package.)
1034
compiler_class = { 'unix': ('unixccompiler', 'UnixCCompiler',
1035
"standard UNIX-style compiler"),
1036
'msvc': ('msvccompiler', 'MSVCCompiler',
1037
"Microsoft Visual C++"),
1038
'cygwin': ('cygwinccompiler', 'CygwinCCompiler',
1039
"Cygwin port of GNU C Compiler for Win32"),
1040
'mingw32': ('cygwinccompiler', 'Mingw32CCompiler',
1041
"Mingw32 port of GNU C Compiler for Win32"),
1042
'bcpp': ('bcppcompiler', 'BCPPCompiler',
1043
"Borland C++ Compiler"),
1044
'emx': ('emxccompiler', 'EMXCCompiler',
1045
"EMX port of GNU C Compiler for OS/2"),
1048
def show_compilers():
1049
"""Print list of available compilers (used by the "--help-compiler"
1050
options to "build", "build_ext", "build_clib").
1052
# XXX this "knows" that the compiler option it's describing is
1053
# "--compiler", which just happens to be the case for the three
1054
# commands that use it.
1055
from distutils.fancy_getopt import FancyGetopt
1057
for compiler in compiler_class.keys():
1058
compilers.append(("compiler="+compiler, None,
1059
compiler_class[compiler][2]))
1061
pretty_printer = FancyGetopt(compilers)
1062
pretty_printer.print_help("List of available compilers:")
1065
def new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0):
1066
"""Generate an instance of some CCompiler subclass for the supplied
1067
platform/compiler combination. 'plat' defaults to 'os.name'
1068
(eg. 'posix', 'nt'), and 'compiler' defaults to the default compiler
1069
for that platform. Currently only 'posix' and 'nt' are supported, and
1070
the default compilers are "traditional Unix interface" (UnixCCompiler
1071
class) and Visual C++ (MSVCCompiler class). Note that it's perfectly
1072
possible to ask for a Unix compiler object under Windows, and a
1073
Microsoft compiler object under Unix -- if you supply a value for
1074
'compiler', 'plat' is ignored.
1080
if compiler is None:
1081
compiler = get_default_compiler(plat)
1083
(module_name, class_name, long_description) = compiler_class[compiler]
1085
msg = "don't know how to compile C/C++ code on platform '%s'" % plat
1086
if compiler is not None:
1087
msg = msg + " with '%s' compiler" % compiler
1088
raise DistutilsPlatformError(msg)
1091
module_name = "distutils." + module_name
1092
__import__ (module_name)
1093
module = sys.modules[module_name]
1094
klass = vars(module)[class_name]
1096
raise DistutilsModuleError(
1097
"can't compile C/C++ code: unable to load module '%s'" % \
1100
raise DistutilsModuleError(
1101
"can't compile C/C++ code: unable to find class '%s' "
1102
"in module '%s'" % (class_name, module_name))
1104
# XXX The None is necessary to preserve backwards compatibility
1105
# with classes that expect verbose to be the first positional
1107
return klass(None, dry_run, force)
1110
def gen_preprocess_options(macros, include_dirs):
1111
"""Generate C pre-processor options (-D, -U, -I) as used by at least
1112
two types of compilers: the typical Unix compiler and Visual C++.
1113
'macros' is the usual thing, a list of 1- or 2-tuples, where (name,)
1114
means undefine (-U) macro 'name', and (name,value) means define (-D)
1115
macro 'name' to 'value'. 'include_dirs' is just a list of directory
1116
names to be added to the header file search path (-I). Returns a list
1117
of command-line options suitable for either Unix compilers or Visual
1120
# XXX it would be nice (mainly aesthetic, and so we don't generate
1121
# stupid-looking command lines) to go over 'macros' and eliminate
1122
# redundant definitions/undefinitions (ie. ensure that only the
1123
# latest mention of a particular macro winds up on the command
1124
# line). I don't think it's essential, though, since most (all?)
1125
# Unix C compilers only pay attention to the latest -D or -U
1126
# mention of a macro on their command line. Similar situation for
1127
# 'include_dirs'. I'm punting on both for now. Anyways, weeding out
1128
# redundancies like this should probably be the province of
1129
# CCompiler, since the data structures used are inherited from it
1130
# and therefore common to all CCompiler classes.
1132
for macro in macros:
1133
if not (isinstance(macro, tuple) and 1 <= len(macro) <= 2):
1135
"bad macro definition '%s': "
1136
"each element of 'macros' list must be a 1- or 2-tuple"
1139
if len(macro) == 1: # undefine this macro
1140
pp_opts.append("-U%s" % macro[0])
1141
elif len(macro) == 2:
1142
if macro[1] is None: # define with no explicit value
1143
pp_opts.append("-D%s" % macro[0])
1145
# XXX *don't* need to be clever about quoting the
1146
# macro value here, because we're going to avoid the
1147
# shell at all costs when we spawn the command!
1148
pp_opts.append("-D%s=%s" % macro)
1150
for dir in include_dirs:
1151
pp_opts.append("-I%s" % dir)
1155
def gen_lib_options (compiler, library_dirs, runtime_library_dirs, libraries):
1156
"""Generate linker options for searching library directories and
1157
linking with specific libraries. 'libraries' and 'library_dirs' are,
1158
respectively, lists of library names (not filenames!) and search
1159
directories. Returns a list of command-line options suitable for use
1160
with some compiler (depending on the two format strings passed in).
1164
for dir in library_dirs:
1165
lib_opts.append(compiler.library_dir_option(dir))
1167
for dir in runtime_library_dirs:
1168
opt = compiler.runtime_library_dir_option(dir)
1169
if isinstance(opt, list):
1170
lib_opts = lib_opts + opt
1172
lib_opts.append(opt)
1174
# XXX it's important that we *not* remove redundant library mentions!
1175
# sometimes you really do have to say "-lfoo -lbar -lfoo" in order to
1176
# resolve all symbols. I just hope we never have to say "-lfoo obj.o
1177
# -lbar" to get things to work -- that's certainly a possibility, but a
1178
# pretty nasty way to arrange your C code.
1180
for lib in libraries:
1181
(lib_dir, lib_name) = os.path.split(lib)
1183
lib_file = compiler.find_library_file([lib_dir], lib_name)
1185
lib_opts.append(lib_file)
1187
compiler.warn("no library file corresponding to "
1188
"'%s' found (skipping)" % lib)
1190
lib_opts.append(compiler.library_option (lib))
added
removed
Lib/distutils/ccompiler.py
