ยปCore Development>Code coverage>Lib/distutils/ccompiler.py

Python code coverage for Lib/distutils/ccompiler.py

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