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