| blob | fa285161676424c2d7062e2495000f061e4751ca |
1 .. _api-reference:
3 *************
4 API Reference
5 *************
8 :mod:`distutils.core` --- Core Distutils functionality
9 ======================================================
11 .. module:: distutils.core
12 :synopsis: The core Distutils functionality
15 The :mod:`distutils.core` module is the only module that needs to be installed
16 to use the Distutils. It provides the :func:`setup` (which is called from the
17 setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
18 :class:`distutils.cmd.Command` class.
21 .. function:: setup(arguments)
23 The basic do-everything function that does most everything you could ever ask
24 for from a Distutils method. See XXXXX
26 The setup function takes a large number of arguments. These are laid out in the
27 following table.
29 +--------------------+--------------------------------+-------------------------------------------------------------+
30 | argument name | value | type |
31 +====================+================================+=============================================================+
32 | *name* | The name of the package | a string |
33 +--------------------+--------------------------------+-------------------------------------------------------------+
34 | *version* | The version number of the | See :mod:`distutils.version` |
35 | | package | |
36 +--------------------+--------------------------------+-------------------------------------------------------------+
37 | *description* | A single line describing the | a string |
38 | | package | |
39 +--------------------+--------------------------------+-------------------------------------------------------------+
40 | *long_description* | Longer description of the | a string |
41 | | package | |
42 +--------------------+--------------------------------+-------------------------------------------------------------+
43 | *author* | The name of the package author | a string |
44 +--------------------+--------------------------------+-------------------------------------------------------------+
45 | *author_email* | The email address of the | a string |
46 | | package author | |
47 +--------------------+--------------------------------+-------------------------------------------------------------+
48 | *maintainer* | The name of the current | a string |
49 | | maintainer, if different from | |
50 | | the author | |
51 +--------------------+--------------------------------+-------------------------------------------------------------+
52 | *maintainer_email* | The email address of the | |
53 | | current maintainer, if | |
54 | | different from the author | |
55 +--------------------+--------------------------------+-------------------------------------------------------------+
56 | *url* | A URL for the package | a URL |
57 | | (homepage) | |
58 +--------------------+--------------------------------+-------------------------------------------------------------+
59 | *download_url* | A URL to download the package | a URL |
60 +--------------------+--------------------------------+-------------------------------------------------------------+
61 | *packages* | A list of Python packages that | a list of strings |
62 | | distutils will manipulate | |
63 +--------------------+--------------------------------+-------------------------------------------------------------+
64 | *py_modules* | A list of Python modules that | a list of strings |
65 | | distutils will manipulate | |
66 +--------------------+--------------------------------+-------------------------------------------------------------+
67 | *scripts* | A list of standalone script | a list of strings |
68 | | files to be built and | |
69 | | installed | |
70 +--------------------+--------------------------------+-------------------------------------------------------------+
71 | *ext_modules* | A list of Python extensions to | A list of instances of |
72 | | be built | :class:`distutils.core.Extension` |
73 +--------------------+--------------------------------+-------------------------------------------------------------+
74 | *classifiers* | A list of categories for the | The list of available |
75 | | package | categorizations is at |
76 | | | http://pypi.python.org/pypi?:action=list_classifiers. |
77 +--------------------+--------------------------------+-------------------------------------------------------------+
78 | *distclass* | the :class:`Distribution` | A subclass of |
79 | | class to use | :class:`distutils.core.Distribution` |
80 +--------------------+--------------------------------+-------------------------------------------------------------+
81 | *script_name* | The name of the setup.py | a string |
82 | | script - defaults to | |
83 | | ``sys.argv[0]`` | |
84 +--------------------+--------------------------------+-------------------------------------------------------------+
85 | *script_args* | Arguments to supply to the | a list of strings |
86 | | setup script | |
87 +--------------------+--------------------------------+-------------------------------------------------------------+
88 | *options* | default options for the setup | a string |
89 | | script | |
90 +--------------------+--------------------------------+-------------------------------------------------------------+
91 | *license* | The license for the package | a string |
92 +--------------------+--------------------------------+-------------------------------------------------------------+
93 | *keywords* | Descriptive meta-data, see | |
94 | | :pep:`314` | |
95 +--------------------+--------------------------------+-------------------------------------------------------------+
96 | *platforms* | | |
97 +--------------------+--------------------------------+-------------------------------------------------------------+
98 | *cmdclass* | A mapping of command names to | a dictionary |
99 | | :class:`Command` subclasses | |
100 +--------------------+--------------------------------+-------------------------------------------------------------+
101 | *data_files* | A list of data files to | a list |
102 | | install | |
103 +--------------------+--------------------------------+-------------------------------------------------------------+
104 | *package_dir* | A mapping of package to | a dictionary |
105 | | directory names | |
106 +--------------------+--------------------------------+-------------------------------------------------------------+
110 .. function:: run_setup(script_name[, script_args=None, stop_after='run'])
112 Run a setup script in a somewhat controlled environment, and return the
113 :class:`distutils.dist.Distribution` instance that drives things. This is
114 useful if you need to find out the distribution meta-data (passed as keyword
115 args from *script* to :func:`setup`), or the contents of the config files or
116 command-line.
118 *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]``
119 will be replaced with *script* for the duration of the call. *script_args* is a
120 list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
121 for the duration of the call.
123 *stop_after* tells :func:`setup` when to stop processing; possible values:
125 +---------------+---------------------------------------------+
126 | value | description |
127 +===============+=============================================+
128 | *init* | Stop after the :class:`Distribution` |
129 | | instance has been created and populated |
130 | | with the keyword arguments to :func:`setup` |
131 +---------------+---------------------------------------------+
132 | *config* | Stop after config files have been parsed |
133 | | (and their data stored in the |
134 | | :class:`Distribution` instance) |
135 +---------------+---------------------------------------------+
136 | *commandline* | Stop after the command-line |
137 | | (``sys.argv[1:]`` or *script_args*) have |
138 | | been parsed (and the data stored in the |
139 | | :class:`Distribution` instance.) |
140 +---------------+---------------------------------------------+
141 | *run* | Stop after all commands have been run (the |
142 | | same as if :func:`setup` had been called |
143 | | in the usual way). This is the default |
144 | | value. |
145 +---------------+---------------------------------------------+
147 In addition, the :mod:`distutils.core` module exposed a number of classes that
148 live elsewhere.
150 * :class:`Extension` from :mod:`distutils.extension`
152 * :class:`Command` from :mod:`distutils.cmd`
154 * :class:`Distribution` from :mod:`distutils.dist`
156 A short description of each of these follows, but see the relevant module for
157 the full reference.
160 .. class:: Extension
162 The Extension class describes a single C or C++extension module in a setup
163 script. It accepts the following keyword arguments in its constructor
165 +------------------------+--------------------------------+---------------------------+
166 | argument name | value | type |
167 +========================+================================+===========================+
168 | *name* | the full name of the | string |
169 | | extension, including any | |
170 | | packages --- ie. *not* a | |
171 | | filename or pathname, but | |
172 | | Python dotted name | |
173 +------------------------+--------------------------------+---------------------------+
174 | *sources* | list of source filenames, | string |
175 | | relative to the distribution | |
176 | | root (where the setup script | |
177 | | lives), in Unix form (slash- | |
178 | | separated) for portability. | |
179 | | Source files may be C, C++, | |
180 | | SWIG (.i), platform-specific | |
181 | | resource files, or whatever | |
182 | | else is recognized by the | |
183 | | :command:`build_ext` command | |
184 | | as source for a Python | |
185 | | extension. | |
186 +------------------------+--------------------------------+---------------------------+
187 | *include_dirs* | list of directories to search | string |
188 | | for C/C++ header files (in | |
189 | | Unix form for portability) | |
190 +------------------------+--------------------------------+---------------------------+
191 | *define_macros* | list of macros to define; each | (string, string) tuple or |
192 | | macro is defined using a | (name, ``None``) |
193 | | 2-tuple ``(name, value)``, | |
194 | | where *value* is | |
195 | | either the string to define it | |
196 | | to or ``None`` to define it | |
197 | | without a particular value | |
198 | | (equivalent of ``#define FOO`` | |
199 | | in source or :option:`-DFOO` | |
200 | | on Unix C compiler command | |
201 | | line) | |
202 +------------------------+--------------------------------+---------------------------+
203 | *undef_macros* | list of macros to undefine | string |
204 | | explicitly | |
205 +------------------------+--------------------------------+---------------------------+
206 | *library_dirs* | list of directories to search | string |
207 | | for C/C++ libraries at link | |
208 | | time | |
209 +------------------------+--------------------------------+---------------------------+
210 | *libraries* | list of library names (not | string |
211 | | filenames or paths) to link | |
212 | | against | |
213 +------------------------+--------------------------------+---------------------------+
214 | *runtime_library_dirs* | list of directories to search | string |
215 | | for C/C++ libraries at run | |
216 | | time (for shared extensions, | |
217 | | this is when the extension is | |
218 | | loaded) | |
219 +------------------------+--------------------------------+---------------------------+
220 | *extra_objects* | list of extra files to link | string |
221 | | with (eg. object files not | |
222 | | implied by 'sources', static | |
223 | | library that must be | |
224 | | explicitly specified, binary | |
225 | | resource files, etc.) | |
226 +------------------------+--------------------------------+---------------------------+
227 | *extra_compile_args* | any extra platform- and | string |
228 | | compiler-specific information | |
229 | | to use when compiling the | |
230 | | source files in 'sources'. For | |
231 | | platforms and compilers where | |
232 | | a command line makes sense, | |
233 | | this is typically a list of | |
234 | | command-line arguments, but | |
235 | | for other platforms it could | |
236 | | be anything. | |
237 +------------------------+--------------------------------+---------------------------+
238 | *extra_link_args* | any extra platform- and | string |
239 | | compiler-specific information | |
240 | | to use when linking object | |
241 | | files together to create the | |
242 | | extension (or to create a new | |
243 | | static Python interpreter). | |
244 | | Similar interpretation as for | |
245 | | 'extra_compile_args'. | |
246 +------------------------+--------------------------------+---------------------------+
247 | *export_symbols* | list of symbols to be exported | string |
248 | | from a shared extension. Not | |
249 | | used on all platforms, and not | |
250 | | generally necessary for Python | |
251 | | extensions, which typically | |
252 | | export exactly one symbol: | |
253 | | ``init`` + extension_name. | |
254 +------------------------+--------------------------------+---------------------------+
255 | *depends* | list of files that the | string |
256 | | extension depends on | |
257 +------------------------+--------------------------------+---------------------------+
258 | *language* | extension language (i.e. | string |
259 | | ``'c'``, ``'c++'``, | |
260 | | ``'objc'``). Will be detected | |
261 | | from the source extensions if | |
262 | | not provided. | |
263 +------------------------+--------------------------------+---------------------------+
266 .. class:: Distribution
268 A :class:`Distribution` describes how to build, install and package up a Python
269 software package.
271 See the :func:`setup` function for a list of keyword arguments accepted by the
272 Distribution constructor. :func:`setup` creates a Distribution instance.
275 .. class:: Command
277 A :class:`Command` class (or rather, an instance of one of its subclasses)
278 implement a single distutils command.
281 :mod:`distutils.ccompiler` --- CCompiler base class
282 ===================================================
284 .. module:: distutils.ccompiler
285 :synopsis: Abstract CCompiler class
288 This module provides the abstract base class for the :class:`CCompiler`
289 classes. A :class:`CCompiler` instance can be used for all the compile and
290 link steps needed to build a single project. Methods are provided to set
291 options for the compiler --- macro definitions, include directories, link path,
292 libraries and the like.
294 This module provides the following functions.
297 .. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
299 Generate linker options for searching library directories and linking with
300 specific libraries. *libraries* and *library_dirs* are, respectively, lists of
301 library names (not filenames!) and search directories. Returns a list of
302 command-line options suitable for use with some compiler (depending on the two
303 format strings passed in).
306 .. function:: gen_preprocess_options(macros, include_dirs)
308 Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as
309 used by at least two types of compilers: the typical Unix compiler and Visual
310 C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
311 means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define
312 (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of
313 directory names to be added to the header file search path (:option:`-I`).
314 Returns a list of command-line options suitable for either Unix compilers or
315 Visual C++.
318 .. function:: get_default_compiler(osname, platform)
320 Determine the default compiler to use for the given platform.
322 *osname* should be one of the standard Python OS names (i.e. the ones returned
323 by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
324 the platform in question.
326 The default values are ``os.name`` and ``sys.platform`` in case the parameters
327 are not given.
330 .. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
332 Factory function to generate an instance of some CCompiler subclass for the
333 supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
334 ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for
335 that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
336 default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
337 class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly
338 possible to ask for a Unix compiler object under Windows, and a Microsoft
339 compiler object under Unix---if you supply a value for *compiler*, *plat* is
340 ignored.
342 .. % Is the posix/nt only thing still true? Mac OS X seems to work, and
343 .. % returns a UnixCCompiler instance. How to document this... hmm.
346 .. function:: show_compilers()
348 Print list of available compilers (used by the :option:`--help-compiler` options
349 to :command:`build`, :command:`build_ext`, :command:`build_clib`).
352 .. class:: CCompiler([verbose=0, dry_run=0, force=0])
354 The abstract base class :class:`CCompiler` defines the interface that must be
355 implemented by real compiler classes. The class also has some utility methods
356 used by several compiler classes.
358 The basic idea behind a compiler abstraction class is that each instance can be
359 used for all the compile/link steps in building a single project. Thus,
360 attributes common to all of those compile and link steps --- include
361 directories, macros to define, libraries to link against, etc. --- are
362 attributes of the compiler instance. To allow for variability in how individual
363 files are treated, most of those attributes may be varied on a per-compilation
364 or per-link basis.
366 The constructor for each subclass creates an instance of the Compiler object.
367 Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
368 steps) and *force* (rebuild everything, regardless of dependencies). All of
369 these flags default to ``0`` (off). Note that you probably don't want to
370 instantiate :class:`CCompiler` or one of its subclasses directly - use the
371 :func:`distutils.CCompiler.new_compiler` factory function instead.
373 The following methods allow you to manually alter compiler options for the
374 instance of the Compiler class.
377 .. method:: CCompiler.add_include_dir(dir)
379 Add *dir* to the list of directories that will be searched for header files.
380 The compiler is instructed to search directories in the order in which they are
381 supplied by successive calls to :meth:`add_include_dir`.
384 .. method:: CCompiler.set_include_dirs(dirs)
386 Set the list of directories that will be searched to *dirs* (a list of strings).
387 Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
388 :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
389 This does not affect any list of standard include directories that the compiler
390 may search by default.
393 .. method:: CCompiler.add_library(libname)
395 Add *libname* to the list of libraries that will be included in all links driven
396 by this compiler object. Note that *libname* should \*not\* be the name of a
397 file containing a library, but the name of the library itself: the actual
398 filename will be inferred by the linker, the compiler, or the compiler class
399 (depending on the platform).
401 The linker will be instructed to link against libraries in the order they were
402 supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly
403 valid to duplicate library names; the linker will be instructed to link against
404 libraries as many times as they are mentioned.
407 .. method:: CCompiler.set_libraries(libnames)
409 Set the list of libraries to be included in all links driven by this compiler
410 object to *libnames* (a list of strings). This does not affect any standard
411 system libraries that the linker may include by default.
414 .. method:: CCompiler.add_library_dir(dir)
416 Add *dir* to the list of directories that will be searched for libraries
417 specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be
418 instructed to search for libraries in the order they are supplied to
419 :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
422 .. method:: CCompiler.set_library_dirs(dirs)
424 Set the list of library search directories to *dirs* (a list of strings). This
425 does not affect any standard library search path that the linker may search by
426 default.
429 .. method:: CCompiler.add_runtime_library_dir(dir)
431 Add *dir* to the list of directories that will be searched for shared libraries
432 at runtime.
435 .. method:: CCompiler.set_runtime_library_dirs(dirs)
437 Set the list of directories to search for shared libraries at runtime to *dirs*
438 (a list of strings). This does not affect any standard search path that the
439 runtime linker may search by default.
442 .. method:: CCompiler.define_macro(name[, value=None])
444 Define a preprocessor macro for all compilations driven by this compiler object.
445 The optional parameter *value* should be a string; if it is not supplied, then
446 the macro will be defined without an explicit value and the exact outcome
447 depends on the compiler used (XXX true? does ANSI say anything about this?)
450 .. method:: CCompiler.undefine_macro(name)
452 Undefine a preprocessor macro for all compilations driven by this compiler
453 object. If the same macro is defined by :meth:`define_macro` and
454 undefined by :meth:`undefine_macro` the last call takes precedence
455 (including multiple redefinitions or undefinitions). If the macro is
456 redefined/undefined on a per-compilation basis (ie. in the call to
457 :meth:`compile`), then that takes precedence.
460 .. method:: CCompiler.add_link_object(object)
462 Add *object* to the list of object files (or analogues, such as explicitly named
463 library files or the output of "resource compilers") to be included in every
464 link driven by this compiler object.
467 .. method:: CCompiler.set_link_objects(objects)
469 Set the list of object files (or analogues) to be included in every link to
470 *objects*. This does not affect any standard object files that the linker may
471 include by default (such as system libraries).
473 The following methods implement methods for autodetection of compiler options,
474 providing some functionality similar to GNU :program:`autoconf`.
477 .. method:: CCompiler.detect_language(sources)
479 Detect the language of a given file, or list of files. Uses the instance
480 attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a
481 list) to do the job.
484 .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
486 Search the specified list of directories for a static or shared library file
487 *lib* and return the full path to that file. If *debug* is true, look for a
488 debugging version (if that makes sense on the current platform). Return
489 ``None`` if *lib* wasn't found in any of the specified directories.
492 .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
494 Return a boolean indicating whether *funcname* is supported on the current
495 platform. The optional arguments can be used to augment the compilation
496 environment by providing additional include files and paths and libraries and
497 paths.
500 .. method:: CCompiler.library_dir_option(dir)
502 Return the compiler option to add *dir* to the list of directories searched for
503 libraries.
506 .. method:: CCompiler.library_option(lib)
508 Return the compiler option to add *dir* to the list of libraries linked into the
509 shared library or executable.
512 .. method:: CCompiler.runtime_library_dir_option(dir)
514 Return the compiler option to add *dir* to the list of directories searched for
515 runtime libraries.
518 .. method:: CCompiler.set_executables(**args)
520 Define the executables (and options for them) that will be run to perform the
521 various stages of compilation. The exact set of executables that may be
522 specified here depends on the compiler class (via the 'executables' class
523 attribute), but most will have:
525 +--------------+------------------------------------------+
526 | attribute | description |
527 +==============+==========================================+
528 | *compiler* | the C/C++ compiler |
529 +--------------+------------------------------------------+
530 | *linker_so* | linker used to create shared objects and |
531 | | libraries |
532 +--------------+------------------------------------------+
533 | *linker_exe* | linker used to create binary executables |
534 +--------------+------------------------------------------+
535 | *archiver* | static library creator |
536 +--------------+------------------------------------------+
538 On platforms with a command-line (Unix, DOS/Windows), each of these is a string
539 that will be split into executable name and (optional) list of arguments.
540 (Splitting the string is done similarly to how Unix shells operate: words are
541 delimited by spaces, but quotes and backslashes can override this. See
542 :func:`distutils.util.split_quoted`.)
544 The following methods invoke stages in the build process.
547 .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
549 Compile one or more source files. Generates object files (e.g. transforms a
550 :file:`.c` file to a :file:`.o` file.)
552 *sources* must be a list of filenames, most likely C/C++ files, but in reality
553 anything that can be handled by a particular compiler and compiler class (eg.
554 :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of
555 object filenames, one per source filename in *sources*. Depending on the
556 implementation, not all source files will necessarily be compiled, but all
557 corresponding object filenames will be returned.
559 If *output_dir* is given, object files will be put under it, while retaining
560 their original path component. That is, :file:`foo/bar.c` normally compiles to
561 :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
562 it would compile to :file:`build/foo/bar.o`.
564 *macros*, if given, must be a list of macro definitions. A macro definition is
565 either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
566 a macro; if the value is ``None``, the macro is defined without an explicit
567 value. The 1-tuple case undefines a macro. Later
568 definitions/redefinitions/undefinitions take precedence.
570 *include_dirs*, if given, must be a list of strings, the directories to add to
571 the default include file search path for this compilation only.
573 *debug* is a boolean; if true, the compiler will be instructed to output debug
574 symbols in (or alongside) the object file(s).
576 *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
577 that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
578 likely lists of strings: extra command-line arguments to prepend/append to the
579 compiler command line. On other platforms, consult the implementation class
580 documentation. In any event, they are intended as an escape hatch for those
581 occasions when the abstract compiler framework doesn't cut the mustard.
583 *depends*, if given, is a list of filenames that all targets depend on. If a
584 source file is older than any file in depends, then the source file will be
585 recompiled. This supports dependency tracking, but only at a coarse
586 granularity.
588 Raises :exc:`CompileError` on failure.
591 .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
593 Link a bunch of stuff together to create a static library file. The "bunch of
594 stuff" consists of the list of object files supplied as *objects*, the extra
595 object files supplied to :meth:`add_link_object` and/or
596 :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
597 :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
599 *output_libname* should be a library name, not a filename; the filename will be
600 inferred from the library name. *output_dir* is the directory where the library
601 file will be put. XXX defaults to what?
603 *debug* is a boolean; if true, debugging information will be included in the
604 library (note that on most platforms, it is the compile step where this matters:
605 the *debug* flag is included here just for consistency).
607 *target_lang* is the target language for which the given objects are being
608 compiled. This allows specific linkage time treatment of certain languages.
610 Raises :exc:`LibError` on failure.
613 .. 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])
615 Link a bunch of stuff together to create an executable or shared library file.
617 The "bunch of stuff" consists of the list of object files supplied as *objects*.
618 *output_filename* should be a filename. If *output_dir* is supplied,
619 *output_filename* is relative to it (i.e. *output_filename* can provide
620 directory components if needed).
622 *libraries* is a list of libraries to link against. These are library names,
623 not filenames, since they're translated into filenames in a platform-specific
624 way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
625 DOS/Windows). However, they can include a directory component, which means the
626 linker will look in that specific directory rather than searching all the normal
627 locations.
629 *library_dirs*, if supplied, should be a list of directories to search for
630 libraries that were specified as bare library names (ie. no directory
631 component). These are on top of the system default and those supplied to
632 :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs*
633 is a list of directories that will be embedded into the shared library and used
634 to search for other shared libraries that \*it\* depends on at run-time. (This
635 may only be relevant on Unix.)
637 *export_symbols* is a list of symbols that the shared library will export.
638 (This appears to be relevant only on Windows.)
640 *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
641 slight distinction that it actually matters on most platforms (as opposed to
642 :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
643 sake).
645 *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
646 course that they supply command-line arguments for the particular linker being
647 used).
649 *target_lang* is the target language for which the given objects are being
650 compiled. This allows specific linkage time treatment of certain languages.
652 Raises :exc:`LinkError` on failure.
655 .. 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])
657 Link an executable. *output_progname* is the name of the file executable, while
658 *objects* are a list of object filenames to link in. Other arguments are as for
659 the :meth:`link` method.
662 .. 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])
664 Link a shared library. *output_libname* is the name of the output library,
665 while *objects* is a list of object filenames to link in. Other arguments are
666 as for the :meth:`link` method.
669 .. 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])
671 Link a shared object. *output_filename* is the name of the shared object that
672 will be created, while *objects* is a list of object filenames to link in.
673 Other arguments are as for the :meth:`link` method.
676 .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
678 Preprocess a single C/C++ source file, named in *source*. Output will be written
679 to file named *output_file*, or *stdout* if *output_file* not supplied.
680 *macros* is a list of macro definitions as for :meth:`compile`, which will
681 augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
682 *include_dirs* is a list of directory names that will be added to the default
683 list, in the same way as :meth:`add_include_dir`.
685 Raises :exc:`PreprocessError` on failure.
687 The following utility methods are defined by the :class:`CCompiler` class, for
688 use by the various concrete subclasses.
691 .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
693 Returns the filename of the executable for the given *basename*. Typically for
694 non-Windows platforms this is the same as the basename, while Windows will get
695 a :file:`.exe` added.
698 .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
700 Returns the filename for the given library name on the current platform. On Unix
701 a library with *lib_type* of ``'static'`` will typically be of the form
702 :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
703 :file:`liblibname.so`.
706 .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
708 Returns the name of the object files for the given source files.
709 *source_filenames* should be a list of filenames.
712 .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
714 Returns the name of a shared object file for the given file name *basename*.
717 .. method:: CCompiler.execute(func, args[, msg=None, level=1])
719 Invokes :func:`distutils.util.execute` This method invokes a Python function
720 *func* with the given arguments *args*, after logging and taking into account
721 the *dry_run* flag. XXX see also.
724 .. method:: CCompiler.spawn(cmd)
726 Invokes :func:`distutils.util.spawn`. This invokes an external process to run
727 the given command. XXX see also.
730 .. method:: CCompiler.mkpath(name[, mode=511])
732 Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any
733 missing ancestor directories. XXX see also.
736 .. method:: CCompiler.move_file(src, dst)
738 Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see
739 also.
742 .. method:: CCompiler.announce(msg[, level=1])
744 Write a message using :func:`distutils.log.debug`. XXX see also.
747 .. method:: CCompiler.warn(msg)
749 Write a warning message *msg* to standard error.
752 .. method:: CCompiler.debug_print(msg)
754 If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to
755 standard output, otherwise do nothing.
757 .. % \subsection{Compiler-specific modules}
758 .. %
759 .. % The following modules implement concrete subclasses of the abstract
760 .. % \class{CCompiler} class. They should not be instantiated directly, but should
761 .. % be created using \function{distutils.ccompiler.new_compiler()} factory
762 .. % function.
765 :mod:`distutils.unixccompiler` --- Unix C Compiler
766 ==================================================
768 .. module:: distutils.unixccompiler
769 :synopsis: UNIX C Compiler
772 This module provides the :class:`UnixCCompiler` class, a subclass of
773 :class:`CCompiler` that handles the typical Unix-style command-line C compiler:
775 * macros defined with :option:`-Dname[=value]`
777 * macros undefined with :option:`-Uname`
779 * include search directories specified with :option:`-Idir`
781 * libraries specified with :option:`-llib`
783 * library search directories specified with :option:`-Ldir`
785 * compile handled by :program:`cc` (or similar) executable with :option:`-c`
786 option: compiles :file:`.c` to :file:`.o`
788 * link static library handled by :program:`ar` command (possibly with
789 :program:`ranlib`)
791 * link shared library handled by :program:`cc` :option:`-shared`
794 :mod:`distutils.msvccompiler` --- Microsoft Compiler
795 ====================================================
797 .. module:: distutils.msvccompiler
798 :synopsis: Microsoft Compiler
801 This module provides :class:`MSVCCompiler`, an implementation of the abstract
802 :class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
803 modules need to be compiled with the same compiler that was used to compile
804 Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
805 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
806 binaries are created using the Platform SDK.
808 :class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
809 its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
810 and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
811 been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
812 had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
813 that the distutils user has made an explicit choice to override the compiler
814 selection by :class:`MSVCCompiler`.
817 :mod:`distutils.bcppcompiler` --- Borland Compiler
818 ==================================================
820 .. module:: distutils.bcppcompiler
823 This module provides :class:`BorlandCCompiler`, an subclass of the abstract
824 :class:`CCompiler` class for the Borland C++ compiler.
827 :mod:`distutils.cygwincompiler` --- Cygwin Compiler
828 ===================================================
830 .. module:: distutils.cygwinccompiler
833 This module provides the :class:`CygwinCCompiler` class, a subclass of
834 :class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
835 Windows. It also contains the Mingw32CCompiler class which handles the mingw32
836 port of GCC (same as cygwin in no-cygwin mode).
839 :mod:`distutils.emxccompiler` --- OS/2 EMX Compiler
840 ===================================================
842 .. module:: distutils.emxccompiler
843 :synopsis: OS/2 EMX Compiler support
846 This module provides the EMXCCompiler class, a subclass of
847 :class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.
850 :mod:`distutils.archive_util` --- Archiving utilities
851 ======================================================
853 .. module:: distutils.archive_util
854 :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
857 This module provides a few functions for creating archive files, such as
858 tarballs or zipfiles.
861 .. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
863 Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of
864 the file to create, minus any format-specific extension; *format* is the
865 archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is
866 a directory that will be the root directory of the archive; ie. we typically
867 ``chdir`` into *root_dir* before creating the archive. *base_dir* is the
868 directory where we start archiving from; ie. *base_dir* will be the common
869 prefix of all files and directories in the archive. *root_dir* and *base_dir*
870 both default to the current directory. Returns the name of the archive file.
872 .. XXX This should be changed to support bz2 files.
875 .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
877 'Create an (optional compressed) archive as a tar file from all files in and
878 under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``,
879 ``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named
880 by *compress* must be on the default program search path, so this is probably
881 Unix-specific. The output tar file will be named :file:`base_dir.tar`,
882 possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
883 or :file:`.Z`). Return the output filename.
885 .. XXX This should be replaced with calls to the :mod:`tarfile` module.
888 .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
890 Create a zip file from all files in and under *base_dir*. The output zip file
891 will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python
892 module (if available) or the InfoZIP :file:`zip` utility (if installed and
893 found on the default search path). If neither tool is available, raises
894 :exc:`DistutilsExecError`. Returns the name of the output zip file.
897 :mod:`distutils.dep_util` --- Dependency checking
898 =================================================
900 .. module:: distutils.dep_util
901 :synopsis: Utility functions for simple dependency checking
904 This module provides functions for performing simple, timestamp-based
905 dependency of files and groups of files; also, functions based entirely on such
906 timestamp dependency analysis.
909 .. function:: newer(source, target)
911 Return true if *source* exists and is more recently modified than *target*, or
912 if *source* exists and *target* doesn't. Return false if both exist and *target*
913 is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if
914 *source* does not exist.
917 .. function:: newer_pairwise(sources, targets)
919 Walk two filename lists in parallel, testing if each source is newer than its
920 corresponding target. Return a pair of lists (*sources*, *targets*) where
921 source is newer than target, according to the semantics of :func:`newer`
923 .. % % equivalent to a listcomp...
926 .. function:: newer_group(sources, target[, missing='error'])
928 Return true if *target* is out-of-date with respect to any file listed in
929 *sources* In other words, if *target* exists and is newer than every file in
930 *sources*, return false; otherwise return true. *missing* controls what we do
931 when a source file is missing; the default (``'error'``) is to blow up with an
932 :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently
933 drop any missing source files; if it is ``'newer'``, any missing source files
934 make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
935 it'll make you pretend to carry out commands that wouldn't work because inputs
936 are missing, but that doesn't matter because you're not actually going to run
937 the commands).
940 :mod:`distutils.dir_util` --- Directory tree operations
941 =======================================================
943 .. module:: distutils.dir_util
944 :synopsis: Utility functions for operating on directories and directory trees
947 This module provides functions for operating on directories and trees of
948 directories.
951 .. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0])
953 Create a directory and any missing ancestor directories. If the directory
954 already exists (or if *name* is the empty string, which means the current
955 directory, which of course exists), then do nothing. Raise
956 :exc:`DistutilsFileError` if unable to create some directory along the way (eg.
957 some sub-path exists, but is a file rather than a directory). If *verbose* is
958 true, print a one-line summary of each mkdir to stdout. Return the list of
959 directories actually created.
962 .. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0])
964 Create all the empty directories under *base_dir* needed to put *files* there.
965 *base_dir* is just the a name of a directory which doesn't necessarily exist
966 yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
967 *base_dir* + the directory portion of every file in *files* will be created if
968 it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for
969 :func:`mkpath`.
972 .. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
974 Copy an entire directory tree *src* to a new location *dst*. Both *src* and
975 *dst* must be directory names. If *src* is not a directory, raise
976 :exc:`DistutilsFileError`. If *dst* does not exist, it is created with
977 :func:`mkpath`. The end result of the copy is that every file in *src* is
978 copied to *dst*, and directories under *src* are recursively copied to *dst*.
979 Return the list of files that were copied or might have been copied, using their
980 output name. The return value is unaffected by *update* or *dry_run*: it is
981 simply the list of all files under *src*, with the names changed to be under
982 *dst*.
984 *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in
985 :mod:`distutils.file_util`; note that they only apply to regular files, not to
986 directories. If *preserve_symlinks* is true, symlinks will be copied as
987 symlinks (on platforms that support them!); otherwise (the default), the
988 destination of the symlink will be copied. *update* and *verbose* are the same
989 as for :func:`copy_file`.
992 .. function:: remove_tree(directory[, verbose=0, dry_run=0])
994 Recursively remove *directory* and all files and directories underneath it. Any
995 errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
996 true).
998 **\*\*** Some of this could be replaced with the shutil module? **\*\***
1001 :mod:`distutils.file_util` --- Single file operations
1002 =====================================================
1004 .. module:: distutils.file_util
1005 :synopsis: Utility functions for operating on single files
1008 This module contains some utility functions for operating on individual files.
1011 .. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
1013 Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
1014 with the same name; otherwise, it must be a filename. (If the file exists, it
1015 will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
1016 file's mode (type and permission bits, or whatever is analogous on the
1017 current platform) is copied. If *preserve_times* is true (the default), the
1018 last-modified and last-access times are copied as well. If *update* is true,
1019 *src* will only be copied if *dst* does not exist, or if *dst* does exist but
1020 is older than *src*.
1022 *link* allows you to make hard links (using :func:`os.link`) or symbolic links
1023 (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
1024 ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
1025 on systems that don't support it: :func:`copy_file` doesn't check if hard or
1026 symbolic linking is available. It uses :func:`_copy_file_contents` to copy file
1027 contents.
1029 Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the
1030 output file, and *copied* is true if the file was copied (or would have been
1031 copied, if *dry_run* true).
1033 .. % XXX if the destination file already exists, we clobber it if
1034 .. % copying, but blow up if linking. Hmmm. And I don't know what
1035 .. % macostools.copyfile() does. Should definitely be consistent, and
1036 .. % should probably blow up if destination exists and we would be
1037 .. % changing it (ie. it's not already a hard/soft link to src OR
1038 .. % (not update) and (src newer than dst)).
1041 .. function:: move_file(src, dst[, verbose, dry_run])
1043 Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
1044 it with the same name; otherwise, *src* is just renamed to *dst*. Returns the
1045 new full name of the file.
1047 .. warning::
1049 Handles cross-device moves on Unix using :func:`copy_file`. What about
1050 other systems?
1053 .. function:: write_file(filename, contents)
1055 Create a file called *filename* and write *contents* (a sequence of strings
1056 without line terminators) to it.
1059 :mod:`distutils.util` --- Miscellaneous other utility functions
1060 ===============================================================
1062 .. module:: distutils.util
1063 :synopsis: Miscellaneous other utility functions
1066 This module contains other assorted bits and pieces that don't fit into any
1067 other utility module.
1070 .. function:: get_platform()
1072 Return a string that identifies the current platform. This is used mainly to
1073 distinguish platform-specific build directories and platform-specific built
1074 distributions. Typically includes the OS name and version and the architecture
1075 (as supplied by 'os.uname()'), although the exact information included depends
1076 on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
1077 runs on SGI hardware), but for Linux the kernel version isn't particularly
1078 important.
1080 Examples of returned values:
1082 * ``linux-i586``
1083 * ``linux-alpha``
1084 * ``solaris-2.6-sun4u``
1085 * ``irix-5.3``
1086 * ``irix64-6.2``
1088 For non-POSIX platforms, currently just returns ``sys.platform``.
1090 For Mac OS X systems the OS version reflects the minimal version on which
1091 binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
1092 during the build of Python), not the OS version of the current system.
1094 For universal binary builds on Mac OS X the architecture value reflects
1095 the univeral binary status instead of the architecture of the current
1096 processor. For 32-bit universal binaries the architecture is ``fat``,
1097 for 64-bit universal binaries the architecture is ``fat64``, and
1098 for 4-way universal binaries the architecture is ``universal``.
1100 Examples of returned values on Mac OS X:
1102 * ``macosx-10.3-ppc``
1104 * ``macosx-10.3-fat``
1106 * ``macosx-10.5-universal``
1108 .. % XXX isn't this also provided by some other non-distutils module?
1111 .. function:: convert_path(pathname)
1113 Return 'pathname' as a name that will work on the native filesystem, i.e. split
1114 it on '/' and put it back together again using the current directory separator.
1115 Needed because filenames in the setup script are always supplied in Unix style,
1116 and have to be converted to the local convention before we can actually use them
1117 in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if
1118 *pathname* either starts or ends with a slash.
1121 .. function:: change_root(new_root, pathname)
1123 Return *pathname* with *new_root* prepended. If *pathname* is relative, this is
1124 equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
1125 *pathname* relative and then joining the two, which is tricky on DOS/Windows.
1128 .. function:: check_environ()
1130 Ensure that 'os.environ' has all the environment variables we guarantee that
1131 users can use in config files, command-line options, etc. Currently this
1132 includes:
1134 * :envvar:`HOME` - user's home directory (Unix only)
1135 * :envvar:`PLAT` - description of the current platform, including hardware and
1136 OS (see :func:`get_platform`)
1139 .. function:: subst_vars(s, local_vars)
1141 Perform shell/Perl-style variable substitution on *s*. Every occurrence of
1142 ``$`` followed by a name is considered a variable, and variable is substituted
1143 by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
1144 not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
1145 it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError`
1146 for any variables not found in either *local_vars* or ``os.environ``.
1148 Note that this is not a fully-fledged string interpolation function. A valid
1149 ``$variable`` can consist only of upper and lower case letters, numbers and an
1150 underscore. No { } or ( ) style quoting is available.
1153 .. function:: grok_environment_error(exc[, prefix='error: '])
1155 Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError`
1156 or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles,
1157 and does what it can to deal with exception objects that don't have a filename
1158 (which happens when the error is due to a two-file operation, such as
1159 :func:`rename` or :func:`link`). Returns the error message as a string
1160 prefixed with *prefix*.
1163 .. function:: split_quoted(s)
1165 Split a string up according to Unix shell-like rules for quotes and backslashes.
1166 In short: words are delimited by spaces, as long as those spaces are not escaped
1167 by a backslash, or inside a quoted string. Single and double quotes are
1168 equivalent, and the quote characters can be backslash-escaped. The backslash is
1169 stripped from any two-character escape sequence, leaving only the escaped
1170 character. The quote characters are stripped from any quoted string. Returns a
1171 list of words.
1173 .. % Should probably be moved into the standard library.
1176 .. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
1178 Perform some action that affects the outside world (for instance, writing to the
1179 filesystem). Such actions are special because they are disabled by the
1180 *dry_run* flag. This method takes care of all that bureaucracy for you; all
1181 you have to do is supply the function to call and an argument tuple for it (to
1182 embody the "external action" being performed), and an optional message to print.
1185 .. function:: strtobool(val)
1187 Convert a string representation of truth to true (1) or false (0).
1189 True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values
1190 are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises
1191 :exc:`ValueError` if *val* is anything else.
1194 .. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
1196 Byte-compile a collection of Python source files to either :file:`.pyc` or
1197 :file:`.pyo` files in the same directory. *py_files* is a list of files to
1198 compile; any files that don't end in :file:`.py` are silently skipped.
1199 *optimize* must be one of the following:
1201 * ``0`` - don't optimize (generate :file:`.pyc`)
1202 * ``1`` - normal optimization (like ``python -O``)
1203 * ``2`` - extra optimization (like ``python -OO``)
1205 If *force* is true, all files are recompiled regardless of timestamps.
1207 The source filename encoded in each :term:`bytecode` file defaults to the filenames
1208 listed in *py_files*; you can modify these with *prefix* and *basedir*.
1209 *prefix* is a string that will be stripped off of each source filename, and
1210 *base_dir* is a directory name that will be prepended (after *prefix* is
1211 stripped). You can supply either or both (or neither) of *prefix* and
1212 *base_dir*, as you wish.
1214 If *dry_run* is true, doesn't actually do anything that would affect the
1215 filesystem.
1217 Byte-compilation is either done directly in this interpreter process with the
1218 standard :mod:`py_compile` module, or indirectly by writing a temporary script
1219 and executing it. Normally, you should let :func:`byte_compile` figure out to
1220 use direct compilation or not (see the source for details). The *direct* flag
1221 is used by the script generated in indirect mode; unless you know what you're
1222 doing, leave it set to ``None``.
1225 .. function:: rfc822_escape(header)
1227 Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
1228 ensuring there are 8 spaces space after each newline. Note that it does no other
1229 modification of the string.
1231 .. % this _can_ be replaced
1233 .. % \subsection{Distutils objects}
1236 :mod:`distutils.dist` --- The Distribution class
1237 ================================================
1239 .. module:: distutils.dist
1240 :synopsis: Provides the Distribution class, which represents the module distribution being
1241 built/installed/distributed
1244 This module provides the :class:`Distribution` class, which represents the
1245 module distribution being built/installed/distributed.
1248 :mod:`distutils.extension` --- The Extension class
1249 ==================================================
1251 .. module:: distutils.extension
1252 :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
1253 scripts
1256 This module provides the :class:`Extension` class, used to describe C/C++
1257 extension modules in setup scripts.
1259 .. % \subsection{Ungrouped modules}
1260 .. % The following haven't been moved into a more appropriate section yet.
1263 :mod:`distutils.debug` --- Distutils debug mode
1264 ===============================================
1266 .. module:: distutils.debug
1267 :synopsis: Provides the debug flag for distutils
1270 This module provides the DEBUG flag.
1273 :mod:`distutils.errors` --- Distutils exceptions
1274 ================================================
1276 .. module:: distutils.errors
1277 :synopsis: Provides standard distutils exceptions
1280 Provides exceptions used by the Distutils modules. Note that Distutils modules
1281 may raise standard exceptions; in particular, SystemExit is usually raised for
1282 errors that are obviously the end-user's fault (eg. bad command-line arguments).
1284 This module is safe to use in ``from ... import *`` mode; it only exports
1285 symbols whose names start with ``Distutils`` and end with ``Error``.
1288 :mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
1289 ===========================================================================
1291 .. module:: distutils.fancy_getopt
1292 :synopsis: Additional getopt functionality
1295 This module provides a wrapper around the standard :mod:`getopt` module that
1296 provides the following additional features:
1298 * short and long options are tied together
1300 * options have help strings, so :func:`fancy_getopt` could potentially create a
1301 complete usage summary
1303 * options set attributes of a passed-in object
1305 * boolean options can have "negative aliases" --- eg. if :option:`--quiet` is
1306 the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
1307 command line sets *verbose* to false.
1309 **\*\*** Should be replaced with :mod:`optik` (which is also now known as
1310 :mod:`optparse` in Python 2.3 and later). **\*\***
1313 .. function:: fancy_getopt(options, negative_opt, object, args)
1315 Wrapper function. *options* is a list of ``(long_option, short_option,
1316 help_string)`` 3-tuples as described in the constructor for
1317 :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
1318 to option names, both the key and value should be in the *options* list.
1319 *object* is an object which will be used to store values (see the :meth:`getopt`
1320 method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
1321 ``sys.argv[1:]`` if you pass ``None`` as *args*.
1324 .. function:: wrap_text(text, width)
1326 Wraps *text* to less than *width* wide.
1328 .. XXX Should be replaced with :mod:`textwrap` (which is available in Python
1329 2.3 and later).
1332 .. class:: FancyGetopt([option_table=None])
1334 The option_table is a list of 3-tuples: ``(long_option, short_option,
1335 help_string)``
1337 If an option takes an argument, its *long_option* should have ``'='`` appended;
1338 *short_option* should just be a single character, no ``':'`` in any case.
1339 *short_option* should be ``None`` if a *long_option* doesn't have a
1340 corresponding *short_option*. All option tuples must have long options.
1342 The :class:`FancyGetopt` class provides the following methods:
1345 .. method:: FancyGetopt.getopt([args=None, object=None])
1347 Parse command-line options in args. Store as attributes on *object*.
1349 If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is
1350 ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
1351 option values there, and returns a tuple ``(args, object)``. If *object* is
1352 supplied, it is modified in place and :func:`getopt` just returns *args*; in
1353 both cases, the returned *args* is a modified copy of the passed-in *args* list,
1354 which is left untouched.
1356 .. % and args returned are?
1359 .. method:: FancyGetopt.get_option_order()
1361 Returns the list of ``(option, value)`` tuples processed by the previous run of
1362 :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
1363 yet.
1366 .. method:: FancyGetopt.generate_help([header=None])
1368 Generate help text (a list of strings, one per suggested line of output) from
1369 the option table for this :class:`FancyGetopt` object.
1371 If supplied, prints the supplied *header* at the top of the help.
1374 :mod:`distutils.filelist` --- The FileList class
1375 ================================================
1377 .. module:: distutils.filelist
1378 :synopsis: The FileList class, used for poking about the file system and
1379 building lists of files.
1382 This module provides the :class:`FileList` class, used for poking about the
1383 filesystem and building lists of files.
1386 :mod:`distutils.log` --- Simple PEP 282-style logging
1387 =====================================================
1389 .. module:: distutils.log
1390 :synopsis: A simple logging mechanism, 282-style
1393 .. XXX Should be replaced with standard :mod:`logging` module.
1397 :mod:`distutils.spawn` --- Spawn a sub-process
1398 ==============================================
1400 .. module:: distutils.spawn
1401 :synopsis: Provides the spawn() function
1404 This module provides the :func:`spawn` function, a front-end to various
1405 platform-specific functions for launching another program in a sub-process.
1406 Also provides :func:`find_executable` to search the path for a given executable
1407 name.
1410 :mod:`distutils.sysconfig` --- System configuration information
1411 ===============================================================
1413 .. module:: distutils.sysconfig
1414 :synopsis: Low-level access to configuration information of the Python interpreter.
1415 .. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1416 .. moduleauthor:: Greg Ward <gward@python.net>
1417 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1420 The :mod:`distutils.sysconfig` module provides access to Python's low-level
1421 configuration information. The specific configuration variables available
1422 depend heavily on the platform and configuration. The specific variables depend
1423 on the build process for the specific version of Python being run; the variables
1424 are those found in the :file:`Makefile` and configuration header that are
1425 installed with Python on Unix systems. The configuration header is called
1426 :file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
1427 for earlier versions of Python.
1429 Some additional functions are provided which perform some useful manipulations
1430 for other parts of the :mod:`distutils` package.
1433 .. data:: PREFIX
1435 The result of ``os.path.normpath(sys.prefix)``.
1438 .. data:: EXEC_PREFIX
1440 The result of ``os.path.normpath(sys.exec_prefix)``.
1443 .. function:: get_config_var(name)
1445 Return the value of a single variable. This is equivalent to
1446 ``get_config_vars().get(name)``.
1449 .. function:: get_config_vars(...)
1451 Return a set of variable definitions. If there are no arguments, this returns a
1452 dictionary mapping names of configuration variables to values. If arguments are
1453 provided, they should be strings, and the return value will be a sequence giving
1454 the associated values. If a given name does not have a corresponding value,
1455 ``None`` will be included for that variable.
1458 .. function:: get_config_h_filename()
1460 Return the full path name of the configuration header. For Unix, this will be
1461 the header generated by the :program:`configure` script; for other platforms the
1462 header will have been supplied directly by the Python source distribution. The
1463 file is a platform-specific text file.
1466 .. function:: get_makefile_filename()
1468 Return the full path name of the :file:`Makefile` used to build Python. For
1469 Unix, this will be a file generated by the :program:`configure` script; the
1470 meaning for other platforms will vary. The file is a platform-specific text
1471 file, if it exists. This function is only useful on POSIX platforms.
1474 .. function:: get_python_inc([plat_specific[, prefix]])
1476 Return the directory for either the general or platform-dependent C include
1477 files. If *plat_specific* is true, the platform-dependent include directory is
1478 returned; if false or omitted, the platform-independent directory is returned.
1479 If *prefix* is given, it is used as either the prefix instead of
1480 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1481 *plat_specific* is true.
1484 .. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
1486 Return the directory for either the general or platform-dependent library
1487 installation. If *plat_specific* is true, the platform-dependent include
1488 directory is returned; if false or omitted, the platform-independent directory
1489 is returned. If *prefix* is given, it is used as either the prefix instead of
1490 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1491 *plat_specific* is true. If *standard_lib* is true, the directory for the
1492 standard library is returned rather than the directory for the installation of
1493 third-party extensions.
1495 The following function is only intended for use within the :mod:`distutils`
1496 package.
1499 .. function:: customize_compiler(compiler)
1501 Do any platform-specific customization of a
1502 :class:`distutils.ccompiler.CCompiler` instance.
1504 This function is only needed on Unix at this time, but should be called
1505 consistently to support forward-compatibility. It inserts the information that
1506 varies across Unix flavors and is stored in Python's :file:`Makefile`. This
1507 information includes the selected compiler, compiler and linker options, and the
1508 extension used by the linker for shared objects.
1510 This function is even more special-purpose, and should only be used from
1511 Python's own build procedures.
1514 .. function:: set_python_build()
1516 Inform the :mod:`distutils.sysconfig` module that it is being used as part of
1517 the build process for Python. This changes a lot of relative locations for
1518 files, allowing them to be located in the build area rather than in an installed
1519 Python.
1522 :mod:`distutils.text_file` --- The TextFile class
1523 =================================================
1525 .. module:: distutils.text_file
1526 :synopsis: provides the TextFile class, a simple interface to text files
1529 This module provides the :class:`TextFile` class, which gives an interface to
1530 text files that (optionally) takes care of stripping comments, ignoring blank
1531 lines, and joining lines with backslashes.
1534 .. class:: TextFile([filename=None, file=None, **options])
1536 This class provides a file-like object that takes care of all the things you
1537 commonly want to do when processing a text file that has some line-by-line
1538 syntax: strip comments (as long as ``#`` is your comment character), skip blank
1539 lines, join adjacent lines by escaping the newline (ie. backslash at end of
1540 line), strip leading and/or trailing whitespace. All of these are optional and
1541 independently controllable.
1543 The class provides a :meth:`warn` method so you can generate warning messages
1544 that report physical line number, even if the logical line in question spans
1545 multiple physical lines. Also provides :meth:`unreadline` for implementing
1546 line-at-a-time lookahead.
1548 :class:`TextFile` instances are create with either *filename*, *file*, or both.
1549 :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
1550 string, and *file* a file object (or something that provides :meth:`readline`
1551 and :meth:`close` methods). It is recommended that you supply at least
1552 *filename*, so that :class:`TextFile` can include it in warning messages. If
1553 *file* is not supplied, :class:`TextFile` creates its own using the
1554 :func:`open` built-in function.
1556 The options are all boolean, and affect the values returned by :meth:`readline`
1558 +------------------+--------------------------------+---------+
1559 | option name | description | default |
1560 +==================+================================+=========+
1561 | *strip_comments* | strip from ``'#'`` to end-of- | true |
1562 | | line, as well as any | |
1563 | | whitespace leading up to the | |
1564 | | ``'#'``\ ---unless it is | |
1565 | | escaped by a backslash | |
1566 +------------------+--------------------------------+---------+
1567 | *lstrip_ws* | strip leading whitespace from | false |
1568 | | each line before returning it | |
1569 +------------------+--------------------------------+---------+
1570 | *rstrip_ws* | strip trailing whitespace | true |
1571 | | (including line terminator!) | |
1572 | | from each line before | |
1573 | | returning it. | |
1574 +------------------+--------------------------------+---------+
1575 | *skip_blanks* | skip lines that are empty | true |
1576 | | \*after\* stripping comments | |
1577 | | and whitespace. (If both | |
1578 | | lstrip_ws and rstrip_ws are | |
1579 | | false, then some lines may | |
1580 | | consist of solely whitespace: | |
1581 | | these will \*not\* be skipped, | |
1582 | | even if *skip_blanks* is | |
1583 | | true.) | |
1584 +------------------+--------------------------------+---------+
1585 | *join_lines* | if a backslash is the last | false |
1586 | | non-newline character on a | |
1587 | | line after stripping comments | |
1588 | | and whitespace, join the | |
1589 | | following line to it to form | |
1590 | | one logical line; if N | |
1591 | | consecutive lines end with a | |
1592 | | backslash, then N+1 physical | |
1593 | | lines will be joined to form | |
1594 | | one logical line. | |
1595 +------------------+--------------------------------+---------+
1596 | *collapse_join* | strip leading whitespace from | false |
1597 | | lines that are joined to their | |
1598 | | predecessor; only matters if | |
1599 | | ``(join_lines and not | |
1600 | | lstrip_ws)`` | |
1601 +------------------+--------------------------------+---------+
1603 Note that since *rstrip_ws* can strip the trailing newline, the semantics of
1604 :meth:`readline` must differ from those of the builtin file object's
1605 :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for
1606 end-of-file: an empty string might just be a blank line (or an all-whitespace
1607 line), if *rstrip_ws* is true but *skip_blanks* is not.
1610 .. method:: TextFile.open(filename)
1612 Open a new file *filename*. This overrides any *file* or *filename* constructor
1613 arguments.
1616 .. method:: TextFile.close()
1618 Close the current file and forget everything we know about it (including the
1619 filename and the current line number).
1622 .. method:: TextFile.warn(msg[,line=None])
1624 Print (to stderr) a warning message tied to the current logical line in the
1625 current file. If the current logical line in the file spans multiple physical
1626 lines, the warning refers to the whole range, such as ``"lines 3-5"``. If
1627 *line* is supplied, it overrides the current line number; it may be a list or
1628 tuple to indicate a range of physical lines, or an integer for a single
1629 physical line.
1632 .. method:: TextFile.readline()
1634 Read and return a single logical line from the current file (or from an internal
1635 buffer if lines have previously been "unread" with :meth:`unreadline`). If the
1636 *join_lines* option is true, this may involve reading multiple physical lines
1637 concatenated into a single string. Updates the current line number, so calling
1638 :meth:`warn` after :meth:`readline` emits a warning about the physical line(s)
1639 just read. Returns ``None`` on end-of-file, since the empty string can occur
1640 if *rstrip_ws* is true but *strip_blanks* is not.
1643 .. method:: TextFile.readlines()
1645 Read and return the list of all logical lines remaining in the current file.
1646 This updates the current line number to the last line of the file.
1649 .. method:: TextFile.unreadline(line)
1651 Push *line* (a string) onto an internal buffer that will be checked by future
1652 :meth:`readline` calls. Handy for implementing a parser with line-at-a-time
1653 lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
1654 subsequently re-cleansed (whitespace stripped, or whatever) when read with
1655 :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
1656 to :meth:`readline`, the lines will be returned most in most recent first order.
1659 :mod:`distutils.version` --- Version number classes
1660 ===================================================
1662 .. module:: distutils.version
1663 :synopsis: implements classes that represent module version numbers.
1666 .. % todo
1667 .. % \section{Distutils Commands}
1668 .. %
1669 .. % This part of Distutils implements the various Distutils commands, such
1670 .. % as \code{build}, \code{install} \&c. Each command is implemented as a
1671 .. % separate module, with the command name as the name of the module.
1674 :mod:`distutils.cmd` --- Abstract base class for Distutils commands
1675 ===================================================================
1677 .. module:: distutils.cmd
1678 :synopsis: This module provides the abstract base class Command. This class is subclassed
1679 by the modules in the distutils.command subpackage.
1682 This module supplies the abstract base class :class:`Command`.
1685 .. class:: Command(dist)
1687 Abstract base class for defining command classes, the "worker bees" of the
1688 Distutils. A useful analogy for command classes is to think of them as
1689 subroutines with local variables called *options*. The options are declared in
1690 :meth:`initialize_options` and defined (given their final values) in
1691 :meth:`finalize_options`, both of which must be defined by every command class.
1692 The distinction between the two is necessary because option values might come
1693 from the outside world (command line, config file, ...), and any options
1694 dependent on other options must be computed after these outside influences have
1695 been processed --- hence :meth:`finalize_options`. The body of the subroutine,
1696 where it does all its work based on the values of its options, is the
1697 :meth:`run` method, which must also be implemented by every command class.
1699 The class constructor takes a single argument *dist*, a :class:`Distribution`
1700 instance.
1703 :mod:`distutils.command` --- Individual Distutils commands
1704 ==========================================================
1706 .. module:: distutils.command
1707 :synopsis: This subpackage contains one module for each standard Distutils command.
1710 .. % \subsubsection{Individual Distutils commands}
1711 .. % todo
1714 :mod:`distutils.command.bdist` --- Build a binary installer
1715 ===========================================================
1717 .. module:: distutils.command.bdist
1718 :synopsis: Build a binary installer for a package
1721 .. % todo
1724 :mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
1725 =============================================================================
1727 .. module:: distutils.command.bdist_packager
1728 :synopsis: Abstract base class for packagers
1731 .. % todo
1734 :mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
1735 ================================================================
1737 .. module:: distutils.command.bdist_dumb
1738 :synopsis: Build a "dumb" installer - a simple archive of files
1741 .. % todo
1744 :mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
1745 =================================================================================
1747 .. module:: distutils.command.bdist_msi
1748 :synopsis: Build a binary distribution as a Windows MSI file
1750 .. class:: bdist_msi(Command)
1752 Builds a `Windows Installer`_ (.msi) binary package.
1754 .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
1756 In most cases, the ``bdist_msi`` installer is a better choice than the
1757 ``bdist_wininst`` installer, because it provides better support for
1758 Win64 platforms, allows administrators to perform non-interactive
1759 installations, and allows installation through group policies.
1762 :mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
1763 ===========================================================================================
1765 .. module:: distutils.command.bdist_rpm
1766 :synopsis: Build a binary distribution as a Redhat RPM and SRPM
1769 .. % todo
1772 :mod:`distutils.command.bdist_wininst` --- Build a Windows installer
1773 ====================================================================
1775 .. module:: distutils.command.bdist_wininst
1776 :synopsis: Build a Windows installer
1779 .. % todo
1782 :mod:`distutils.command.sdist` --- Build a source distribution
1783 ==============================================================
1785 .. module:: distutils.command.sdist
1786 :synopsis: Build a source distribution
1789 .. % todo
1792 :mod:`distutils.command.build` --- Build all files of a package
1793 ===============================================================
1795 .. module:: distutils.command.build
1796 :synopsis: Build all files of a package
1799 .. % todo
1802 :mod:`distutils.command.build_clib` --- Build any C libraries in a package
1803 ==========================================================================
1805 .. module:: distutils.command.build_clib
1806 :synopsis: Build any C libraries in a package
1809 .. % todo
1812 :mod:`distutils.command.build_ext` --- Build any extensions in a package
1813 ========================================================================
1815 .. module:: distutils.command.build_ext
1816 :synopsis: Build any extensions in a package
1819 .. % todo
1822 :mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
1823 ===========================================================================
1825 .. module:: distutils.command.build_py
1826 :synopsis: Build the .py/.pyc files of a package
1829 .. % todo
1832 :mod:`distutils.command.build_scripts` --- Build the scripts of a package
1833 =========================================================================
1835 .. module:: distutils.command.build_scripts
1836 :synopsis: Build the scripts of a package
1839 .. % todo
1842 :mod:`distutils.command.clean` --- Clean a package build area
1843 =============================================================
1845 .. module:: distutils.command.clean
1846 :synopsis: Clean a package build area
1849 .. % todo
1852 :mod:`distutils.command.config` --- Perform package configuration
1853 =================================================================
1855 .. module:: distutils.command.config
1856 :synopsis: Perform package configuration
1859 .. % todo
1862 :mod:`distutils.command.install` --- Install a package
1863 ======================================================
1865 .. module:: distutils.command.install
1866 :synopsis: Install a package
1869 .. % todo
1872 :mod:`distutils.command.install_data` --- Install data files from a package
1873 ===========================================================================
1875 .. module:: distutils.command.install_data
1876 :synopsis: Install data files from a package
1879 .. % todo
1882 :mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
1883 ======================================================================================
1885 .. module:: distutils.command.install_headers
1886 :synopsis: Install C/C++ header files from a package
1889 .. % todo
1892 :mod:`distutils.command.install_lib` --- Install library files from a package
1893 =============================================================================
1895 .. module:: distutils.command.install_lib
1896 :synopsis: Install library files from a package
1899 .. % todo
1902 :mod:`distutils.command.install_scripts` --- Install script files from a package
1903 ================================================================================
1905 .. module:: distutils.command.install_scripts
1906 :synopsis: Install script files from a package
1909 .. % todo
1912 :mod:`distutils.command.register` --- Register a module with the Python Package Index
1913 =====================================================================================
1915 .. module:: distutils.command.register
1916 :synopsis: Register a module with the Python Package Index
1919 The ``register`` command registers the package with the Python Package Index.
1920 This is described in more detail in :pep:`301`.
1922 .. % todo
1924 :mod:`distutils.command.check` --- Check the meta-data of a package
1925 ===================================================================
1927 .. module:: distutils.command.check
1928 :synopsis: Check the metadata of a package
1931 The ``check`` command performs some tests on the meta-data of a package.
1932 It makes sure for example that all required meta-data are provided through
1933 the arguments passed to the :func:`setup` function.
1935 .. % todo
1938 Creating a new Distutils command
1939 ================================
1941 This section outlines the steps to create a new Distutils command.
1943 A new command lives in a module in the :mod:`distutils.command` package. There
1944 is a sample template in that directory called :file:`command_template`. Copy
1945 this file to a new module with the same name as the new command you're
1946 implementing. This module should implement a class with the same name as the
1947 module (and the command). So, for instance, to create the command
1948 ``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
1949 :file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
1950 it so that it's implementing the class :class:`peel_banana`, a subclass of
1951 :class:`distutils.cmd.Command`.
1953 Subclasses of :class:`Command` must define the following methods.
1956 .. method:: Command.initialize_options()(S)
1958 et default values for all the options that this command supports. Note that
1959 these defaults may be overridden by other commands, by the setup script, by
1960 config files, or by the command-line. Thus, this is not the place to code
1961 dependencies between options; generally, :meth:`initialize_options`
1962 implementations are just a bunch of ``self.foo = None`` assignments.
1965 .. method:: Command.finalize_options()
1967 Set final values for all the options that this command supports. This is
1968 always called as late as possible, ie. after any option assignments from the
1969 command-line or from other commands have been done. Thus, this is the place
1970 to to code option dependencies: if *foo* depends on *bar*, then it is safe to
1971 set *foo* from *bar* as long as *foo* still has the same value it was
1972 assigned in :meth:`initialize_options`.
1975 .. method:: Command.run()
1977 A command's raison d'etre: carry out the action it exists to perform, controlled
1978 by the options initialized in :meth:`initialize_options`, customized by other
1979 commands, the setup script, the command-line, and config files, and finalized in
1980 :meth:`finalize_options`. All terminal output and filesystem interaction should
1981 be done by :meth:`run`.
1983 *sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
1984 as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The
1985 parent of a family of commands defines *sub_commands* as a class attribute; it's
1986 a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
1987 and *predicate* an unbound method, a string or None. *predicate* is a method of
1988 the parent command that determines whether the corresponding command is
1989 applicable in the current situation. (Eg. we ``install_headers`` is only
1990 applicable if we have any C header files to install.) If *predicate* is None,
1991 that command is always applicable.
1993 *sub_commands* is usually defined at the \*end\* of a class, because predicates
1994 can be unbound methods, so they must already have been defined. The canonical
1995 example is the :command:`install` command.