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