]>
jfr.im git - dlqueue.git/blob - venv/lib/python3.11/site-packages/setuptools/_distutils/ccompiler.py
3 Contains CCompiler, an abstract base class that defines the interface
4 for the Distutils compiler abstraction model."""
15 DistutilsPlatformError
,
18 from .spawn
import spawn
19 from .file_util
import move_file
20 from .dir_util
import mkpath
21 from .dep_util
import newer_group
22 from .util
import split_quoted
, execute
27 """Abstract base class to define the interface that must be implemented
28 by real compiler classes. Also has some utility methods used by
29 several compiler classes.
31 The basic idea behind a compiler abstraction class is that each
32 instance can be used for all the compile/link steps in building a
33 single project. Thus, attributes common to all of those compile and
34 link steps -- include directories, macros to define, libraries to link
35 against, etc. -- are attributes of the compiler instance. To allow for
36 variability in how individual files are treated, most of those
37 attributes may be varied on a per-compilation or per-link basis.
40 # 'compiler_type' is a class attribute that identifies this class. It
41 # keeps code that wants to know what kind of compiler it's dealing with
42 # from having to import all possible compiler classes just to do an
43 # 'isinstance'. In concrete CCompiler subclasses, 'compiler_type'
44 # should really, really be one of the keys of the 'compiler_class'
45 # dictionary (see below -- used by the 'new_compiler()' factory
46 # function) -- authors of new compiler interface classes are
47 # responsible for updating 'compiler_class'!
50 # XXX things not handled by this compiler abstraction model:
51 # * client can't provide additional options for a compiler,
52 # e.g. warning, optimization, debugging flags. Perhaps this
53 # should be the domain of concrete compiler abstraction classes
54 # (UnixCCompiler, MSVCCompiler, etc.) -- or perhaps the base
55 # class should have methods for the common ones.
56 # * can't completely override the include or library searchg
57 # path, ie. no "cc -I -Idir1 -Idir2" or "cc -L -Ldir1 -Ldir2".
58 # I'm not sure how widely supported this is even by Unix
59 # compilers, much less on other platforms. And I'm even less
60 # sure how useful it is; maybe for cross-compiling, but
61 # support for that is a ways off. (And anyways, cross
62 # compilers probably have a dedicated binary with the
63 # right paths compiled in. I hope.)
64 # * can't do really freaky things with the library list/library
65 # dirs, e.g. "-Ldir1 -lfoo -Ldir2 -lfoo" to link against
66 # different versions of libfoo.a in different locations. I
67 # think this is useless without the ability to null out the
68 # library search path anyways.
70 # Subclasses that rely on the standard filename generation methods
71 # implemented below should override these; see the comment near
72 # those methods ('object_filenames()' et. al.) for details:
73 src_extensions
= None # list of strings
74 obj_extension
= None # string
75 static_lib_extension
= None
76 shared_lib_extension
= None # string
77 static_lib_format
= None # format string
78 shared_lib_format
= None # prob. same as static_lib_format
79 exe_extension
= None # string
81 # Default language settings. language_map is used to detect a source
82 # file or Extension target language, checking source filenames.
83 # language_order is used to detect the language precedence, when deciding
84 # what language to use when mixing source types. For example, if some
85 # extension has two files with ".c" extension, and one with ".cpp", it
86 # is still linked as c++.
94 language_order
= ["c++", "objc", "c"]
98 include dirs specific to this compiler class
103 library dirs specific to this compiler class
106 def __init__(self
, verbose
=0, dry_run
=0, force
=0):
107 self
.dry_run
= dry_run
109 self
.verbose
= verbose
111 # 'output_dir': a common output directory for object, library,
112 # shared object, and shared library files
113 self
.output_dir
= None
115 # 'macros': a list of macro definitions (or undefinitions). A
116 # macro definition is a 2-tuple (name, value), where the value is
117 # either a string or None (no explicit value). A macro
118 # undefinition is a 1-tuple (name,).
121 # 'include_dirs': a list of directories to search for include files
122 self
.include_dirs
= []
124 # 'libraries': a list of libraries to include in any link
125 # (library names, not filenames: eg. "foo" not "libfoo.a")
128 # 'library_dirs': a list of directories to search for libraries
129 self
.library_dirs
= []
131 # 'runtime_library_dirs': a list of directories to search for
132 # shared libraries/objects at runtime
133 self
.runtime_library_dirs
= []
135 # 'objects': a list of object files (or similar, such as explicitly
136 # named library files) to include on any link
139 for key
in self
.executables
.keys():
140 self
.set_executable(key
, self
.executables
[key
])
142 def set_executables(self
, **kwargs
):
143 """Define the executables (and options for them) that will be run
144 to perform the various stages of compilation. The exact set of
145 executables that may be specified here depends on the compiler
146 class (via the 'executables' class attribute), but most will have:
147 compiler the C/C++ compiler
148 linker_so linker used to create shared objects and libraries
149 linker_exe linker used to create binary executables
150 archiver static library creator
152 On platforms with a command-line (Unix, DOS/Windows), each of these
153 is a string that will be split into executable name and (optional)
154 list of arguments. (Splitting the string is done similarly to how
155 Unix shells operate: words are delimited by spaces, but quotes and
156 backslashes can override this. See
157 'distutils.util.split_quoted()'.)
160 # Note that some CCompiler implementation classes will define class
161 # attributes 'cpp', 'cc', etc. with hard-coded executable names;
162 # this is appropriate when a compiler class is for exactly one
163 # compiler/OS combination (eg. MSVCCompiler). Other compiler
164 # classes (UnixCCompiler, in particular) are driven by information
165 # discovered at run-time, since there are many different ways to do
166 # basically the same things with Unix C compilers.
169 if key
not in self
.executables
:
171 "unknown executable '%s' for class %s"
172 % (key
, self
.__class
__.__name
__)
174 self
.set_executable(key
, kwargs
[key
])
176 def set_executable(self
, key
, value
):
177 if isinstance(value
, str):
178 setattr(self
, key
, split_quoted(value
))
180 setattr(self
, key
, value
)
182 def _find_macro(self
, name
):
184 for defn
in self
.macros
:
190 def _check_macro_definitions(self
, definitions
):
191 """Ensures that every element of 'definitions' is a valid macro
192 definition, ie. either (name,value) 2-tuple or a (name,) tuple. Do
193 nothing if all definitions are OK, raise TypeError otherwise.
195 for defn
in definitions
:
197 isinstance(defn
, tuple)
200 and (isinstance(defn
[1], str) or defn
[1] is None)
202 and isinstance(defn
[0], str)
205 ("invalid macro definition '%s': " % defn
)
206 + "must be tuple (string,), (string, string), or "
210 # -- Bookkeeping methods -------------------------------------------
212 def define_macro(self
, name
, value
=None):
213 """Define a preprocessor macro for all compilations driven by this
214 compiler object. The optional parameter 'value' should be a
215 string; if it is not supplied, then the macro will be defined
216 without an explicit value and the exact outcome depends on the
217 compiler used (XXX true? does ANSI say anything about this?)
219 # Delete from the list of macro definitions/undefinitions if
220 # already there (so that this one will take precedence).
221 i
= self
._find
_macro
(name
)
225 self
.macros
.append((name
, value
))
227 def undefine_macro(self
, name
):
228 """Undefine a preprocessor macro for all compilations driven by
229 this compiler object. If the same macro is defined by
230 'define_macro()' and undefined by 'undefine_macro()' the last call
231 takes precedence (including multiple redefinitions or
232 undefinitions). If the macro is redefined/undefined on a
233 per-compilation basis (ie. in the call to 'compile()'), then that
236 # Delete from the list of macro definitions/undefinitions if
237 # already there (so that this one will take precedence).
238 i
= self
._find
_macro
(name
)
243 self
.macros
.append(undefn
)
245 def add_include_dir(self
, dir):
246 """Add 'dir' to the list of directories that will be searched for
247 header files. The compiler is instructed to search directories in
248 the order in which they are supplied by successive calls to
251 self
.include_dirs
.append(dir)
253 def set_include_dirs(self
, dirs
):
254 """Set the list of directories that will be searched to 'dirs' (a
255 list of strings). Overrides any preceding calls to
256 'add_include_dir()'; subsequence calls to 'add_include_dir()' add
257 to the list passed to 'set_include_dirs()'. This does not affect
258 any list of standard include directories that the compiler may
261 self
.include_dirs
= dirs
[:]
263 def add_library(self
, libname
):
264 """Add 'libname' to the list of libraries that will be included in
265 all links driven by this compiler object. Note that 'libname'
266 should *not* be the name of a file containing a library, but the
267 name of the library itself: the actual filename will be inferred by
268 the linker, the compiler, or the compiler class (depending on the
271 The linker will be instructed to link against libraries in the
272 order they were supplied to 'add_library()' and/or
273 'set_libraries()'. It is perfectly valid to duplicate library
274 names; the linker will be instructed to link against libraries as
275 many times as they are mentioned.
277 self
.libraries
.append(libname
)
279 def set_libraries(self
, libnames
):
280 """Set the list of libraries to be included in all links driven by
281 this compiler object to 'libnames' (a list of strings). This does
282 not affect any standard system libraries that the linker may
285 self
.libraries
= libnames
[:]
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()'.
293 self
.library_dirs
.append(dir)
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.
300 self
.library_dirs
= dirs
[:]
302 def add_runtime_library_dir(self
, dir):
303 """Add 'dir' to the list of directories that will be searched for
304 shared libraries at runtime.
306 self
.runtime_library_dirs
.append(dir)
308 def set_runtime_library_dirs(self
, dirs
):
309 """Set the list of directories to search for shared libraries at
310 runtime to 'dirs' (a list of strings). This does not affect any
311 standard search path that the runtime linker may search by
314 self
.runtime_library_dirs
= dirs
[:]
316 def add_link_object(self
, object):
317 """Add 'object' to the list of object files (or analogues, such as
318 explicitly named library files or the output of "resource
319 compilers") to be included in every link driven by this compiler
322 self
.objects
.append(object)
324 def set_link_objects(self
, objects
):
325 """Set the list of object files (or analogues) to be included in
326 every link to 'objects'. This does not affect any standard object
327 files that the linker may include by default (such as system
330 self
.objects
= objects
[:]
332 # -- Private utility methods --------------------------------------
333 # (here for the convenience of subclasses)
335 # Helper method to prep compiler in subclass compile() methods
337 def _setup_compile(self
, outdir
, macros
, incdirs
, sources
, depends
, extra
):
338 """Process arguments and decide which source files to compile."""
339 outdir
, macros
, incdirs
= self
._fix
_compile
_args
(outdir
, macros
, incdirs
)
344 # Get the list of expected output (object) files
345 objects
= self
.object_filenames(sources
, strip_dir
=0, output_dir
=outdir
)
346 assert len(objects
) == len(sources
)
348 pp_opts
= gen_preprocess_options(macros
, incdirs
)
351 for i
in range(len(sources
)):
354 ext
= os
.path
.splitext(src
)[1]
355 self
.mkpath(os
.path
.dirname(obj
))
356 build
[obj
] = (src
, ext
)
358 return macros
, objects
, extra
, pp_opts
, build
360 def _get_cc_args(self
, pp_opts
, debug
, before
):
361 # works for unixccompiler, cygwinccompiler
362 cc_args
= pp_opts
+ ['-c']
369 def _fix_compile_args(self
, output_dir
, macros
, include_dirs
):
370 """Typecheck and fix-up some of the arguments to the 'compile()'
371 method, and return fixed-up values. Specifically: if 'output_dir'
372 is None, replaces it with 'self.output_dir'; ensures that 'macros'
373 is a list, and augments it with 'self.macros'; ensures that
374 'include_dirs' is a list, and augments it with 'self.include_dirs'.
375 Guarantees that the returned values are of the correct type,
376 i.e. for 'output_dir' either string or None, and for 'macros' and
377 'include_dirs' either list or None.
379 if output_dir
is None:
380 output_dir
= self
.output_dir
381 elif not isinstance(output_dir
, str):
382 raise TypeError("'output_dir' must be a string or None")
386 elif isinstance(macros
, list):
387 macros
= macros
+ (self
.macros
or [])
389 raise TypeError("'macros' (if supplied) must be a list of tuples")
391 if include_dirs
is None:
392 include_dirs
= list(self
.include_dirs
)
393 elif isinstance(include_dirs
, (list, tuple)):
394 include_dirs
= list(include_dirs
) + (self
.include_dirs
or [])
396 raise TypeError("'include_dirs' (if supplied) must be a list of strings")
398 # add include dirs for class
399 include_dirs
+= self
.__class
__.include_dirs
401 return output_dir
, macros
, include_dirs
403 def _prep_compile(self
, sources
, output_dir
, depends
=None):
404 """Decide which source files must be recompiled.
406 Determine the list of object files corresponding to 'sources',
407 and figure out which ones really need to be recompiled.
408 Return a list of all object files and a dictionary telling
409 which source files can be skipped.
411 # Get the list of expected output (object) files
412 objects
= self
.object_filenames(sources
, output_dir
=output_dir
)
413 assert len(objects
) == len(sources
)
415 # Return an empty dict for the "which source files can be skipped"
416 # return value to preserve API compatibility.
419 def _fix_object_args(self
, objects
, output_dir
):
420 """Typecheck and fix up some arguments supplied to various methods.
421 Specifically: ensure that 'objects' is a list; if output_dir is
422 None, replace with self.output_dir. Return fixed versions of
423 'objects' and 'output_dir'.
425 if not isinstance(objects
, (list, tuple)):
426 raise TypeError("'objects' must be a list or tuple of strings")
427 objects
= list(objects
)
429 if output_dir
is None:
430 output_dir
= self
.output_dir
431 elif not isinstance(output_dir
, str):
432 raise TypeError("'output_dir' must be a string or None")
434 return (objects
, output_dir
)
436 def _fix_lib_args(self
, libraries
, library_dirs
, runtime_library_dirs
):
437 """Typecheck and fix up some of the arguments supplied to the
438 'link_*' methods. Specifically: ensure that all arguments are
439 lists, and augment them with their permanent versions
440 (eg. 'self.libraries' augments 'libraries'). Return a tuple with
441 fixed versions of all arguments.
443 if libraries
is None:
444 libraries
= self
.libraries
445 elif isinstance(libraries
, (list, tuple)):
446 libraries
= list(libraries
) + (self
.libraries
or [])
448 raise TypeError("'libraries' (if supplied) must be a list of strings")
450 if library_dirs
is None:
451 library_dirs
= self
.library_dirs
452 elif isinstance(library_dirs
, (list, tuple)):
453 library_dirs
= list(library_dirs
) + (self
.library_dirs
or [])
455 raise TypeError("'library_dirs' (if supplied) must be a list of strings")
457 # add library dirs for class
458 library_dirs
+= self
.__class
__.library_dirs
460 if runtime_library_dirs
is None:
461 runtime_library_dirs
= self
.runtime_library_dirs
462 elif isinstance(runtime_library_dirs
, (list, tuple)):
463 runtime_library_dirs
= list(runtime_library_dirs
) + (
464 self
.runtime_library_dirs
or []
468 "'runtime_library_dirs' (if supplied) " "must be a list of strings"
471 return (libraries
, library_dirs
, runtime_library_dirs
)
473 def _need_link(self
, objects
, output_file
):
474 """Return true if we need to relink the files listed in 'objects'
475 to recreate 'output_file'.
481 newer
= newer_group(objects
, output_file
, missing
='newer')
483 newer
= newer_group(objects
, output_file
)
486 def detect_language(self
, sources
):
487 """Detect the language of a given file, or list of files. Uses
488 language_map, and language_order to do the job.
490 if not isinstance(sources
, list):
493 index
= len(self
.language_order
)
494 for source
in sources
:
495 base
, ext
= os
.path
.splitext(source
)
496 extlang
= self
.language_map
.get(ext
)
498 extindex
= self
.language_order
.index(extlang
)
506 # -- Worker methods ------------------------------------------------
507 # (must be implemented by subclasses)
518 """Preprocess a single C/C++ source file, named in 'source'.
519 Output will be written to file named 'output_file', or stdout if
520 'output_file' not supplied. 'macros' is a list of macro
521 definitions as for 'compile()', which will augment the macros set
522 with 'define_macro()' and 'undefine_macro()'. 'include_dirs' is a
523 list of directory names that will be added to the default list.
525 Raises PreprocessError on failure.
540 """Compile one or more source files.
542 'sources' must be a list of filenames, most likely C/C++
543 files, but in reality anything that can be handled by a
544 particular compiler and compiler class (eg. MSVCCompiler can
545 handle resource files in 'sources'). Return a list of object
546 filenames, one per source filename in 'sources'. Depending on
547 the implementation, not all source files will necessarily be
548 compiled, but all corresponding object filenames will be
551 If 'output_dir' is given, object files will be put under it, while
552 retaining their original path component. That is, "foo/bar.c"
553 normally compiles to "foo/bar.o" (for a Unix implementation); if
554 'output_dir' is "build", then it would compile to
557 'macros', if given, must be a list of macro definitions. A macro
558 definition is either a (name, value) 2-tuple or a (name,) 1-tuple.
559 The former defines a macro; if the value is None, the macro is
560 defined without an explicit value. The 1-tuple case undefines a
561 macro. Later definitions/redefinitions/ undefinitions take
564 'include_dirs', if given, must be a list of strings, the
565 directories to add to the default include file search path for this
568 'debug' is a boolean; if true, the compiler will be instructed to
569 output debug symbols in (or alongside) the object file(s).
571 'extra_preargs' and 'extra_postargs' are implementation- dependent.
572 On platforms that have the notion of a command-line (e.g. Unix,
573 DOS/Windows), they are most likely lists of strings: extra
574 command-line arguments to prepend/append to the compiler command
575 line. On other platforms, consult the implementation class
576 documentation. In any event, they are intended as an escape hatch
577 for those occasions when the abstract compiler framework doesn't
580 'depends', if given, is a list of filenames that all targets
581 depend on. If a source file is older than any file in
582 depends, then the source file will be recompiled. This
583 supports dependency tracking, but only at a coarse
586 Raises CompileError on failure.
588 # A concrete compiler class can either override this method
589 # entirely or implement _compile().
590 macros
, objects
, extra_postargs
, pp_opts
, build
= self
._setup
_compile
(
591 output_dir
, macros
, include_dirs
, sources
, depends
, extra_postargs
593 cc_args
= self
._get
_cc
_args
(pp_opts
, debug
, extra_preargs
)
597 src
, ext
= build
[obj
]
600 self
._compile
(obj
, src
, ext
, cc_args
, extra_postargs
, pp_opts
)
602 # Return *all* object filenames, not just the ones we just built.
605 def _compile(self
, obj
, src
, ext
, cc_args
, extra_postargs
, pp_opts
):
606 """Compile 'src' to product 'obj'."""
607 # A concrete compiler class that does not override compile()
608 # should implement _compile().
611 def create_static_lib(
612 self
, objects
, output_libname
, output_dir
=None, debug
=0, target_lang
=None
614 """Link a bunch of stuff together to create a static library file.
615 The "bunch of stuff" consists of the list of object files supplied
616 as 'objects', the extra object files supplied to
617 'add_link_object()' and/or 'set_link_objects()', the libraries
618 supplied to 'add_library()' and/or 'set_libraries()', and the
619 libraries supplied as 'libraries' (if any).
621 'output_libname' should be a library name, not a filename; the
622 filename will be inferred from the library name. 'output_dir' is
623 the directory where the library file will be put.
625 'debug' is a boolean; if true, debugging information will be
626 included in the library (note that on most platforms, it is the
627 compile step where this matters: the 'debug' flag is included here
628 just for consistency).
630 'target_lang' is the target language for which the given objects
631 are being compiled. This allows specific linkage time treatment of
634 Raises LibError on failure.
638 # values for target_desc parameter in link()
639 SHARED_OBJECT
= "shared_object"
640 SHARED_LIBRARY
= "shared_library"
641 EXECUTABLE
= "executable"
651 runtime_library_dirs
=None,
659 """Link a bunch of stuff together to create an executable or
662 The "bunch of stuff" consists of the list of object files supplied
663 as 'objects'. 'output_filename' should be a filename. If
664 'output_dir' is supplied, 'output_filename' is relative to it
665 (i.e. 'output_filename' can provide directory components if
668 'libraries' is a list of libraries to link against. These are
669 library names, not filenames, since they're translated into
670 filenames in a platform-specific way (eg. "foo" becomes "libfoo.a"
671 on Unix and "foo.lib" on DOS/Windows). However, they can include a
672 directory component, which means the linker will look in that
673 specific directory rather than searching all the normal locations.
675 'library_dirs', if supplied, should be a list of directories to
676 search for libraries that were specified as bare library names
677 (ie. no directory component). These are on top of the system
678 default and those supplied to 'add_library_dir()' and/or
679 'set_library_dirs()'. 'runtime_library_dirs' is a list of
680 directories that will be embedded into the shared library and used
681 to search for other shared libraries that *it* depends on at
682 run-time. (This may only be relevant on Unix.)
684 'export_symbols' is a list of symbols that the shared library will
685 export. (This appears to be relevant only on Windows.)
687 'debug' is as for 'compile()' and 'create_static_lib()', with the
688 slight distinction that it actually matters on most platforms (as
689 opposed to 'create_static_lib()', which includes a 'debug' flag
690 mostly for form's sake).
692 'extra_preargs' and 'extra_postargs' are as for 'compile()' (except
693 of course that they supply command-line arguments for the
694 particular linker being used).
696 'target_lang' is the target language for which the given objects
697 are being compiled. This allows specific linkage time treatment of
700 Raises LinkError on failure.
702 raise NotImplementedError
704 # Old 'link_*()' methods, rewritten to use the new 'link()' method.
713 runtime_library_dirs
=None,
722 CCompiler
.SHARED_LIBRARY
,
724 self
.library_filename(output_libname
, lib_type
='shared'),
728 runtime_library_dirs
,
737 def link_shared_object(
744 runtime_library_dirs
=None,
753 CCompiler
.SHARED_OBJECT
,
759 runtime_library_dirs
,
775 runtime_library_dirs
=None,
782 CCompiler
.EXECUTABLE
,
784 self
.executable_filename(output_progname
),
788 runtime_library_dirs
,
797 # -- Miscellaneous methods -----------------------------------------
798 # These are all used by the 'gen_lib_options() function; there is
799 # no appropriate default implementation so subclasses should
800 # implement all of these.
802 def library_dir_option(self
, dir):
803 """Return the compiler option to add 'dir' to the list of
804 directories searched for libraries.
806 raise NotImplementedError
808 def runtime_library_dir_option(self
, dir):
809 """Return the compiler option to add 'dir' to the list of
810 directories searched for runtime libraries.
812 raise NotImplementedError
814 def library_option(self
, lib
):
815 """Return the compiler option to add 'lib' to the list of libraries
816 linked into the shared library or executable.
818 raise NotImplementedError
820 def has_function( # noqa: C901
828 """Return a boolean indicating whether funcname is provided as
829 a symbol on the current platform. The optional arguments can
830 be used to augment the compilation environment.
832 The libraries argument is a list of flags to be passed to the
833 linker to make additional symbol definitions available for
836 The includes and include_dirs arguments are deprecated.
837 Usually, supplying include files with function declarations
838 will cause function detection to fail even in cases where the
839 symbol is available for linking.
842 # this can't be included at module scope because it tries to
843 # import math which might not be available at that point - maybe
844 # the necessary logic should just be inlined?
850 warnings
.warn("includes is deprecated", DeprecationWarning)
851 if include_dirs
is None:
854 warnings
.warn("include_dirs is deprecated", DeprecationWarning)
855 if libraries
is None:
857 if library_dirs
is None:
859 fd
, fname
= tempfile
.mkstemp(".c", funcname
, text
=True)
860 f
= os
.fdopen(fd
, "w")
862 for incl
in includes
:
863 f
.write("""#include "%s"\n""" % incl
)
865 # Use "char func(void);" as the prototype to follow
866 # what autoconf does. This prototype does not match
867 # any well-known function the compiler might recognize
868 # as a builtin, so this ends up as a true link test.
869 # Without a fake prototype, the test would need to
870 # know the exact argument types, and the has_function
871 # interface does not provide that level of information.
883 int main (int argc, char **argv) {
893 objects
= self
.compile([fname
], include_dirs
=include_dirs
)
900 self
.link_executable(
901 objects
, "a.out", libraries
=libraries
, library_dirs
=library_dirs
903 except (LinkError
, TypeError):
907 self
.executable_filename("a.out", output_dir
=self
.output_dir
or '')
914 def find_library_file(self
, dirs
, lib
, debug
=0):
915 """Search the specified list of directories for a static or shared
916 library file 'lib' and return the full path to that file. If
917 'debug' true, look for a debugging version (if that makes sense on
918 the current platform). Return None if 'lib' wasn't found in any of
919 the specified directories.
921 raise NotImplementedError
923 # -- Filename generation methods -----------------------------------
925 # The default implementation of the filename generating methods are
926 # prejudiced towards the Unix/DOS/Windows view of the world:
927 # * object files are named by replacing the source file extension
928 # (eg. .c/.cpp -> .o/.obj)
929 # * library files (shared or static) are named by plugging the
930 # library name and extension into a format string, eg.
931 # "lib%s.%s" % (lib_name, ".a") for Unix static libraries
932 # * executables are named by appending an extension (possibly
933 # empty) to the program name: eg. progname + ".exe" for
936 # To reduce redundant code, these methods expect to find
937 # several attributes in the current object (presumably defined
938 # as class attributes):
940 # list of C/C++ source file extensions, eg. ['.c', '.cpp']
942 # object file extension, eg. '.o' or '.obj'
943 # * static_lib_extension -
944 # extension for static library files, eg. '.a' or '.lib'
945 # * shared_lib_extension -
946 # extension for shared library/object files, eg. '.so', '.dll'
947 # * static_lib_format -
948 # format string for generating static library filenames,
949 # eg. 'lib%s.%s' or '%s.%s'
950 # * shared_lib_format
951 # format string for generating shared library filenames
952 # (probably same as static_lib_format, since the extension
953 # is one of the intended parameters to the format string)
955 # extension for executable files, eg. '' or '.exe'
957 def object_filenames(self
, source_filenames
, strip_dir
=0, output_dir
=''):
958 if output_dir
is None:
961 self
._make
_out
_path
(output_dir
, strip_dir
, src_name
)
962 for src_name
in source_filenames
966 def out_extensions(self
):
967 return dict.fromkeys(self
.src_extensions
, self
.obj_extension
)
969 def _make_out_path(self
, output_dir
, strip_dir
, src_name
):
970 base
, ext
= os
.path
.splitext(src_name
)
971 base
= self
._make
_relative
(base
)
973 new_ext
= self
.out_extensions
[ext
]
975 raise UnknownFileError(
976 "unknown file type '{}' (from '{}')".format(ext
, src_name
)
979 base
= os
.path
.basename(base
)
980 return os
.path
.join(output_dir
, base
+ new_ext
)
983 def _make_relative(base
):
985 In order to ensure that a filename always honors the
986 indicated output_dir, make sure it's relative.
987 Ref python/cpython#37775.
990 no_drive
= os
.path
.splitdrive(base
)[1]
991 # If abs, chop off leading /
992 return no_drive
[os
.path
.isabs(no_drive
) :]
994 def shared_object_filename(self
, basename
, strip_dir
=0, output_dir
=''):
995 assert output_dir
is not None
997 basename
= os
.path
.basename(basename
)
998 return os
.path
.join(output_dir
, basename
+ self
.shared_lib_extension
)
1000 def executable_filename(self
, basename
, strip_dir
=0, output_dir
=''):
1001 assert output_dir
is not None
1003 basename
= os
.path
.basename(basename
)
1004 return os
.path
.join(output_dir
, basename
+ (self
.exe_extension
or ''))
1006 def library_filename(
1007 self
, libname
, lib_type
='static', strip_dir
=0, output_dir
='' # or 'shared'
1009 assert output_dir
is not None
1010 expected
= '"static", "shared", "dylib", "xcode_stub"'
1011 if lib_type
not in eval(expected
):
1012 raise ValueError(f
"'lib_type' must be {expected}")
1013 fmt
= getattr(self
, lib_type
+ "_lib_format")
1014 ext
= getattr(self
, lib_type
+ "_lib_extension")
1016 dir, base
= os
.path
.split(libname
)
1017 filename
= fmt
% (base
, ext
)
1021 return os
.path
.join(output_dir
, dir, filename
)
1023 # -- Utility methods -----------------------------------------------
1025 def announce(self
, msg
, level
=1):
1028 def debug_print(self
, msg
):
1029 from distutils
.debug
import DEBUG
1034 def warn(self
, msg
):
1035 sys
.stderr
.write("warning: %s\n" % msg
)
1037 def execute(self
, func
, args
, msg
=None, level
=1):
1038 execute(func
, args
, msg
, self
.dry_run
)
1040 def spawn(self
, cmd
, **kwargs
):
1041 spawn(cmd
, dry_run
=self
.dry_run
, **kwargs
)
1043 def move_file(self
, src
, dst
):
1044 return move_file(src
, dst
, dry_run
=self
.dry_run
)
1046 def mkpath(self
, name
, mode
=0o777):
1047 mkpath(name
, mode
, dry_run
=self
.dry_run
)
1050 # Map a sys.platform/os.name ('posix', 'nt') to the default compiler
1051 # type for that platform. Keys are interpreted as re match
1052 # patterns. Order is important; platform mappings are preferred over
1054 _default_compilers
= (
1055 # Platform string mappings
1056 # on a cygwin built python we can use gcc like an ordinary UNIXish
1058 ('cygwin.*', 'unix'),
1065 def get_default_compiler(osname
=None, platform
=None):
1066 """Determine the default compiler to use for the given platform.
1068 osname should be one of the standard Python OS names (i.e. the
1069 ones returned by os.name) and platform the common value
1070 returned by sys.platform for the platform in question.
1072 The default values are os.name and sys.platform in case the
1073 parameters are not given.
1077 if platform
is None:
1078 platform
= sys
.platform
1079 for pattern
, compiler
in _default_compilers
:
1081 re
.match(pattern
, platform
) is not None
1082 or re
.match(pattern
, osname
) is not None
1085 # Default to Unix compiler
1089 # Map compiler types to (module_name, class_name) pairs -- ie. where to
1090 # find the code that implements an interface to this compiler. (The module
1091 # is assumed to be in the 'distutils' package.)
1093 'unix': ('unixccompiler', 'UnixCCompiler', "standard UNIX-style compiler"),
1094 'msvc': ('_msvccompiler', 'MSVCCompiler', "Microsoft Visual C++"),
1098 "Cygwin port of GNU C Compiler for Win32",
1103 "Mingw32 port of GNU C Compiler for Win32",
1105 'bcpp': ('bcppcompiler', 'BCPPCompiler', "Borland C++ Compiler"),
1109 def show_compilers():
1110 """Print list of available compilers (used by the "--help-compiler"
1111 options to "build", "build_ext", "build_clib").
1113 # XXX this "knows" that the compiler option it's describing is
1114 # "--compiler", which just happens to be the case for the three
1115 # commands that use it.
1116 from distutils
.fancy_getopt
import FancyGetopt
1119 for compiler
in compiler_class
.keys():
1120 compilers
.append(("compiler=" + compiler
, None, compiler_class
[compiler
][2]))
1122 pretty_printer
= FancyGetopt(compilers
)
1123 pretty_printer
.print_help("List of available compilers:")
1126 def new_compiler(plat
=None, compiler
=None, verbose
=0, dry_run
=0, force
=0):
1127 """Generate an instance of some CCompiler subclass for the supplied
1128 platform/compiler combination. 'plat' defaults to 'os.name'
1129 (eg. 'posix', 'nt'), and 'compiler' defaults to the default compiler
1130 for that platform. Currently only 'posix' and 'nt' are supported, and
1131 the default compilers are "traditional Unix interface" (UnixCCompiler
1132 class) and Visual C++ (MSVCCompiler class). Note that it's perfectly
1133 possible to ask for a Unix compiler object under Windows, and a
1134 Microsoft compiler object under Unix -- if you supply a value for
1135 'compiler', 'plat' is ignored.
1141 if compiler
is None:
1142 compiler
= get_default_compiler(plat
)
1144 (module_name
, class_name
, long_description
) = compiler_class
[compiler
]
1146 msg
= "don't know how to compile C/C++ code on platform '%s'" % plat
1147 if compiler
is not None:
1148 msg
= msg
+ " with '%s' compiler" % compiler
1149 raise DistutilsPlatformError(msg
)
1152 module_name
= "distutils." + module_name
1153 __import__(module_name
)
1154 module
= sys
.modules
[module_name
]
1155 klass
= vars(module
)[class_name
]
1157 raise DistutilsModuleError(
1158 "can't compile C/C++ code: unable to load module '%s'" % module_name
1161 raise DistutilsModuleError(
1162 "can't compile C/C++ code: unable to find class '%s' "
1163 "in module '%s'" % (class_name
, module_name
)
1166 # XXX The None is necessary to preserve backwards compatibility
1167 # with classes that expect verbose to be the first positional
1169 return klass(None, dry_run
, force
)
1172 def gen_preprocess_options(macros
, include_dirs
):
1173 """Generate C pre-processor options (-D, -U, -I) as used by at least
1174 two types of compilers: the typical Unix compiler and Visual C++.
1175 'macros' is the usual thing, a list of 1- or 2-tuples, where (name,)
1176 means undefine (-U) macro 'name', and (name,value) means define (-D)
1177 macro 'name' to 'value'. 'include_dirs' is just a list of directory
1178 names to be added to the header file search path (-I). Returns a list
1179 of command-line options suitable for either Unix compilers or Visual
1182 # XXX it would be nice (mainly aesthetic, and so we don't generate
1183 # stupid-looking command lines) to go over 'macros' and eliminate
1184 # redundant definitions/undefinitions (ie. ensure that only the
1185 # latest mention of a particular macro winds up on the command
1186 # line). I don't think it's essential, though, since most (all?)
1187 # Unix C compilers only pay attention to the latest -D or -U
1188 # mention of a macro on their command line. Similar situation for
1189 # 'include_dirs'. I'm punting on both for now. Anyways, weeding out
1190 # redundancies like this should probably be the province of
1191 # CCompiler, since the data structures used are inherited from it
1192 # and therefore common to all CCompiler classes.
1194 for macro
in macros
:
1195 if not (isinstance(macro
, tuple) and 1 <= len(macro
) <= 2):
1197 "bad macro definition '%s': "
1198 "each element of 'macros' list must be a 1- or 2-tuple" % macro
1201 if len(macro
) == 1: # undefine this macro
1202 pp_opts
.append("-U%s" % macro
[0])
1203 elif len(macro
) == 2:
1204 if macro
[1] is None: # define with no explicit value
1205 pp_opts
.append("-D%s" % macro
[0])
1207 # XXX *don't* need to be clever about quoting the
1208 # macro value here, because we're going to avoid the
1209 # shell at all costs when we spawn the command!
1210 pp_opts
.append("-D%s=%s" % macro
)
1212 for dir in include_dirs
:
1213 pp_opts
.append("-I%s" % dir)
1217 def gen_lib_options(compiler
, library_dirs
, runtime_library_dirs
, libraries
):
1218 """Generate linker options for searching library directories and
1219 linking with specific libraries. 'libraries' and 'library_dirs' are,
1220 respectively, lists of library names (not filenames!) and search
1221 directories. Returns a list of command-line options suitable for use
1222 with some compiler (depending on the two format strings passed in).
1226 for dir in library_dirs
:
1227 lib_opts
.append(compiler
.library_dir_option(dir))
1229 for dir in runtime_library_dirs
:
1230 opt
= compiler
.runtime_library_dir_option(dir)
1231 if isinstance(opt
, list):
1232 lib_opts
= lib_opts
+ opt
1234 lib_opts
.append(opt
)
1236 # XXX it's important that we *not* remove redundant library mentions!
1237 # sometimes you really do have to say "-lfoo -lbar -lfoo" in order to
1238 # resolve all symbols. I just hope we never have to say "-lfoo obj.o
1239 # -lbar" to get things to work -- that's certainly a possibility, but a
1240 # pretty nasty way to arrange your C code.
1242 for lib
in libraries
:
1243 (lib_dir
, lib_name
) = os
.path
.split(lib
)
1245 lib_file
= compiler
.find_library_file([lib_dir
], lib_name
)
1247 lib_opts
.append(lib_file
)
1250 "no library file corresponding to " "'%s' found (skipping)" % lib
1253 lib_opts
.append(compiler
.library_option(lib
))