• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1.. _api-reference:
2
3*************
4API Reference
5*************
6
7
8:mod:`distutils.core` --- Core Distutils functionality
9======================================================
10
11.. module:: distutils.core
12   :synopsis: The core Distutils functionality
13
14
15The :mod:`distutils.core` module is the only module that needs to be installed
16to use the Distutils. It provides the :func:`setup` (which is called from the
17setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
18:class:`distutils.cmd.Command` class.
19
20
21.. function:: setup(arguments)
22
23   The basic do-everything function that does most everything you could ever ask
24   for from a Distutils method.
25
26   The setup function takes a large number of arguments. These are laid out in the
27   following table.
28
29   .. tabularcolumns:: |l|L|L|
30
31   +--------------------+--------------------------------+-------------------------------------------------------------+
32   | argument name      | value                          | type                                                        |
33   +====================+================================+=============================================================+
34   | *name*             | The name of the package        | a string                                                    |
35   +--------------------+--------------------------------+-------------------------------------------------------------+
36   | *version*          | The version number of the      | a string                                                    |
37   |                    | package; see                   |                                                             |
38   |                    | :mod:`distutils.version`       |                                                             |
39   +--------------------+--------------------------------+-------------------------------------------------------------+
40   | *description*      | A single line describing the   | a string                                                    |
41   |                    | package                        |                                                             |
42   +--------------------+--------------------------------+-------------------------------------------------------------+
43   | *long_description* | Longer description of the      | a string                                                    |
44   |                    | package                        |                                                             |
45   +--------------------+--------------------------------+-------------------------------------------------------------+
46   | *author*           | The name of the package author | a string                                                    |
47   +--------------------+--------------------------------+-------------------------------------------------------------+
48   | *author_email*     | The email address of the       | a string                                                    |
49   |                    | package author                 |                                                             |
50   +--------------------+--------------------------------+-------------------------------------------------------------+
51   | *maintainer*       | The name of the current        | a string                                                    |
52   |                    | maintainer, if different from  |                                                             |
53   |                    | the author. Note that if       |                                                             |
54   |                    | the maintainer is provided,    |                                                             |
55   |                    | distutils will use it as the   |                                                             |
56   |                    | author in :file:`PKG-INFO`     |                                                             |
57   +--------------------+--------------------------------+-------------------------------------------------------------+
58   | *maintainer_email* | The email address of the       | a string                                                    |
59   |                    | current maintainer, if         |                                                             |
60   |                    | different from the author      |                                                             |
61   +--------------------+--------------------------------+-------------------------------------------------------------+
62   | *url*              | A URL for the package          | a string                                                    |
63   |                    | (homepage)                     |                                                             |
64   +--------------------+--------------------------------+-------------------------------------------------------------+
65   | *download_url*     | A URL to download the package  | a string                                                    |
66   +--------------------+--------------------------------+-------------------------------------------------------------+
67   | *packages*         | A list of Python packages that | a list of strings                                           |
68   |                    | distutils will manipulate      |                                                             |
69   +--------------------+--------------------------------+-------------------------------------------------------------+
70   | *py_modules*       | A list of Python modules that  | a list of strings                                           |
71   |                    | distutils will manipulate      |                                                             |
72   +--------------------+--------------------------------+-------------------------------------------------------------+
73   | *scripts*          | A list of standalone script    | a list of strings                                           |
74   |                    | files to be built and          |                                                             |
75   |                    | installed                      |                                                             |
76   +--------------------+--------------------------------+-------------------------------------------------------------+
77   | *ext_modules*      | A list of Python extensions to | a list of instances of                                      |
78   |                    | be built                       | :class:`distutils.core.Extension`                           |
79   +--------------------+--------------------------------+-------------------------------------------------------------+
80   | *classifiers*      | A list of categories for the   | a list of strings; valid classifiers are listed on `PyPI    |
81   |                    | package                        | <https://pypi.org/classifiers>`_.                           |
82   +--------------------+--------------------------------+-------------------------------------------------------------+
83   | *distclass*        | the :class:`Distribution`      | a subclass of                                               |
84   |                    | class to use                   | :class:`distutils.core.Distribution`                        |
85   +--------------------+--------------------------------+-------------------------------------------------------------+
86   | *script_name*      | The name of the setup.py       | a string                                                    |
87   |                    | script - defaults to           |                                                             |
88   |                    | ``sys.argv[0]``                |                                                             |
89   +--------------------+--------------------------------+-------------------------------------------------------------+
90   | *script_args*      | Arguments to supply to the     | a list of strings                                           |
91   |                    | setup script                   |                                                             |
92   +--------------------+--------------------------------+-------------------------------------------------------------+
93   | *options*          | default options for the setup  | a dictionary                                                |
94   |                    | script                         |                                                             |
95   +--------------------+--------------------------------+-------------------------------------------------------------+
96   | *license*          | The license for the package    | a string                                                    |
97   +--------------------+--------------------------------+-------------------------------------------------------------+
98   | *keywords*         | Descriptive meta-data, see     | a list of strings or a comma-separated string               |
99   |                    | :pep:`314`                     |                                                             |
100   +--------------------+--------------------------------+-------------------------------------------------------------+
101   | *platforms*        |                                | a list of strings or a comma-separated string               |
102   +--------------------+--------------------------------+-------------------------------------------------------------+
103   | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
104   |                    | :class:`Command` subclasses    |                                                             |
105   +--------------------+--------------------------------+-------------------------------------------------------------+
106   | *data_files*       | A list of data files to        | a list                                                      |
107   |                    | install                        |                                                             |
108   +--------------------+--------------------------------+-------------------------------------------------------------+
109   | *package_dir*      | A mapping of package to        | a dictionary                                                |
110   |                    | directory names                |                                                             |
111   +--------------------+--------------------------------+-------------------------------------------------------------+
112
113
114
115.. function:: run_setup(script_name[, script_args=None, stop_after='run'])
116
117   Run a setup script in a somewhat controlled environment, and return  the
118   :class:`distutils.dist.Distribution` instance that drives things.   This is
119   useful if you need to find out the distribution meta-data  (passed as keyword
120   args from *script* to :func:`setup`), or  the contents of the config files or
121   command-line.
122
123   *script_name* is a file that will be read and run with :func:`exec`.  ``sys.argv[0]``
124   will be replaced with *script* for the duration of the call.  *script_args* is a
125   list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
126   for the duration  of the call.
127
128   *stop_after* tells :func:`setup` when to stop processing; possible  values:
129
130   .. tabularcolumns:: |l|L|
131
132   +---------------+---------------------------------------------+
133   | value         | description                                 |
134   +===============+=============================================+
135   | *init*        | Stop after the :class:`Distribution`        |
136   |               | instance has been created  and populated    |
137   |               | with the keyword arguments to :func:`setup` |
138   +---------------+---------------------------------------------+
139   | *config*      | Stop after config files have been parsed    |
140   |               | (and their data stored in the               |
141   |               | :class:`Distribution` instance)             |
142   +---------------+---------------------------------------------+
143   | *commandline* | Stop after the command-line                 |
144   |               | (``sys.argv[1:]`` or  *script_args*) have   |
145   |               | been parsed (and the data stored in the     |
146   |               | :class:`Distribution` instance.)            |
147   +---------------+---------------------------------------------+
148   | *run*         | Stop after all commands have been run (the  |
149   |               | same as  if :func:`setup` had been called   |
150   |               | in the usual way). This is the default      |
151   |               | value.                                      |
152   +---------------+---------------------------------------------+
153
154In addition, the :mod:`distutils.core` module exposed a number of  classes that
155live elsewhere.
156
157* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
158
159* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
160
161* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
162
163A short description of each of these follows, but see the relevant module for
164the full reference.
165
166
167.. class:: Extension
168
169   The Extension class describes a single C or C++ extension module in a setup
170   script. It accepts the following keyword arguments in its constructor:
171
172   .. tabularcolumns:: |l|L|l|
173
174   +------------------------+--------------------------------+---------------------------+
175   | argument name          | value                          | type                      |
176   +========================+================================+===========================+
177   | *name*                 | the full name of the           | a string                  |
178   |                        | extension, including any       |                           |
179   |                        | packages --- ie. *not* a       |                           |
180   |                        | filename or pathname, but      |                           |
181   |                        | Python dotted name             |                           |
182   +------------------------+--------------------------------+---------------------------+
183   | *sources*              | list of source filenames,      | a list of strings         |
184   |                        | relative to the distribution   |                           |
185   |                        | root (where the setup script   |                           |
186   |                        | lives), in Unix form           |                           |
187   |                        | (slash-separated) for          |                           |
188   |                        | portability.                   |                           |
189   |                        | Source files may be C, C++,    |                           |
190   |                        | SWIG (.i), platform-specific   |                           |
191   |                        | resource files, or whatever    |                           |
192   |                        | else is recognized by the      |                           |
193   |                        | :command:`build_ext` command   |                           |
194   |                        | as source for a Python         |                           |
195   |                        | extension.                     |                           |
196   +------------------------+--------------------------------+---------------------------+
197   | *include_dirs*         | list of directories to search  | a list of strings         |
198   |                        | for C/C++ header files (in     |                           |
199   |                        | Unix form for portability)     |                           |
200   +------------------------+--------------------------------+---------------------------+
201   | *define_macros*        | list of macros to define; each | a list of tuples          |
202   |                        | macro is defined using a       |                           |
203   |                        | 2-tuple ``(name, value)``,     |                           |
204   |                        | where *value* is               |                           |
205   |                        | either the string to define it |                           |
206   |                        | to or ``None`` to define it    |                           |
207   |                        | without a particular value     |                           |
208   |                        | (equivalent of ``#define FOO`` |                           |
209   |                        | in source or :option:`!-DFOO`  |                           |
210   |                        | on Unix C compiler command     |                           |
211   |                        | line)                          |                           |
212   +------------------------+--------------------------------+---------------------------+
213   | *undef_macros*         | list of macros to undefine     | a list of strings         |
214   |                        | explicitly                     |                           |
215   +------------------------+--------------------------------+---------------------------+
216   | *library_dirs*         | list of directories to search  | a list of strings         |
217   |                        | for C/C++ libraries at link    |                           |
218   |                        | time                           |                           |
219   +------------------------+--------------------------------+---------------------------+
220   | *libraries*            | list of library names (not     | a list of strings         |
221   |                        | filenames or paths) to link    |                           |
222   |                        | against                        |                           |
223   +------------------------+--------------------------------+---------------------------+
224   | *runtime_library_dirs* | list of directories to search  | a list of strings         |
225   |                        | for C/C++ libraries at run     |                           |
226   |                        | time (for shared extensions,   |                           |
227   |                        | this is when the extension is  |                           |
228   |                        | loaded)                        |                           |
229   +------------------------+--------------------------------+---------------------------+
230   | *extra_objects*        | list of extra files to link    | a list of strings         |
231   |                        | with (eg. object files not     |                           |
232   |                        | implied by 'sources', static   |                           |
233   |                        | library that must be           |                           |
234   |                        | explicitly specified, binary   |                           |
235   |                        | resource files, etc.)          |                           |
236   +------------------------+--------------------------------+---------------------------+
237   | *extra_compile_args*   | any extra platform- and        | a list of strings         |
238   |                        | compiler-specific information  |                           |
239   |                        | to use when compiling the      |                           |
240   |                        | source files in 'sources'. For |                           |
241   |                        | platforms and compilers where  |                           |
242   |                        | a command line makes sense,    |                           |
243   |                        | this is typically a list of    |                           |
244   |                        | command-line arguments, but    |                           |
245   |                        | for other platforms it could   |                           |
246   |                        | be anything.                   |                           |
247   +------------------------+--------------------------------+---------------------------+
248   | *extra_link_args*      | any extra platform- and        | a list of strings         |
249   |                        | compiler-specific information  |                           |
250   |                        | to use when linking object     |                           |
251   |                        | files together to create the   |                           |
252   |                        | extension (or to create a new  |                           |
253   |                        | static Python interpreter).    |                           |
254   |                        | Similar interpretation as for  |                           |
255   |                        | 'extra_compile_args'.          |                           |
256   +------------------------+--------------------------------+---------------------------+
257   | *export_symbols*       | list of symbols to be exported | a list of strings         |
258   |                        | from a shared extension. Not   |                           |
259   |                        | used on all platforms, and not |                           |
260   |                        | generally necessary for Python |                           |
261   |                        | extensions, which typically    |                           |
262   |                        | export exactly one symbol:     |                           |
263   |                        | ``init`` + extension_name.     |                           |
264   +------------------------+--------------------------------+---------------------------+
265   | *depends*              | list of files that the         | a list of strings         |
266   |                        | extension depends on           |                           |
267   +------------------------+--------------------------------+---------------------------+
268   | *language*             | extension language (i.e.       | a string                  |
269   |                        | ``'c'``, ``'c++'``,            |                           |
270   |                        | ``'objc'``). Will be detected  |                           |
271   |                        | from the source extensions if  |                           |
272   |                        | not provided.                  |                           |
273   +------------------------+--------------------------------+---------------------------+
274   | *optional*             | specifies that a build failure | a boolean                 |
275   |                        | in the extension should not    |                           |
276   |                        | abort the build process, but   |                           |
277   |                        | simply skip the extension.     |                           |
278   +------------------------+--------------------------------+---------------------------+
279
280
281.. class:: Distribution
282
283   A :class:`Distribution` describes how to build, install and package up a Python
284   software package.
285
286   See the :func:`setup` function for a list of keyword arguments accepted  by the
287   Distribution constructor. :func:`setup` creates a Distribution instance.
288
289   .. versionchanged:: 3.7
290      :class:`~distutils.core.Distribution` now warns if ``classifiers``,
291      ``keywords`` and ``platforms`` fields are not specified as a list or
292      a string.
293
294.. class:: Command
295
296   A :class:`Command` class (or rather, an instance of one of its subclasses)
297   implement a single distutils command.
298
299
300:mod:`distutils.ccompiler` --- CCompiler base class
301===================================================
302
303.. module:: distutils.ccompiler
304   :synopsis: Abstract CCompiler class
305
306
307This module provides the abstract base class for the :class:`CCompiler`
308classes.  A :class:`CCompiler` instance can be used for all the compile  and
309link steps needed to build a single project. Methods are provided to  set
310options for the compiler --- macro definitions, include directories,  link path,
311libraries and the like.
312
313This module provides the following functions.
314
315
316.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
317
318   Generate linker options for searching library directories and linking with
319   specific libraries.  *libraries* and *library_dirs* are, respectively, lists of
320   library names (not filenames!) and search directories.  Returns a list of
321   command-line options suitable for use with some compiler (depending on the two
322   format strings passed in).
323
324
325.. function:: gen_preprocess_options(macros, include_dirs)
326
327   Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as
328   used by at least two types of compilers: the typical Unix compiler and Visual
329   C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
330   means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define
331   (:option:`!-D`) macro *name* to *value*.  *include_dirs* is just a list of
332   directory names to be added to the header file search path (:option:`!-I`).
333   Returns a list of command-line options suitable for either Unix compilers or
334   Visual C++.
335
336
337.. function:: get_default_compiler(osname, platform)
338
339   Determine the default compiler to use for the given platform.
340
341   *osname* should be one of the standard Python OS names (i.e. the ones returned
342   by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
343   the platform in question.
344
345   The default values are ``os.name`` and ``sys.platform`` in case the parameters
346   are not given.
347
348
349.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
350
351   Factory function to generate an instance of some CCompiler subclass for the
352   supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
353   ``'posix'``, ``'nt'``), and *compiler*  defaults to the default compiler for
354   that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
355   default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
356   class) and Visual C++ (:class:`MSVCCompiler` class).  Note that it's perfectly
357   possible to ask for a Unix compiler object under Windows, and a Microsoft
358   compiler object under Unix---if you supply a value for *compiler*, *plat* is
359   ignored.
360
361   .. % Is the posix/nt only thing still true? Mac OS X seems to work, and
362   .. % returns a UnixCCompiler instance. How to document this... hmm.
363
364
365.. function:: show_compilers()
366
367   Print list of available compilers (used by the :option:`!--help-compiler` options
368   to :command:`build`, :command:`build_ext`, :command:`build_clib`).
369
370
371.. class:: CCompiler([verbose=0, dry_run=0, force=0])
372
373   The abstract base class :class:`CCompiler` defines the interface that  must be
374   implemented by real compiler classes.  The class also has  some utility methods
375   used by several compiler classes.
376
377   The basic idea behind a compiler abstraction class is that each instance can be
378   used for all the compile/link steps in building a single project.  Thus,
379   attributes common to all of those compile and link steps --- include
380   directories, macros to define, libraries to link against, etc. --- are
381   attributes of the compiler instance.  To allow for variability in how individual
382   files are treated, most of those attributes may be varied on a per-compilation
383   or per-link basis.
384
385   The constructor for each subclass creates an instance of the Compiler object.
386   Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
387   steps) and *force* (rebuild everything, regardless of dependencies). All of
388   these flags default to ``0`` (off). Note that you probably don't want to
389   instantiate :class:`CCompiler` or one of its subclasses directly - use the
390   :func:`distutils.CCompiler.new_compiler` factory function instead.
391
392   The following methods allow you to manually alter compiler options for  the
393   instance of the Compiler class.
394
395
396   .. method:: CCompiler.add_include_dir(dir)
397
398      Add *dir* to the list of directories that will be searched for header files.
399      The compiler is instructed to search directories in the order in which they are
400      supplied by successive calls to :meth:`add_include_dir`.
401
402
403   .. method:: CCompiler.set_include_dirs(dirs)
404
405      Set the list of directories that will be searched to *dirs* (a list of strings).
406      Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
407      :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
408      This does not affect any list of standard include directories that the compiler
409      may search by default.
410
411
412   .. method:: CCompiler.add_library(libname)
413
414      Add *libname* to the list of libraries that will be included in all links driven
415      by this compiler object.  Note that *libname* should \*not\* be the name of a
416      file containing a library, but the name of the library itself: the actual
417      filename will be inferred by the linker, the compiler, or the compiler class
418      (depending on the platform).
419
420      The linker will be instructed to link against libraries in the order they were
421      supplied to :meth:`add_library` and/or :meth:`set_libraries`.  It is perfectly
422      valid to duplicate library names; the linker will be instructed to link against
423      libraries as many times as they are mentioned.
424
425
426   .. method:: CCompiler.set_libraries(libnames)
427
428      Set the list of libraries to be included in all links driven by this compiler
429      object to *libnames* (a list of strings).  This does not affect any standard
430      system libraries that the linker may include by default.
431
432
433   .. method:: CCompiler.add_library_dir(dir)
434
435      Add *dir* to the list of directories that will be searched for libraries
436      specified to :meth:`add_library` and :meth:`set_libraries`.  The linker will be
437      instructed to search for libraries in the order they are supplied to
438      :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
439
440
441   .. method:: CCompiler.set_library_dirs(dirs)
442
443      Set the list of library search directories to *dirs* (a list of strings).  This
444      does not affect any standard library search path that the linker may search by
445      default.
446
447
448   .. method:: CCompiler.add_runtime_library_dir(dir)
449
450      Add *dir* to the list of directories that will be searched for shared libraries
451      at runtime.
452
453
454   .. method:: CCompiler.set_runtime_library_dirs(dirs)
455
456      Set the list of directories to search for shared libraries at runtime to *dirs*
457      (a list of strings).  This does not affect any standard search path that the
458      runtime linker may search by default.
459
460
461   .. method:: CCompiler.define_macro(name[, value=None])
462
463      Define a preprocessor macro for all compilations driven by this compiler object.
464      The optional parameter *value* should be a string; if it is not supplied, then
465      the macro will be defined without an explicit value and the exact outcome
466      depends on the compiler used.
467
468      .. XXX true? does ANSI say anything about this?
469
470
471   .. method:: CCompiler.undefine_macro(name)
472
473      Undefine a preprocessor macro for all compilations driven by this compiler
474      object.  If the same macro is defined by :meth:`define_macro` and
475      undefined by :meth:`undefine_macro` the last call takes precedence
476      (including multiple redefinitions or undefinitions).  If the macro is
477      redefined/undefined on a per-compilation basis (ie. in the call to
478      :meth:`compile`), then that takes precedence.
479
480
481   .. method:: CCompiler.add_link_object(object)
482
483      Add *object* to the list of object files (or analogues, such as explicitly named
484      library files or the output of "resource compilers") to be included in every
485      link driven by this compiler object.
486
487
488   .. method:: CCompiler.set_link_objects(objects)
489
490      Set the list of object files (or analogues) to be included in every link to
491      *objects*.  This does not affect any standard object files that the linker may
492      include by default (such as system libraries).
493
494   The following methods implement methods for autodetection of compiler  options,
495   providing some functionality similar to GNU :program:`autoconf`.
496
497
498   .. method:: CCompiler.detect_language(sources)
499
500      Detect the language of a given file, or list of files. Uses the  instance
501      attributes :attr:`language_map` (a dictionary), and  :attr:`language_order` (a
502      list) to do the job.
503
504
505   .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
506
507      Search the specified list of directories for a static or shared library file
508      *lib* and return the full path to that file.  If *debug* is true, look for a
509      debugging version (if that makes sense on the current platform).  Return
510      ``None`` if *lib* wasn't found in any of the specified directories.
511
512
513   .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
514
515      Return a boolean indicating whether *funcname* is supported on the current
516      platform.  The optional arguments can be used to augment the compilation
517      environment by providing additional include files and paths and libraries and
518      paths.
519
520
521   .. method:: CCompiler.library_dir_option(dir)
522
523      Return the compiler option to add *dir* to the list of directories searched for
524      libraries.
525
526
527   .. method:: CCompiler.library_option(lib)
528
529      Return the compiler option to add *lib* to the list of libraries linked into the
530      shared library or executable.
531
532
533   .. method:: CCompiler.runtime_library_dir_option(dir)
534
535      Return the compiler option to add *dir* to the list of directories searched for
536      runtime libraries.
537
538
539   .. method:: CCompiler.set_executables(**args)
540
541      Define the executables (and options for them) that will be run to perform the
542      various stages of compilation.  The exact set of executables that may be
543      specified here depends on the compiler class (via the 'executables' class
544      attribute), but most will have:
545
546      +--------------+------------------------------------------+
547      | attribute    | description                              |
548      +==============+==========================================+
549      | *compiler*   | the C/C++ compiler                       |
550      +--------------+------------------------------------------+
551      | *linker_so*  | linker used to create shared objects and |
552      |              | libraries                                |
553      +--------------+------------------------------------------+
554      | *linker_exe* | linker used to create binary executables |
555      +--------------+------------------------------------------+
556      | *archiver*   | static library creator                   |
557      +--------------+------------------------------------------+
558
559      On platforms with a command-line (Unix, DOS/Windows), each of these is a string
560      that will be split into executable name and (optional) list of arguments.
561      (Splitting the string is done similarly to how Unix shells operate: words are
562      delimited by spaces, but quotes and backslashes can override this.  See
563      :func:`distutils.util.split_quoted`.)
564
565   The following methods invoke stages in the build process.
566
567
568   .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
569
570      Compile one or more source files. Generates object files (e.g.  transforms a
571      :file:`.c` file to a :file:`.o` file.)
572
573      *sources* must be a list of filenames, most likely C/C++ files, but in reality
574      anything that can be handled by a particular compiler and compiler class (eg.
575      :class:`MSVCCompiler` can handle resource files in *sources*).  Return a list of
576      object filenames, one per source filename in *sources*.  Depending on the
577      implementation, not all source files will necessarily be compiled, but all
578      corresponding object filenames will be returned.
579
580      If *output_dir* is given, object files will be put under it, while retaining
581      their original path component.  That is, :file:`foo/bar.c` normally compiles to
582      :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
583      it would compile to :file:`build/foo/bar.o`.
584
585      *macros*, if given, must be a list of macro definitions.  A macro definition is
586      either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
587      a macro; if the value is ``None``, the macro is defined without an explicit
588      value.  The 1-tuple case undefines a macro.  Later
589      definitions/redefinitions/undefinitions take precedence.
590
591      *include_dirs*, if given, must be a list of strings, the directories to add to
592      the default include file search path for this compilation only.
593
594      *debug* is a boolean; if true, the compiler will be instructed to output debug
595      symbols in (or alongside) the object file(s).
596
597      *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
598      that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
599      likely lists of strings: extra command-line arguments to prepend/append to the
600      compiler command line.  On other platforms, consult the implementation class
601      documentation.  In any event, they are intended as an escape hatch for those
602      occasions when the abstract compiler framework doesn't cut the mustard.
603
604      *depends*, if given, is a list of filenames that all targets depend on.  If a
605      source file is older than any file in depends, then the source file will be
606      recompiled.  This supports dependency tracking, but only at a coarse
607      granularity.
608
609      Raises :exc:`CompileError` on failure.
610
611
612   .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
613
614      Link a bunch of stuff together to create a static library file. The "bunch of
615      stuff" consists of the list of object files supplied as *objects*, the extra
616      object files supplied to :meth:`add_link_object` and/or
617      :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
618      :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
619
620      *output_libname* should be a library name, not a filename; the filename will be
621      inferred from the library name.  *output_dir* is the directory where the library
622      file will be put.
623
624      .. XXX defaults to what?
625
626      *debug* is a boolean; if true, debugging information will be included in the
627      library (note that on most platforms, it is the compile step where this matters:
628      the *debug* flag is included here just for consistency).
629
630      *target_lang* is the target language for which the given objects are being
631      compiled. This allows specific linkage time treatment of certain languages.
632
633      Raises :exc:`LibError` on failure.
634
635
636   .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
637
638      Link a bunch of stuff together to create an executable or shared library file.
639
640      The "bunch of stuff" consists of the list of object files supplied as *objects*.
641      *output_filename* should be a filename.  If *output_dir* is supplied,
642      *output_filename* is relative to it (i.e. *output_filename* can provide
643      directory components if needed).
644
645      *libraries* is a list of libraries to link against.  These are library names,
646      not filenames, since they're translated into filenames in a platform-specific
647      way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
648      DOS/Windows).  However, they can include a directory component, which means the
649      linker will look in that specific directory rather than searching all the normal
650      locations.
651
652      *library_dirs*, if supplied, should be a list of directories to search for
653      libraries that were specified as bare library names (ie. no directory
654      component).  These are on top of the system default and those supplied to
655      :meth:`add_library_dir` and/or :meth:`set_library_dirs`.  *runtime_library_dirs*
656      is a list of directories that will be embedded into the shared library and used
657      to search for other shared libraries that \*it\* depends on at run-time.  (This
658      may only be relevant on Unix.)
659
660      *export_symbols* is a list of symbols that the shared library will export.
661      (This appears to be relevant only on Windows.)
662
663      *debug* is as for :meth:`compile` and :meth:`create_static_lib`,  with the
664      slight distinction that it actually matters on most platforms (as opposed to
665      :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
666      sake).
667
668      *extra_preargs* and *extra_postargs* are as for :meth:`compile`  (except of
669      course that they supply command-line arguments for the particular linker being
670      used).
671
672      *target_lang* is the target language for which the given objects are being
673      compiled. This allows specific linkage time treatment of certain languages.
674
675      Raises :exc:`LinkError` on failure.
676
677
678   .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
679
680      Link an executable.  *output_progname* is the name of the file executable, while
681      *objects* are a list of object filenames to link in. Other arguments  are as for
682      the :meth:`link` method.
683
684
685   .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
686
687      Link a shared library. *output_libname* is the name of the output  library,
688      while *objects* is a list of object filenames to link in.  Other arguments are
689      as for the :meth:`link` method.
690
691
692   .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
693
694      Link a shared object. *output_filename* is the name of the shared object that
695      will be created, while *objects* is a list of object filenames  to link in.
696      Other arguments are as for the :meth:`link` method.
697
698
699   .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
700
701      Preprocess a single C/C++ source file, named in *source*. Output will be written
702      to file named *output_file*, or *stdout* if *output_file* not supplied.
703      *macros* is a list of macro definitions as for :meth:`compile`, which will
704      augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
705      *include_dirs* is a list of directory names that will be added to the  default
706      list, in the same way as :meth:`add_include_dir`.
707
708      Raises :exc:`PreprocessError` on failure.
709
710   The following utility methods are defined by the :class:`CCompiler` class, for
711   use by the various concrete subclasses.
712
713
714   .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
715
716      Returns the filename of the executable for the given *basename*.  Typically for
717      non-Windows platforms this is the same as the basename,  while Windows will get
718      a :file:`.exe` added.
719
720
721   .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
722
723      Returns the filename for the given library name on the current platform. On Unix
724      a library with *lib_type* of ``'static'`` will typically  be of the form
725      :file:`liblibname.a`, while a *lib_type* of ``'dynamic'``  will be of the form
726      :file:`liblibname.so`.
727
728
729   .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
730
731      Returns the name of the object files for the given source files.
732      *source_filenames* should be a list of filenames.
733
734
735   .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
736
737      Returns the name of a shared object file for the given file name *basename*.
738
739
740   .. method:: CCompiler.execute(func, args[, msg=None, level=1])
741
742      Invokes :func:`distutils.util.execute`. This method invokes a  Python function
743      *func* with the given arguments *args*, after  logging and taking into account
744      the *dry_run* flag.
745
746
747   .. method:: CCompiler.spawn(cmd)
748
749      Invokes :func:`distutils.util.spawn`. This invokes an external  process to run
750      the given command.
751
752
753   .. method:: CCompiler.mkpath(name[, mode=511])
754
755      Invokes :func:`distutils.dir_util.mkpath`. This creates a directory  and any
756      missing ancestor directories.
757
758
759   .. method:: CCompiler.move_file(src, dst)
760
761      Invokes :meth:`distutils.file_util.move_file`. Renames *src* to  *dst*.
762
763
764   .. method:: CCompiler.announce(msg[, level=1])
765
766      Write a message using :func:`distutils.log.debug`.
767
768
769   .. method:: CCompiler.warn(msg)
770
771      Write a warning message *msg* to standard error.
772
773
774   .. method:: CCompiler.debug_print(msg)
775
776      If the *debug* flag is set on this :class:`CCompiler` instance, print  *msg* to
777      standard output, otherwise do nothing.
778
779.. % \subsection{Compiler-specific modules}
780.. %
781.. % The following modules implement concrete subclasses of the abstract
782.. % \class{CCompiler} class. They should not be instantiated directly, but should
783.. % be created using \function{distutils.ccompiler.new_compiler()} factory
784.. % function.
785
786
787:mod:`distutils.unixccompiler` --- Unix C Compiler
788==================================================
789
790.. module:: distutils.unixccompiler
791   :synopsis: UNIX C Compiler
792
793
794This module provides the :class:`UnixCCompiler` class, a subclass of
795:class:`CCompiler` that handles the typical Unix-style command-line  C compiler:
796
797* macros defined with :option:`!-Dname[=value]`
798
799* macros undefined with :option:`!-Uname`
800
801* include search directories specified with :option:`!-Idir`
802
803* libraries specified with :option:`!-llib`
804
805* library search directories specified with :option:`!-Ldir`
806
807* compile handled by :program:`cc` (or similar) executable with :option:`!-c`
808  option: compiles :file:`.c` to :file:`.o`
809
810* link static library handled by :program:`ar` command (possibly with
811  :program:`ranlib`)
812
813* link shared library handled by :program:`cc` :option:`!-shared`
814
815
816:mod:`distutils.msvccompiler` --- Microsoft Compiler
817====================================================
818
819.. module:: distutils.msvccompiler
820   :synopsis: Microsoft Compiler
821
822.. XXX: This is *waaaaay* out of date!
823
824This module provides :class:`MSVCCompiler`, an implementation of the abstract
825:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
826modules need to be compiled with the same compiler that was used to compile
827Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
8282.4 and 2.5, the compiler is Visual Studio .NET 2003.
829
830:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
831its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
832and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
833been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
834had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
835that the distutils user has made an explicit choice to override the compiler
836selection by :class:`MSVCCompiler`.
837
838
839:mod:`distutils.bcppcompiler` --- Borland Compiler
840==================================================
841
842.. module:: distutils.bcppcompiler
843
844
845This module provides :class:`BorlandCCompiler`, a subclass of the abstract
846:class:`CCompiler` class for the Borland C++ compiler.
847
848
849:mod:`distutils.cygwincompiler` --- Cygwin Compiler
850===================================================
851
852.. module:: distutils.cygwinccompiler
853
854
855This module provides the :class:`CygwinCCompiler` class, a subclass of
856:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
857Windows.  It also contains the Mingw32CCompiler class which handles the mingw32
858port of GCC (same as cygwin in no-cygwin mode).
859
860
861:mod:`distutils.archive_util` ---  Archiving utilities
862======================================================
863
864.. module:: distutils.archive_util
865   :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
866
867
868This module provides a few functions for creating archive files, such as
869tarballs or zipfiles.
870
871
872.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
873
874   Create an archive file (eg. ``zip`` or ``tar``).  *base_name*  is the name of
875   the file to create, minus any format-specific extension;  *format* is the
876   archive format: one of ``zip``, ``tar``, ``gztar``, ``bztar``, ``xztar``, or
877   ``ztar``. *root_dir* is a directory that will be the root directory of the
878   archive; ie. we typically ``chdir`` into *root_dir* before  creating the
879   archive.  *base_dir* is the directory where we start  archiving from; ie.
880   *base_dir* will be the common prefix of all files and directories in the
881   archive.  *root_dir* and *base_dir* both default to the current directory.
882   Returns the name of the archive file.
883
884   .. versionchanged:: 3.5
885      Added support for the ``xztar`` format.
886
887
888.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
889
890   'Create an (optional compressed) archive as a tar file from all files in and
891   under *base_dir*. *compress* must be ``'gzip'`` (the default),
892   ``'bzip2'``, ``'xz'``, ``'compress'``, or ``None``.  For the ``'compress'``
893   method the compression utility named by :program:`compress` must be on the
894   default program search path, so this is probably Unix-specific.  The output
895   tar file will be named :file:`base_dir.tar`, possibly plus the appropriate
896   compression extension (``.gz``, ``.bz2``, ``.xz`` or ``.Z``).  Return the
897   output filename.
898
899   .. versionchanged:: 3.5
900      Added support for the ``xz`` compression.
901
902
903.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
904
905   Create a zip file from all files in and under *base_dir*.  The output zip file
906   will be named *base_name* + :file:`.zip`.  Uses either the  :mod:`zipfile` Python
907   module (if available) or the InfoZIP :file:`zip`  utility (if installed and
908   found on the default search path).  If neither  tool is available, raises
909   :exc:`DistutilsExecError`.   Returns the name of the output zip file.
910
911
912:mod:`distutils.dep_util` --- Dependency checking
913=================================================
914
915.. module:: distutils.dep_util
916   :synopsis: Utility functions for simple dependency checking
917
918
919This module provides functions for performing simple, timestamp-based
920dependency of files and groups of files; also, functions based entirely  on such
921timestamp dependency analysis.
922
923
924.. function:: newer(source, target)
925
926   Return true if *source* exists and is more recently modified than *target*, or
927   if *source* exists and *target* doesn't. Return false if both exist and *target*
928   is the same age or newer  than *source*. Raise :exc:`DistutilsFileError` if
929   *source* does not exist.
930
931
932.. function:: newer_pairwise(sources, targets)
933
934   Walk two filename lists in parallel, testing if each source is newer than its
935   corresponding target.  Return a pair of lists (*sources*, *targets*) where
936   source is newer than target, according to the semantics of :func:`newer`.
937
938   .. % % equivalent to a listcomp...
939
940
941.. function:: newer_group(sources, target[, missing='error'])
942
943   Return true if *target* is out-of-date with respect to any file listed in
944   *sources*.  In other words, if *target* exists and is newer than every file in
945   *sources*, return false; otherwise return true. *missing* controls what we do
946   when a source file is missing; the default (``'error'``) is to blow up with an
947   :exc:`OSError` from  inside :func:`os.stat`; if it is ``'ignore'``, we silently
948   drop any missing source files; if it is ``'newer'``, any missing source files
949   make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
950   it'll make you pretend to carry out commands that wouldn't work because inputs
951   are missing, but that doesn't matter because you're not actually going to run
952   the commands).
953
954
955:mod:`distutils.dir_util` --- Directory tree operations
956=======================================================
957
958.. module:: distutils.dir_util
959   :synopsis: Utility functions for operating on directories and directory trees
960
961
962This module provides functions for operating on directories and trees of
963directories.
964
965
966.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0])
967
968   Create a directory and any missing ancestor directories.  If the directory
969   already exists (or if *name* is the empty string, which means the current
970   directory, which of course exists), then do nothing.  Raise
971   :exc:`DistutilsFileError` if unable to create some directory along the way (eg.
972   some sub-path exists, but is a file rather than a directory).  If *verbose* is
973   true, print a one-line summary of each mkdir to stdout.  Return the list of
974   directories actually created.
975
976
977.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])
978
979   Create all the empty directories under *base_dir* needed to put *files* there.
980   *base_dir* is just the name of a directory which doesn't necessarily exist
981   yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
982   *base_dir* + the directory portion of every file in *files* will be created if
983   it doesn't already exist.  *mode*, *verbose* and *dry_run* flags  are as for
984   :func:`mkpath`.
985
986
987.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
988
989   Copy an entire directory tree *src* to a new location *dst*.  Both *src* and
990   *dst* must be directory names.  If *src* is not a directory, raise
991   :exc:`DistutilsFileError`.  If *dst* does  not exist, it is created with
992   :func:`mkpath`.  The end result of the  copy is that every file in *src* is
993   copied to *dst*, and  directories under *src* are recursively copied to *dst*.
994   Return the list of files that were copied or might have been copied, using their
995   output name. The return value is unaffected by *update* or *dry_run*: it is
996   simply the list of all files under *src*, with the names changed to be under
997   *dst*.
998
999   *preserve_mode* and *preserve_times* are the same as for
1000   :func:`distutils.file_util.copy_file`; note that they only apply to
1001   regular files, not to
1002   directories.  If *preserve_symlinks* is true, symlinks will be copied as
1003   symlinks (on platforms that support them!); otherwise (the default), the
1004   destination of the symlink will be copied.  *update* and *verbose* are the same
1005   as for :func:`copy_file`.
1006
1007   Files in *src* that begin with :file:`.nfs` are skipped (more information on
1008   these files is available in answer D2 of the `NFS FAQ page
1009   <http://nfs.sourceforge.net/#section_d>`_).
1010
1011   .. versionchanged:: 3.3.1
1012      NFS files are ignored.
1013
1014.. function:: remove_tree(directory[, verbose=0, dry_run=0])
1015
1016   Recursively remove *directory* and all files and directories underneath it. Any
1017   errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
1018   true).
1019
1020
1021:mod:`distutils.file_util` --- Single file operations
1022=====================================================
1023
1024.. module:: distutils.file_util
1025   :synopsis: Utility functions for operating on single files
1026
1027
1028This module contains some utility functions for operating on individual files.
1029
1030
1031.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
1032
1033   Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
1034   with the same name; otherwise, it must be a filename. (If the file exists, it
1035   will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
1036   file's mode (type and permission bits, or whatever is analogous on the
1037   current platform) is copied. If *preserve_times* is true (the default), the
1038   last-modified and last-access times are copied as well. If *update* is true,
1039   *src* will only be copied if *dst* does not exist, or if *dst* does exist but
1040   is older than *src*.
1041
1042   *link* allows you to make hard links (using :func:`os.link`) or symbolic links
1043   (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
1044   ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
1045   on systems that don't support it: :func:`copy_file` doesn't check if hard or
1046   symbolic linking is available.  It uses :func:`_copy_file_contents` to copy file
1047   contents.
1048
1049   Return a tuple ``(dest_name, copied)``: *dest_name* is the actual  name of the
1050   output file, and *copied* is true if the file was copied  (or would have been
1051   copied, if *dry_run* true).
1052
1053   .. % XXX if the destination file already exists, we clobber it if
1054   .. % copying, but blow up if linking.  Hmmm.  And I don't know what
1055   .. % macostools.copyfile() does.  Should definitely be consistent, and
1056   .. % should probably blow up if destination exists and we would be
1057   .. % changing it (ie. it's not already a hard/soft link to src OR
1058   .. % (not update) and (src newer than dst)).
1059
1060
1061.. function:: move_file(src, dst[, verbose, dry_run])
1062
1063   Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
1064   it with the same name; otherwise, *src* is just renamed to *dst*.  Returns the
1065   new full name of the file.
1066
1067   .. warning::
1068
1069      Handles cross-device moves on Unix using :func:`copy_file`.  What about
1070      other systems?
1071
1072
1073.. function:: write_file(filename, contents)
1074
1075   Create a file called *filename* and write *contents* (a sequence of strings
1076   without line terminators) to it.
1077
1078
1079:mod:`distutils.util` --- Miscellaneous other utility functions
1080===============================================================
1081
1082.. module:: distutils.util
1083   :synopsis: Miscellaneous other utility functions
1084
1085
1086This module contains other assorted bits and pieces that don't fit into  any
1087other utility module.
1088
1089
1090.. function:: get_platform()
1091
1092   Return a string that identifies the current platform.  This is used mainly to
1093   distinguish platform-specific build directories and platform-specific built
1094   distributions.  Typically includes the OS name and version and the
1095   architecture (as supplied by 'os.uname()'), although the exact information
1096   included depends on the OS; e.g., on Linux, the kernel version isn't
1097   particularly important.
1098
1099   Examples of returned values:
1100
1101   * ``linux-i586``
1102   * ``linux-alpha``
1103   * ``solaris-2.6-sun4u``
1104
1105   For non-POSIX platforms, currently just returns ``sys.platform``.
1106
1107   For Mac OS X systems the OS version reflects the minimal version on which
1108   binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
1109   during the build of Python), not the OS version of the current system.
1110
1111   For universal binary builds on Mac OS X the architecture value reflects
1112   the universal binary status instead of the architecture of the current
1113   processor. For 32-bit universal binaries the architecture is ``fat``,
1114   for 64-bit universal binaries the architecture is ``fat64``, and
1115   for 4-way universal binaries the architecture is ``universal``. Starting
1116   from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
1117   a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
1118   a universal build with the i386 and x86_64 architectures
1119
1120   Examples of returned values on Mac OS X:
1121
1122   * ``macosx-10.3-ppc``
1123
1124   * ``macosx-10.3-fat``
1125
1126   * ``macosx-10.5-universal``
1127
1128   * ``macosx-10.6-intel``
1129
1130
1131.. function:: convert_path(pathname)
1132
1133   Return 'pathname' as a name that will work on the native filesystem, i.e. split
1134   it on '/' and put it back together again using the current directory separator.
1135   Needed because filenames in the setup script are always supplied in Unix style,
1136   and have to be converted to the local convention before we can actually use them
1137   in the filesystem.  Raises :exc:`ValueError` on non-Unix-ish systems if
1138   *pathname* either  starts or ends with a slash.
1139
1140
1141.. function:: change_root(new_root, pathname)
1142
1143   Return *pathname* with *new_root* prepended.  If *pathname* is relative, this is
1144   equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
1145   *pathname* relative and then joining the two, which is tricky on DOS/Windows.
1146
1147
1148.. function:: check_environ()
1149
1150   Ensure that 'os.environ' has all the environment variables we guarantee that
1151   users can use in config files, command-line options, etc.  Currently this
1152   includes:
1153
1154   * :envvar:`HOME` - user's home directory (Unix only)
1155   * :envvar:`PLAT` - description of the current platform, including hardware and
1156     OS (see :func:`get_platform`)
1157
1158
1159.. function:: subst_vars(s, local_vars)
1160
1161   Perform shell/Perl-style variable substitution on *s*.  Every occurrence of
1162   ``$`` followed by a name is considered a variable, and variable is substituted
1163   by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
1164   not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
1165   it contains certain values: see :func:`check_environ`.  Raise :exc:`ValueError`
1166   for any variables not found in either *local_vars* or ``os.environ``.
1167
1168   Note that this is not a fully-fledged string interpolation function. A valid
1169   ``$variable`` can consist only of upper and lower case letters, numbers and an
1170   underscore. No { } or ( ) style quoting is available.
1171
1172
1173.. function:: split_quoted(s)
1174
1175   Split a string up according to Unix shell-like rules for quotes and backslashes.
1176   In short: words are delimited by spaces, as long as those spaces are not escaped
1177   by a backslash, or inside a quoted string. Single and double quotes are
1178   equivalent, and the quote characters can be backslash-escaped.  The backslash is
1179   stripped from any two-character escape sequence, leaving only the escaped
1180   character.  The quote characters are stripped from any quoted string.  Returns a
1181   list of words.
1182
1183   .. % Should probably be moved into the standard library.
1184
1185
1186.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
1187
1188   Perform some action that affects the outside world (for instance, writing to the
1189   filesystem).  Such actions are special because they are disabled by the
1190   *dry_run* flag.  This method takes  care of all that bureaucracy for you; all
1191   you have to do is supply the function to call and an argument tuple for it (to
1192   embody the "external action" being performed), and an optional message to print.
1193
1194
1195.. function:: strtobool(val)
1196
1197   Convert a string representation of truth to true (1) or false (0).
1198
1199   True values are ``y``, ``yes``, ``t``, ``true``, ``on``  and ``1``; false values
1200   are ``n``, ``no``, ``f``, ``false``,  ``off`` and ``0``.  Raises
1201   :exc:`ValueError` if *val*  is anything else.
1202
1203
1204.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
1205
1206   Byte-compile a collection of Python source files to :file:`.pyc` files in a
1207   :file:`__pycache__` subdirectory (see :pep:`3147` and :pep:`488`).
1208   *py_files* is a list of files to compile; any files that don't end in
1209   :file:`.py` are silently skipped.  *optimize* must be one of the following:
1210
1211   * ``0`` - don't optimize
1212   * ``1`` - normal optimization (like ``python -O``)
1213   * ``2`` - extra optimization (like ``python -OO``)
1214
1215   If *force* is true, all files are recompiled regardless of timestamps.
1216
1217   The source filename encoded in each :term:`bytecode` file defaults to the filenames
1218   listed in *py_files*; you can modify these with *prefix* and *basedir*.
1219   *prefix* is a string that will be stripped off of each source filename, and
1220   *base_dir* is a directory name that will be prepended (after *prefix* is
1221   stripped).  You can supply either or both (or neither) of *prefix* and
1222   *base_dir*, as you wish.
1223
1224   If *dry_run* is true, doesn't actually do anything that would affect the
1225   filesystem.
1226
1227   Byte-compilation is either done directly in this interpreter process with the
1228   standard :mod:`py_compile` module, or indirectly by writing a temporary script
1229   and executing it.  Normally, you should let :func:`byte_compile` figure out to
1230   use direct compilation or not (see the source for details).  The *direct* flag
1231   is used by the script generated in indirect mode; unless you know what you're
1232   doing, leave it set to ``None``.
1233
1234   .. versionchanged:: 3.2.3
1235      Create ``.pyc`` files with an :func:`import magic tag
1236      <imp.get_tag>` in their name, in a :file:`__pycache__` subdirectory
1237      instead of files without tag in the current directory.
1238
1239   .. versionchanged:: 3.5
1240      Create ``.pyc`` files according to :pep:`488`.
1241
1242
1243.. function:: rfc822_escape(header)
1244
1245   Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
1246   ensuring there are 8 spaces space after each newline. Note that it does no other
1247   modification of the string.
1248
1249   .. % this _can_ be replaced
1250
1251.. % \subsection{Distutils objects}
1252
1253
1254:mod:`distutils.dist` --- The Distribution class
1255================================================
1256
1257.. module:: distutils.dist
1258   :synopsis: Provides the Distribution class, which represents the module distribution being
1259              built/installed/distributed
1260
1261
1262This module provides the :class:`~distutils.core.Distribution` class, which
1263represents the module distribution being built/installed/distributed.
1264
1265
1266:mod:`distutils.extension` --- The Extension class
1267==================================================
1268
1269.. module:: distutils.extension
1270   :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
1271              scripts
1272
1273
1274This module provides the :class:`Extension` class, used to describe C/C++
1275extension modules in setup scripts.
1276
1277.. % \subsection{Ungrouped modules}
1278.. % The following haven't been moved into a more appropriate section yet.
1279
1280
1281:mod:`distutils.debug` --- Distutils debug mode
1282===============================================
1283
1284.. module:: distutils.debug
1285   :synopsis: Provides the debug flag for distutils
1286
1287
1288This module provides the DEBUG flag.
1289
1290
1291:mod:`distutils.errors` --- Distutils exceptions
1292================================================
1293
1294.. module:: distutils.errors
1295   :synopsis: Provides standard distutils exceptions
1296
1297
1298Provides exceptions used by the Distutils modules.  Note that Distutils modules
1299may raise standard exceptions; in particular, SystemExit is usually raised for
1300errors that are obviously the end-user's fault (eg. bad command-line arguments).
1301
1302This module is safe to use in ``from ... import *`` mode; it only exports
1303symbols whose names start with ``Distutils`` and end with ``Error``.
1304
1305
1306:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
1307===========================================================================
1308
1309.. module:: distutils.fancy_getopt
1310   :synopsis: Additional getopt functionality
1311
1312
1313This module provides a wrapper around the standard :mod:`getopt`  module that
1314provides the following additional features:
1315
1316* short and long options are tied together
1317
1318* options have help strings, so :func:`fancy_getopt` could potentially  create a
1319  complete usage summary
1320
1321* options set attributes of a passed-in object
1322
1323* boolean options can have "negative aliases" --- eg. if :option:`!--quiet` is
1324  the "negative alias" of :option:`!--verbose`, then :option:`!--quiet` on the
1325  command line sets *verbose* to false.
1326
1327.. function:: fancy_getopt(options, negative_opt, object, args)
1328
1329   Wrapper function. *options* is a list of ``(long_option, short_option,
1330   help_string)`` 3-tuples as described in the constructor for
1331   :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
1332   to option names, both the key and value should be in the *options* list.
1333   *object* is an object which will be used to store values (see the :meth:`getopt`
1334   method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
1335   ``sys.argv[1:]`` if you  pass ``None`` as *args*.
1336
1337
1338.. function:: wrap_text(text, width)
1339
1340   Wraps *text* to less than *width* wide.
1341
1342
1343.. class:: FancyGetopt([option_table=None])
1344
1345   The option_table is a list of 3-tuples: ``(long_option, short_option,
1346   help_string)``
1347
1348   If an option takes an argument, its *long_option* should have ``'='`` appended;
1349   *short_option* should just be a single character, no ``':'`` in any case.
1350   *short_option* should be ``None`` if a *long_option*  doesn't have a
1351   corresponding *short_option*. All option tuples must have long options.
1352
1353The :class:`FancyGetopt` class provides the following methods:
1354
1355
1356.. method:: FancyGetopt.getopt([args=None, object=None])
1357
1358   Parse command-line options in args. Store as attributes on *object*.
1359
1360   If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``.  If *object* is
1361   ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
1362   option values there, and returns a tuple ``(args, object)``.  If *object* is
1363   supplied, it is modified in place and :func:`getopt` just returns *args*; in
1364   both cases, the returned *args* is a modified copy of the passed-in *args* list,
1365   which is left untouched.
1366
1367   .. % and args returned are?
1368
1369
1370.. method:: FancyGetopt.get_option_order()
1371
1372   Returns the list of ``(option, value)`` tuples processed by the previous run of
1373   :meth:`getopt`  Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
1374   yet.
1375
1376
1377.. method:: FancyGetopt.generate_help([header=None])
1378
1379   Generate help text (a list of strings, one per suggested line of output) from
1380   the option table for this :class:`FancyGetopt` object.
1381
1382   If supplied, prints the supplied *header* at the top of the help.
1383
1384
1385:mod:`distutils.filelist` --- The FileList class
1386================================================
1387
1388.. module:: distutils.filelist
1389   :synopsis: The FileList class, used for poking about the file system and
1390              building lists of files.
1391
1392
1393This module provides the :class:`FileList` class, used for poking about the
1394filesystem and building lists of files.
1395
1396
1397:mod:`distutils.log` --- Simple PEP 282-style logging
1398=====================================================
1399
1400.. module:: distutils.log
1401   :synopsis: A simple logging mechanism, 282-style
1402
1403
1404:mod:`distutils.spawn` --- Spawn a sub-process
1405==============================================
1406
1407.. module:: distutils.spawn
1408   :synopsis: Provides the spawn() function
1409
1410
1411This module provides the :func:`spawn` function, a front-end to  various
1412platform-specific functions for launching another program in a  sub-process.
1413Also provides :func:`find_executable` to search the path for a given executable
1414name.
1415
1416
1417:mod:`distutils.sysconfig` --- System configuration information
1418===============================================================
1419
1420.. module:: distutils.sysconfig
1421   :synopsis: Low-level access to configuration information of the Python interpreter.
1422.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1423.. moduleauthor:: Greg Ward <gward@python.net>
1424.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1425
1426
1427The :mod:`distutils.sysconfig` module provides access to Python's low-level
1428configuration information.  The specific configuration variables available
1429depend heavily on the platform and configuration. The specific variables depend
1430on the build process for the specific version of Python being run; the variables
1431are those found in the :file:`Makefile` and configuration header that are
1432installed with Python on Unix systems.  The configuration header is called
1433:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
1434for earlier versions of Python.
1435
1436Some additional functions are provided which perform some useful manipulations
1437for other parts of the :mod:`distutils` package.
1438
1439
1440.. data:: PREFIX
1441
1442   The result of ``os.path.normpath(sys.prefix)``.
1443
1444
1445.. data:: EXEC_PREFIX
1446
1447   The result of ``os.path.normpath(sys.exec_prefix)``.
1448
1449
1450.. function:: get_config_var(name)
1451
1452   Return the value of a single variable.  This is equivalent to
1453   ``get_config_vars().get(name)``.
1454
1455
1456.. function:: get_config_vars(...)
1457
1458   Return a set of variable definitions.  If there are no arguments, this returns a
1459   dictionary mapping names of configuration variables to values.  If arguments are
1460   provided, they should be strings, and the return value will be a sequence giving
1461   the associated values. If a given name does not have a corresponding value,
1462   ``None`` will be included for that variable.
1463
1464
1465.. function:: get_config_h_filename()
1466
1467   Return the full path name of the configuration header.  For Unix, this will be
1468   the header generated by the :program:`configure` script; for other platforms the
1469   header will have been supplied directly by the Python source distribution.  The
1470   file is a platform-specific text file.
1471
1472
1473.. function:: get_makefile_filename()
1474
1475   Return the full path name of the :file:`Makefile` used to build Python.  For
1476   Unix, this will be a file generated by the :program:`configure` script; the
1477   meaning for other platforms will vary.  The file is a platform-specific text
1478   file, if it exists. This function is only useful on POSIX platforms.
1479
1480
1481.. function:: get_python_inc([plat_specific[, prefix]])
1482
1483   Return the directory for either the general or platform-dependent C include
1484   files.  If *plat_specific* is true, the platform-dependent include directory is
1485   returned; if false or omitted, the platform-independent directory is returned.
1486   If *prefix* is given, it is used as either the prefix instead of
1487   :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1488   *plat_specific* is true.
1489
1490
1491.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
1492
1493   Return the directory for either the general or platform-dependent library
1494   installation.  If *plat_specific* is true, the platform-dependent include
1495   directory is returned; if false or omitted, the platform-independent directory
1496   is returned.  If *prefix* is given, it is used as either the prefix instead of
1497   :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1498   *plat_specific* is true.  If *standard_lib* is true, the directory for the
1499   standard library is returned rather than the directory for the installation of
1500   third-party extensions.
1501
1502The following function is only intended for use within the :mod:`distutils`
1503package.
1504
1505
1506.. function:: customize_compiler(compiler)
1507
1508   Do any platform-specific customization of a
1509   :class:`distutils.ccompiler.CCompiler` instance.
1510
1511   This function is only needed on Unix at this time, but should be called
1512   consistently to support forward-compatibility.  It inserts the information that
1513   varies across Unix flavors and is stored in Python's :file:`Makefile`.  This
1514   information includes the selected compiler, compiler and linker options, and the
1515   extension used by the linker for shared objects.
1516
1517This function is even more special-purpose, and should only be used from
1518Python's own build procedures.
1519
1520
1521.. function:: set_python_build()
1522
1523   Inform the :mod:`distutils.sysconfig` module that it is being used as part of
1524   the build process for Python.  This changes a lot of relative locations for
1525   files, allowing them to be located in the build area rather than in an installed
1526   Python.
1527
1528
1529:mod:`distutils.text_file` --- The TextFile class
1530=================================================
1531
1532.. module:: distutils.text_file
1533   :synopsis: provides the TextFile class, a simple interface to text files
1534
1535
1536This module provides the :class:`TextFile` class, which gives an interface  to
1537text files that (optionally) takes care of stripping comments, ignoring  blank
1538lines, and joining lines with backslashes.
1539
1540
1541.. class:: TextFile([filename=None, file=None, **options])
1542
1543   This class provides a file-like object that takes care of all  the things you
1544   commonly want to do when processing a text file  that has some line-by-line
1545   syntax: strip comments (as long as ``#``  is your comment character), skip blank
1546   lines, join adjacent lines by escaping the newline (ie. backslash at end of
1547   line), strip leading and/or trailing whitespace.  All of these are optional and
1548   independently controllable.
1549
1550   The class provides a :meth:`warn` method so you can generate  warning messages
1551   that report physical line number, even if the  logical line in question spans
1552   multiple physical lines.  Also  provides :meth:`unreadline` for implementing
1553   line-at-a-time lookahead.
1554
1555   :class:`TextFile` instances are create with either *filename*, *file*, or both.
1556   :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
1557   string, and *file* a file object (or something that provides :meth:`readline`
1558   and :meth:`close`  methods).  It is recommended that you supply at least
1559   *filename*,  so that :class:`TextFile` can include it in warning messages.  If
1560   *file* is not supplied, :class:`TextFile` creates its own using the
1561   :func:`open` built-in function.
1562
1563   The options are all boolean, and affect the values returned by :meth:`readline`
1564
1565   .. tabularcolumns:: |l|L|l|
1566
1567   +------------------+--------------------------------+---------+
1568   | option name      | description                    | default |
1569   +==================+================================+=========+
1570   | *strip_comments* | strip from ``'#'`` to          | true    |
1571   |                  | end-of-line, as well as any    |         |
1572   |                  | whitespace leading up to the   |         |
1573   |                  | ``'#'``\ ---unless it is       |         |
1574   |                  | escaped by a backslash         |         |
1575   +------------------+--------------------------------+---------+
1576   | *lstrip_ws*      | strip leading whitespace from  | false   |
1577   |                  | each line before returning it  |         |
1578   +------------------+--------------------------------+---------+
1579   | *rstrip_ws*      | strip trailing whitespace      | true    |
1580   |                  | (including line terminator!)   |         |
1581   |                  | from each line before          |         |
1582   |                  | returning it.                  |         |
1583   +------------------+--------------------------------+---------+
1584   | *skip_blanks*    | skip lines that are empty      | true    |
1585   |                  | \*after\* stripping comments   |         |
1586   |                  | and whitespace.  (If both      |         |
1587   |                  | lstrip_ws and rstrip_ws are    |         |
1588   |                  | false, then some lines may     |         |
1589   |                  | consist of solely whitespace:  |         |
1590   |                  | these will \*not\* be skipped, |         |
1591   |                  | even if *skip_blanks* is       |         |
1592   |                  | true.)                         |         |
1593   +------------------+--------------------------------+---------+
1594   | *join_lines*     | if a backslash is the last     | false   |
1595   |                  | non-newline character on a     |         |
1596   |                  | line after stripping comments  |         |
1597   |                  | and whitespace, join the       |         |
1598   |                  | following line to it to form   |         |
1599   |                  | one logical line; if N         |         |
1600   |                  | consecutive lines end with a   |         |
1601   |                  | backslash, then N+1 physical   |         |
1602   |                  | lines will be joined to form   |         |
1603   |                  | one logical line.              |         |
1604   +------------------+--------------------------------+---------+
1605   | *collapse_join*  | strip leading whitespace from  | false   |
1606   |                  | lines that are joined to their |         |
1607   |                  | predecessor; only matters if   |         |
1608   |                  | ``(join_lines and not          |         |
1609   |                  | lstrip_ws)``                   |         |
1610   +------------------+--------------------------------+---------+
1611
1612   Note that since *rstrip_ws* can strip the trailing newline, the semantics of
1613   :meth:`readline` must differ from those of the built-in file object's
1614   :meth:`readline` method!  In particular, :meth:`readline`  returns ``None`` for
1615   end-of-file: an empty string might just be a  blank line (or an all-whitespace
1616   line), if *rstrip_ws* is true  but *skip_blanks* is not.
1617
1618
1619   .. method:: TextFile.open(filename)
1620
1621      Open a new file *filename*.  This overrides any *file* or *filename*
1622      constructor arguments.
1623
1624
1625   .. method:: TextFile.close()
1626
1627      Close the current file and forget everything we know about it (including the
1628      filename and the current line number).
1629
1630
1631   .. method:: TextFile.warn(msg[,line=None])
1632
1633      Print (to stderr) a warning message tied to the current logical line in the
1634      current file.  If the current logical line in the file spans multiple physical
1635      lines, the warning refers to the whole range, such as ``"lines 3-5"``.  If
1636      *line* is supplied,  it overrides the current line number; it may be a list or
1637      tuple  to indicate a range of physical lines, or an integer for a  single
1638      physical line.
1639
1640
1641   .. method:: TextFile.readline()
1642
1643      Read and return a single logical line from the current file (or from an internal
1644      buffer if lines have previously been "unread" with :meth:`unreadline`).  If the
1645      *join_lines* option  is true, this may involve reading multiple physical lines
1646      concatenated into a single string.  Updates the current line number,  so calling
1647      :meth:`warn` after :meth:`readline` emits a warning  about the physical line(s)
1648      just read.  Returns ``None`` on end-of-file,  since the empty string can occur
1649      if *rstrip_ws* is true but  *strip_blanks* is not.
1650
1651
1652   .. method:: TextFile.readlines()
1653
1654      Read and return the list of all logical lines remaining in the current file.
1655      This updates the current line number to the last line of the file.
1656
1657
1658   .. method:: TextFile.unreadline(line)
1659
1660      Push *line* (a string) onto an internal buffer that will be checked by future
1661      :meth:`readline` calls.  Handy for implementing a parser with line-at-a-time
1662      lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
1663      subsequently re-cleansed (whitespace  stripped, or whatever) when read with
1664      :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
1665      to :meth:`readline`, the lines will be returned most in most recent first order.
1666
1667
1668:mod:`distutils.version` --- Version number classes
1669===================================================
1670
1671.. module:: distutils.version
1672   :synopsis: implements classes that represent module version numbers.
1673
1674
1675.. % todo
1676.. % \section{Distutils Commands}
1677.. %
1678.. % This part of Distutils implements the various Distutils commands, such
1679.. % as \code{build}, \code{install} \&c. Each command is implemented as a
1680.. % separate module, with the command name as the name of the module.
1681
1682
1683:mod:`distutils.cmd` --- Abstract base class for Distutils commands
1684===================================================================
1685
1686.. module:: distutils.cmd
1687   :synopsis: This module provides the abstract base class Command. This class
1688              is subclassed by the modules in the distutils.command subpackage.
1689
1690
1691This module supplies the abstract base class :class:`Command`.
1692
1693
1694.. class:: Command(dist)
1695
1696   Abstract base class for defining command classes, the "worker bees" of the
1697   Distutils.  A useful analogy for command classes is to think of them as
1698   subroutines with local variables called *options*.  The options are declared
1699   in :meth:`initialize_options` and defined (given their final values) in
1700   :meth:`finalize_options`, both of which must be defined by every command
1701   class.  The distinction between the two is necessary because option values
1702   might come from the outside world (command line, config file, ...), and any
1703   options dependent on other options must be computed after these outside
1704   influences have been processed --- hence :meth:`finalize_options`.  The body
1705   of the subroutine, where it does all its work based on the values of its
1706   options, is the :meth:`run` method, which must also be implemented by every
1707   command class.
1708
1709   The class constructor takes a single argument *dist*, a
1710   :class:`~distutils.core.Distribution` instance.
1711
1712
1713Creating a new Distutils command
1714================================
1715
1716This section outlines the steps to create a new Distutils command.
1717
1718A new command lives in a module in the :mod:`distutils.command` package. There
1719is a sample template in that directory called :file:`command_template`.  Copy
1720this file to a new module with the same name as the new command you're
1721implementing.  This module should implement a class with the same name as the
1722module (and the command).  So, for instance, to create the command
1723``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
1724:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
1725it so that it's implementing the class :class:`peel_banana`, a subclass of
1726:class:`distutils.cmd.Command`.
1727
1728Subclasses of :class:`Command` must define the following methods.
1729
1730.. method:: Command.initialize_options()
1731
1732   Set default values for all the options that this command supports.  Note that
1733   these defaults may be overridden by other commands, by the setup script, by
1734   config files, or by the command-line.  Thus, this is not the place to code
1735   dependencies between options; generally, :meth:`initialize_options`
1736   implementations are just a bunch of ``self.foo = None`` assignments.
1737
1738
1739.. method:: Command.finalize_options()
1740
1741   Set final values for all the options that this command supports. This is
1742   always called as late as possible, ie.  after any option assignments from the
1743   command-line or from other commands have been done.  Thus, this is the place
1744   to code option dependencies: if *foo* depends on *bar*, then it is safe to
1745   set *foo* from *bar* as long as *foo* still has the same value it was
1746   assigned in :meth:`initialize_options`.
1747
1748
1749.. method:: Command.run()
1750
1751   A command's raison d'etre: carry out the action it exists to perform, controlled
1752   by the options initialized in :meth:`initialize_options`, customized by other
1753   commands, the setup script, the command-line, and config files, and finalized in
1754   :meth:`finalize_options`.  All terminal output and filesystem interaction should
1755   be done by :meth:`run`.
1756
1757
1758.. attribute:: Command.sub_commands
1759
1760   *sub_commands* formalizes the notion of a "family" of commands,
1761   e.g. ``install`` as the parent with sub-commands ``install_lib``,
1762   ``install_headers``, etc.  The parent of a family of commands defines
1763   *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
1764   predicate)``, with *command_name* a string and *predicate* a function, a
1765   string or ``None``.  *predicate* is a method of the parent command that
1766   determines whether the corresponding command is applicable in the current
1767   situation.  (E.g. ``install_headers`` is only applicable if we have any C
1768   header files to install.)  If *predicate* is ``None``, that command is always
1769   applicable.
1770
1771   *sub_commands* is usually defined at the *end* of a class, because
1772   predicates can be methods of the class, so they must already have been
1773   defined.  The canonical example is the :command:`install` command.
1774
1775
1776:mod:`distutils.command` --- Individual Distutils commands
1777==========================================================
1778
1779.. module:: distutils.command
1780   :synopsis: This subpackage contains one module for each standard Distutils command.
1781
1782
1783.. % \subsubsection{Individual Distutils commands}
1784.. % todo
1785
1786
1787:mod:`distutils.command.bdist` --- Build a binary installer
1788===========================================================
1789
1790.. module:: distutils.command.bdist
1791   :synopsis: Build a binary installer for a package
1792
1793
1794.. % todo
1795
1796
1797:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
1798=============================================================================
1799
1800.. module:: distutils.command.bdist_packager
1801   :synopsis: Abstract base class for packagers
1802
1803
1804.. % todo
1805
1806
1807:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
1808================================================================
1809
1810.. module:: distutils.command.bdist_dumb
1811   :synopsis: Build a "dumb" installer - a simple archive of files
1812
1813
1814.. % todo
1815
1816
1817:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
1818=================================================================================
1819
1820.. module:: distutils.command.bdist_msi
1821   :synopsis: Build a binary distribution as a Windows MSI file
1822
1823.. class:: bdist_msi
1824
1825   Builds a `Windows Installer`_ (.msi) binary package.
1826
1827   .. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
1828
1829   In most cases, the ``bdist_msi`` installer is a better choice than the
1830   ``bdist_wininst`` installer, because it provides better support for
1831   Win64 platforms, allows administrators to perform non-interactive
1832   installations, and allows installation through group policies.
1833
1834
1835:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
1836===========================================================================================
1837
1838.. module:: distutils.command.bdist_rpm
1839   :synopsis: Build a binary distribution as a Redhat RPM and SRPM
1840
1841
1842.. % todo
1843
1844
1845:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
1846====================================================================
1847
1848.. module:: distutils.command.bdist_wininst
1849   :synopsis: Build a Windows installer
1850
1851
1852.. % todo
1853
1854
1855:mod:`distutils.command.sdist` --- Build a source distribution
1856==============================================================
1857
1858.. module:: distutils.command.sdist
1859   :synopsis: Build a source distribution
1860
1861
1862.. % todo
1863
1864
1865:mod:`distutils.command.build` --- Build all files of a package
1866===============================================================
1867
1868.. module:: distutils.command.build
1869   :synopsis: Build all files of a package
1870
1871
1872.. % todo
1873
1874
1875:mod:`distutils.command.build_clib` --- Build any C libraries in a package
1876==========================================================================
1877
1878.. module:: distutils.command.build_clib
1879   :synopsis: Build any C libraries in a package
1880
1881
1882.. % todo
1883
1884
1885:mod:`distutils.command.build_ext` --- Build any extensions in a package
1886========================================================================
1887
1888.. module:: distutils.command.build_ext
1889   :synopsis: Build any extensions in a package
1890
1891
1892.. % todo
1893
1894
1895:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
1896===========================================================================
1897
1898.. module:: distutils.command.build_py
1899   :synopsis: Build the .py/.pyc files of a package
1900
1901
1902.. class:: build_py
1903
1904.. class:: build_py_2to3
1905
1906   Alternative implementation of build_py which also runs the
1907   2to3 conversion library on each .py file that is going to be
1908   installed. To use this in a setup.py file for a distribution
1909   that is designed to run with both Python 2.x and 3.x, add::
1910
1911     try:
1912         from distutils.command.build_py import build_py_2to3 as build_py
1913     except ImportError:
1914         from distutils.command.build_py import build_py
1915
1916   to your setup.py, and later::
1917
1918      cmdclass = {'build_py': build_py}
1919
1920   to the invocation of setup().
1921
1922
1923:mod:`distutils.command.build_scripts` --- Build the scripts of a package
1924=========================================================================
1925
1926.. module:: distutils.command.build_scripts
1927   :synopsis: Build the scripts of a package
1928
1929
1930.. % todo
1931
1932
1933:mod:`distutils.command.clean` --- Clean a package build area
1934=============================================================
1935
1936.. module:: distutils.command.clean
1937   :synopsis: Clean a package build area
1938
1939This command removes the temporary files created by :command:`build`
1940and its subcommands, like intermediary compiled object files.  With
1941the ``--all`` option, the complete build directory will be removed.
1942
1943Extension modules built :ref:`in place <distutils-build-ext-inplace>`
1944will not be cleaned, as they are not in the build directory.
1945
1946
1947:mod:`distutils.command.config` --- Perform package configuration
1948=================================================================
1949
1950.. module:: distutils.command.config
1951   :synopsis: Perform package configuration
1952
1953
1954.. % todo
1955
1956
1957:mod:`distutils.command.install` --- Install a package
1958======================================================
1959
1960.. module:: distutils.command.install
1961   :synopsis: Install a package
1962
1963
1964.. % todo
1965
1966
1967:mod:`distutils.command.install_data` --- Install data files from a package
1968===========================================================================
1969
1970.. module:: distutils.command.install_data
1971   :synopsis: Install data files from a package
1972
1973
1974.. % todo
1975
1976
1977:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
1978======================================================================================
1979
1980.. module:: distutils.command.install_headers
1981   :synopsis: Install C/C++ header files from a package
1982
1983
1984.. % todo
1985
1986
1987:mod:`distutils.command.install_lib` --- Install library files from a package
1988=============================================================================
1989
1990.. module:: distutils.command.install_lib
1991   :synopsis: Install library files from a package
1992
1993
1994.. % todo
1995
1996
1997:mod:`distutils.command.install_scripts` --- Install script files from a package
1998================================================================================
1999
2000.. module:: distutils.command.install_scripts
2001   :synopsis: Install script files from a package
2002
2003
2004.. % todo
2005
2006
2007:mod:`distutils.command.register` --- Register a module with the Python Package Index
2008=====================================================================================
2009
2010.. module:: distutils.command.register
2011   :synopsis: Register a module with the Python Package Index
2012
2013
2014The ``register`` command registers the package with the Python Package  Index.
2015This is described in more detail in :pep:`301`.
2016
2017.. % todo
2018
2019
2020:mod:`distutils.command.check` --- Check the meta-data of a package
2021===================================================================
2022
2023.. module:: distutils.command.check
2024   :synopsis: Check the metadata of a package
2025
2026
2027The ``check`` command performs some tests on the meta-data of a package.
2028For example, it verifies that all required meta-data are provided as
2029the arguments passed to the :func:`setup` function.
2030
2031.. % todo
2032