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
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` |
36
+--------------------+--------------------------------+-------------------------------------------------------------+
37
| *description* | A single line describing the | a string |
39
+--------------------+--------------------------------+-------------------------------------------------------------+
40
| *long_description* | Longer description of the | a string |
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 | |
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 |
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 | |
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 |
87
+--------------------+--------------------------------+-------------------------------------------------------------+
88
| *options* | default options for the setup | a string |
90
+--------------------+--------------------------------+-------------------------------------------------------------+
91
| *license* | The license for the package | a string |
92
+--------------------+--------------------------------+-------------------------------------------------------------+
93
| *keywords* | Descriptive meta-data, see | |
95
+--------------------+--------------------------------+-------------------------------------------------------------+
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 |
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
118
*script_name* is a file that will be read and run with :func:`exec`. ``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 |
145
+---------------+---------------------------------------------+
147
In addition, the :mod:`distutils.core` module exposed a number of classes that
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
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 | |
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 | |
202
+------------------------+--------------------------------+---------------------------+
203
| *undef_macros* | list of macros to undefine | string |
205
+------------------------+--------------------------------+---------------------------+
206
| *library_dirs* | list of directories to search | string |
207
| | for C/C++ libraries at link | |
209
+------------------------+--------------------------------+---------------------------+
210
| *libraries* | list of library names (not | string |
211
| | filenames or paths) to link | |
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 | |
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 | |
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
271
See the :func:`setup` function for a list of keyword arguments accepted by the
272
Distribution constructor. :func:`setup` creates a Distribution instance.
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
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
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
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
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
429
.. method:: CCompiler.add_runtime_library_dir(dir)
431
Add *dir* to the list of directories that will be searched for shared libraries
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
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
500
.. method:: CCompiler.library_dir_option(dir)
502
Return the compiler option to add *dir* to the list of directories searched for
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
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 |
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
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
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
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
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
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}
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
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
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.
874
This should be changed to support bz2 files
877
.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
879
'Create an (optional compressed) archive as a tar file from all files in and
880
under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``,
881
``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named
882
by *compress* must be on the default program search path, so this is probably
883
Unix-specific. The output tar file will be named :file:`base_dir.tar`,
884
possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
885
or :file:`.Z`). Return the output filename.
889
This should be replaced with calls to the :mod:`tarfile` module.
892
.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
894
Create a zip file from all files in and under *base_dir*. The output zip file
895
will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python
896
module (if available) or the InfoZIP :file:`zip` utility (if installed and
897
found on the default search path). If neither tool is available, raises
898
:exc:`DistutilsExecError`. Returns the name of the output zip file.
901
:mod:`distutils.dep_util` --- Dependency checking
902
=================================================
904
.. module:: distutils.dep_util
905
:synopsis: Utility functions for simple dependency checking
908
This module provides functions for performing simple, timestamp-based
909
dependency of files and groups of files; also, functions based entirely on such
910
timestamp dependency analysis.
913
.. function:: newer(source, target)
915
Return true if *source* exists and is more recently modified than *target*, or
916
if *source* exists and *target* doesn't. Return false if both exist and *target*
917
is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if
918
*source* does not exist.
921
.. function:: newer_pairwise(sources, targets)
923
Walk two filename lists in parallel, testing if each source is newer than its
924
corresponding target. Return a pair of lists (*sources*, *targets*) where
925
source is newer than target, according to the semantics of :func:`newer`
927
.. % % equivalent to a listcomp...
930
.. function:: newer_group(sources, target[, missing='error'])
932
Return true if *target* is out-of-date with respect to any file listed in
933
*sources* In other words, if *target* exists and is newer than every file in
934
*sources*, return false; otherwise return true. *missing* controls what we do
935
when a source file is missing; the default (``'error'``) is to blow up with an
936
:exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently
937
drop any missing source files; if it is ``'newer'``, any missing source files
938
make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
939
it'll make you pretend to carry out commands that wouldn't work because inputs
940
are missing, but that doesn't matter because you're not actually going to run
944
:mod:`distutils.dir_util` --- Directory tree operations
945
=======================================================
947
.. module:: distutils.dir_util
948
:synopsis: Utility functions for operating on directories and directory trees
951
This module provides functions for operating on directories and trees of
955
.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0])
957
Create a directory and any missing ancestor directories. If the directory
958
already exists (or if *name* is the empty string, which means the current
959
directory, which of course exists), then do nothing. Raise
960
:exc:`DistutilsFileError` if unable to create some directory along the way (eg.
961
some sub-path exists, but is a file rather than a directory). If *verbose* is
962
true, print a one-line summary of each mkdir to stdout. Return the list of
963
directories actually created.
966
.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])
968
Create all the empty directories under *base_dir* needed to put *files* there.
969
*base_dir* is just the a name of a directory which doesn't necessarily exist
970
yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
971
*base_dir* + the directory portion of every file in *files* will be created if
972
it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for
976
.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
978
Copy an entire directory tree *src* to a new location *dst*. Both *src* and
979
*dst* must be directory names. If *src* is not a directory, raise
980
:exc:`DistutilsFileError`. If *dst* does not exist, it is created with
981
:func:`mkpath`. The end result of the copy is that every file in *src* is
982
copied to *dst*, and directories under *src* are recursively copied to *dst*.
983
Return the list of files that were copied or might have been copied, using their
984
output name. The return value is unaffected by *update* or *dry_run*: it is
985
simply the list of all files under *src*, with the names changed to be under
988
*preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in
989
:mod:`distutils.file_util`; note that they only apply to regular files, not to
990
directories. If *preserve_symlinks* is true, symlinks will be copied as
991
symlinks (on platforms that support them!); otherwise (the default), the
992
destination of the symlink will be copied. *update* and *verbose* are the same
993
as for :func:`copy_file`.
996
.. function:: remove_tree(directory[, verbose=0, dry_run=0])
998
Recursively remove *directory* and all files and directories underneath it. Any
999
errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
1002
**\*\*** Some of this could be replaced with the shutil module? **\*\***
1005
:mod:`distutils.file_util` --- Single file operations
1006
=====================================================
1008
.. module:: distutils.file_util
1009
:synopsis: Utility functions for operating on single files
1012
This module contains some utility functions for operating on individual files.
1015
.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
1017
Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
1018
with the same name; otherwise, it must be a filename. (If the file exists, it
1019
will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
1020
file's mode (type and permission bits, or whatever is analogous on the
1021
current platform) is copied. If *preserve_times* is true (the default), the
1022
last-modified and last-access times are copied as well. If *update* is true,
1023
*src* will only be copied if *dst* does not exist, or if *dst* does exist but
1024
is older than *src*.
1026
*link* allows you to make hard links (using :func:`os.link`) or symbolic links
1027
(using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
1028
``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
1029
on systems that don't support it: :func:`copy_file` doesn't check if hard or
1030
symbolic linking is available. It uses :func:`_copy_file_contents` to copy file
1033
Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the
1034
output file, and *copied* is true if the file was copied (or would have been
1035
copied, if *dry_run* true).
1037
.. % XXX if the destination file already exists, we clobber it if
1038
.. % copying, but blow up if linking. Hmmm. And I don't know what
1039
.. % macostools.copyfile() does. Should definitely be consistent, and
1040
.. % should probably blow up if destination exists and we would be
1041
.. % changing it (ie. it's not already a hard/soft link to src OR
1042
.. % (not update) and (src newer than dst)).
1045
.. function:: move_file(src, dst[, verbose, dry_run])
1047
Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
1048
it with the same name; otherwise, *src* is just renamed to *dst*. Returns the
1049
new full name of the file.
1053
Handles cross-device moves on Unix using :func:`copy_file`. What about other
1057
.. function:: write_file(filename, contents)
1059
Create a file called *filename* and write *contents* (a sequence of strings
1060
without line terminators) to it.
1063
:mod:`distutils.util` --- Miscellaneous other utility functions
1064
===============================================================
1066
.. module:: distutils.util
1067
:synopsis: Miscellaneous other utility functions
1070
This module contains other assorted bits and pieces that don't fit into any
1071
other utility module.
1074
.. function:: get_platform()
1076
Return a string that identifies the current platform. This is used mainly to
1077
distinguish platform-specific build directories and platform-specific built
1078
distributions. Typically includes the OS name and version and the architecture
1079
(as supplied by 'os.uname()'), although the exact information included depends
1080
on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
1081
runs on SGI hardware), but for Linux the kernel version isn't particularly
1084
Examples of returned values:
1088
* ``solaris-2.6-sun4u``
1092
For non-POSIX platforms, currently just returns ``sys.platform``.
1094
For MacOS X systems the OS version reflects the minimal version on which
1095
binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
1096
during the build of Python), not the OS version of the current system.
1098
For universal binary builds on MacOS X the architecture value reflects
1099
the univeral binary status instead of the architecture of the current
1100
processor. For 32-bit universal binaries the architecture is ``fat``,
1101
for 64-bit universal binaries the architecture is ``fat64``, and
1102
for 4-way universal binaries the architecture is ``universal``.
1104
Examples of returned values on MacOS X:
1106
* ``macosx-10.3-ppc``
1108
* ``macosx-10.3-fat``
1110
* ``macosx-10.5-universal``
1112
.. % XXX isn't this also provided by some other non-distutils module?
1115
.. function:: convert_path(pathname)
1117
Return 'pathname' as a name that will work on the native filesystem, i.e. split
1118
it on '/' and put it back together again using the current directory separator.
1119
Needed because filenames in the setup script are always supplied in Unix style,
1120
and have to be converted to the local convention before we can actually use them
1121
in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if
1122
*pathname* either starts or ends with a slash.
1125
.. function:: change_root(new_root, pathname)
1127
Return *pathname* with *new_root* prepended. If *pathname* is relative, this is
1128
equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
1129
*pathname* relative and then joining the two, which is tricky on DOS/Windows.
1132
.. function:: check_environ()
1134
Ensure that 'os.environ' has all the environment variables we guarantee that
1135
users can use in config files, command-line options, etc. Currently this
1138
* :envvar:`HOME` - user's home directory (Unix only)
1139
* :envvar:`PLAT` - description of the current platform, including hardware and
1140
OS (see :func:`get_platform`)
1143
.. function:: subst_vars(s, local_vars)
1145
Perform shell/Perl-style variable substitution on *s*. Every occurrence of
1146
``$`` followed by a name is considered a variable, and variable is substituted
1147
by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
1148
not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
1149
it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError`
1150
for any variables not found in either *local_vars* or ``os.environ``.
1152
Note that this is not a fully-fledged string interpolation function. A valid
1153
``$variable`` can consist only of upper and lower case letters, numbers and an
1154
underscore. No { } or ( ) style quoting is available.
1157
.. function:: grok_environment_error(exc[, prefix='error: '])
1159
Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError`
1160
or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles,
1161
and does what it can to deal with exception objects that don't have a filename
1162
(which happens when the error is due to a two-file operation, such as
1163
:func:`rename` or :func:`link`). Returns the error message as a string
1164
prefixed with *prefix*.
1167
.. function:: split_quoted(s)
1169
Split a string up according to Unix shell-like rules for quotes and backslashes.
1170
In short: words are delimited by spaces, as long as those spaces are not escaped
1171
by a backslash, or inside a quoted string. Single and double quotes are
1172
equivalent, and the quote characters can be backslash-escaped. The backslash is
1173
stripped from any two-character escape sequence, leaving only the escaped
1174
character. The quote characters are stripped from any quoted string. Returns a
1177
.. % Should probably be moved into the standard library.
1180
.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
1182
Perform some action that affects the outside world (for instance, writing to the
1183
filesystem). Such actions are special because they are disabled by the
1184
*dry_run* flag. This method takes care of all that bureaucracy for you; all
1185
you have to do is supply the function to call and an argument tuple for it (to
1186
embody the "external action" being performed), and an optional message to print.
1189
.. function:: strtobool(val)
1191
Convert a string representation of truth to true (1) or false (0).
1193
True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values
1194
are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises
1195
:exc:`ValueError` if *val* is anything else.
1198
.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
1200
Byte-compile a collection of Python source files to either :file:`.pyc` or
1201
:file:`.pyo` files in the same directory. *py_files* is a list of files to
1202
compile; any files that don't end in :file:`.py` are silently skipped.
1203
*optimize* must be one of the following:
1205
* ``0`` - don't optimize (generate :file:`.pyc`)
1206
* ``1`` - normal optimization (like ``python -O``)
1207
* ``2`` - extra optimization (like ``python -OO``)
1209
If *force* is true, all files are recompiled regardless of timestamps.
1211
The source filename encoded in each :term:`bytecode` file defaults to the filenames
1212
listed in *py_files*; you can modify these with *prefix* and *basedir*.
1213
*prefix* is a string that will be stripped off of each source filename, and
1214
*base_dir* is a directory name that will be prepended (after *prefix* is
1215
stripped). You can supply either or both (or neither) of *prefix* and
1216
*base_dir*, as you wish.
1218
If *dry_run* is true, doesn't actually do anything that would affect the
1221
Byte-compilation is either done directly in this interpreter process with the
1222
standard :mod:`py_compile` module, or indirectly by writing a temporary script
1223
and executing it. Normally, you should let :func:`byte_compile` figure out to
1224
use direct compilation or not (see the source for details). The *direct* flag
1225
is used by the script generated in indirect mode; unless you know what you're
1226
doing, leave it set to ``None``.
1229
.. function:: rfc822_escape(header)
1231
Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
1232
ensuring there are 8 spaces space after each newline. Note that it does no other
1233
modification of the string.
1235
.. % this _can_ be replaced
1237
.. % \subsection{Distutils objects}
1240
:mod:`distutils.dist` --- The Distribution class
1241
================================================
1243
.. module:: distutils.dist
1244
:synopsis: Provides the Distribution class, which represents the module distribution being
1245
built/installed/distributed
1248
This module provides the :class:`Distribution` class, which represents the
1249
module distribution being built/installed/distributed.
1252
:mod:`distutils.extension` --- The Extension class
1253
==================================================
1255
.. module:: distutils.extension
1256
:synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
1260
This module provides the :class:`Extension` class, used to describe C/C++
1261
extension modules in setup scripts.
1263
.. % \subsection{Ungrouped modules}
1264
.. % The following haven't been moved into a more appropriate section yet.
1267
:mod:`distutils.debug` --- Distutils debug mode
1268
===============================================
1270
.. module:: distutils.debug
1271
:synopsis: Provides the debug flag for distutils
1274
This module provides the DEBUG flag.
1277
:mod:`distutils.errors` --- Distutils exceptions
1278
================================================
1280
.. module:: distutils.errors
1281
:synopsis: Provides standard distutils exceptions
1284
Provides exceptions used by the Distutils modules. Note that Distutils modules
1285
may raise standard exceptions; in particular, SystemExit is usually raised for
1286
errors that are obviously the end-user's fault (eg. bad command-line arguments).
1288
This module is safe to use in ``from ... import *`` mode; it only exports
1289
symbols whose names start with ``Distutils`` and end with ``Error``.
1292
:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
1293
===========================================================================
1295
.. module:: distutils.fancy_getopt
1296
:synopsis: Additional getopt functionality
1299
This module provides a wrapper around the standard :mod:`getopt` module that
1300
provides the following additional features:
1302
* short and long options are tied together
1304
* options have help strings, so :func:`fancy_getopt` could potentially create a
1305
complete usage summary
1307
* options set attributes of a passed-in object
1309
* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is
1310
the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
1311
command line sets *verbose* to false.
1313
**\*\*** Should be replaced with :mod:`optik` (which is also now known as
1314
:mod:`optparse` in Python 2.3 and later). **\*\***
1317
.. function:: fancy_getopt(options, negative_opt, object, args)
1319
Wrapper function. *options* is a list of ``(long_option, short_option,
1320
help_string)`` 3-tuples as described in the constructor for
1321
:class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
1322
to option names, both the key and value should be in the *options* list.
1323
*object* is an object which will be used to store values (see the :meth:`getopt`
1324
method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
1325
``sys.argv[1:]`` if you pass ``None`` as *args*.
1328
.. function:: wrap_text(text, width)
1330
Wraps *text* to less than *width* wide.
1334
Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and
1338
.. class:: FancyGetopt([option_table=None])
1340
The option_table is a list of 3-tuples: ``(long_option, short_option,
1343
If an option takes an argument, its *long_option* should have ``'='`` appended;
1344
*short_option* should just be a single character, no ``':'`` in any case.
1345
*short_option* should be ``None`` if a *long_option* doesn't have a
1346
corresponding *short_option*. All option tuples must have long options.
1348
The :class:`FancyGetopt` class provides the following methods:
1351
.. method:: FancyGetopt.getopt([args=None, object=None])
1353
Parse command-line options in args. Store as attributes on *object*.
1355
If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is
1356
``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
1357
option values there, and returns a tuple ``(args, object)``. If *object* is
1358
supplied, it is modified in place and :func:`getopt` just returns *args*; in
1359
both cases, the returned *args* is a modified copy of the passed-in *args* list,
1360
which is left untouched.
1362
.. % and args returned are?
1365
.. method:: FancyGetopt.get_option_order()
1367
Returns the list of ``(option, value)`` tuples processed by the previous run of
1368
:meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
1372
.. method:: FancyGetopt.generate_help([header=None])
1374
Generate help text (a list of strings, one per suggested line of output) from
1375
the option table for this :class:`FancyGetopt` object.
1377
If supplied, prints the supplied *header* at the top of the help.
1380
:mod:`distutils.filelist` --- The FileList class
1381
================================================
1383
.. module:: distutils.filelist
1384
:synopsis: The FileList class, used for poking about the file system and building lists of
1388
This module provides the :class:`FileList` class, used for poking about the
1389
filesystem and building lists of files.
1392
:mod:`distutils.log` --- Simple PEP 282-style logging
1393
=====================================================
1395
.. module:: distutils.log
1396
:synopsis: A simple logging mechanism, 282-style
1401
Should be replaced with standard :mod:`logging` module.
1403
.. % \subsubsection{\module{} --- }
1404
.. % \declaremodule{standard}{distutils.magic}
1405
.. % \modulesynopsis{ }
1408
:mod:`distutils.spawn` --- Spawn a sub-process
1409
==============================================
1411
.. module:: distutils.spawn
1412
:synopsis: Provides the spawn() function
1415
This module provides the :func:`spawn` function, a front-end to various
1416
platform-specific functions for launching another program in a sub-process.
1417
Also provides :func:`find_executable` to search the path for a given executable
1421
:mod:`distutils.sysconfig` --- System configuration information
1422
===============================================================
1424
.. module:: distutils.sysconfig
1425
:synopsis: Low-level access to configuration information of the Python interpreter.
1426
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1427
.. moduleauthor:: Greg Ward <gward@python.net>
1428
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1431
The :mod:`distutils.sysconfig` module provides access to Python's low-level
1432
configuration information. The specific configuration variables available
1433
depend heavily on the platform and configuration. The specific variables depend
1434
on the build process for the specific version of Python being run; the variables
1435
are those found in the :file:`Makefile` and configuration header that are
1436
installed with Python on Unix systems. The configuration header is called
1437
:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
1438
for earlier versions of Python.
1440
Some additional functions are provided which perform some useful manipulations
1441
for other parts of the :mod:`distutils` package.
1446
The result of ``os.path.normpath(sys.prefix)``.
1449
.. data:: EXEC_PREFIX
1451
The result of ``os.path.normpath(sys.exec_prefix)``.
1454
.. function:: get_config_var(name)
1456
Return the value of a single variable. This is equivalent to
1457
``get_config_vars().get(name)``.
1460
.. function:: get_config_vars(...)
1462
Return a set of variable definitions. If there are no arguments, this returns a
1463
dictionary mapping names of configuration variables to values. If arguments are
1464
provided, they should be strings, and the return value will be a sequence giving
1465
the associated values. If a given name does not have a corresponding value,
1466
``None`` will be included for that variable.
1469
.. function:: get_config_h_filename()
1471
Return the full path name of the configuration header. For Unix, this will be
1472
the header generated by the :program:`configure` script; for other platforms the
1473
header will have been supplied directly by the Python source distribution. The
1474
file is a platform-specific text file.
1477
.. function:: get_makefile_filename()
1479
Return the full path name of the :file:`Makefile` used to build Python. For
1480
Unix, this will be a file generated by the :program:`configure` script; the
1481
meaning for other platforms will vary. The file is a platform-specific text
1482
file, if it exists. This function is only useful on POSIX platforms.
1485
.. function:: get_python_inc([plat_specific[, prefix]])
1487
Return the directory for either the general or platform-dependent C include
1488
files. If *plat_specific* is true, the platform-dependent include directory is
1489
returned; if false or omitted, the platform-independent directory is returned.
1490
If *prefix* is given, it is used as either the prefix instead of
1491
:const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1492
*plat_specific* is true.
1495
.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
1497
Return the directory for either the general or platform-dependent library
1498
installation. If *plat_specific* is true, the platform-dependent include
1499
directory is returned; if false or omitted, the platform-independent directory
1500
is returned. If *prefix* is given, it is used as either the prefix instead of
1501
:const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1502
*plat_specific* is true. If *standard_lib* is true, the directory for the
1503
standard library is returned rather than the directory for the installation of
1504
third-party extensions.
1506
The following function is only intended for use within the :mod:`distutils`
1510
.. function:: customize_compiler(compiler)
1512
Do any platform-specific customization of a
1513
:class:`distutils.ccompiler.CCompiler` instance.
1515
This function is only needed on Unix at this time, but should be called
1516
consistently to support forward-compatibility. It inserts the information that
1517
varies across Unix flavors and is stored in Python's :file:`Makefile`. This
1518
information includes the selected compiler, compiler and linker options, and the
1519
extension used by the linker for shared objects.
1521
This function is even more special-purpose, and should only be used from
1522
Python's own build procedures.
1525
.. function:: set_python_build()
1527
Inform the :mod:`distutils.sysconfig` module that it is being used as part of
1528
the build process for Python. This changes a lot of relative locations for
1529
files, allowing them to be located in the build area rather than in an installed
1533
:mod:`distutils.text_file` --- The TextFile class
1534
=================================================
1536
.. module:: distutils.text_file
1537
:synopsis: provides the TextFile class, a simple interface to text files
1540
This module provides the :class:`TextFile` class, which gives an interface to
1541
text files that (optionally) takes care of stripping comments, ignoring blank
1542
lines, and joining lines with backslashes.
1545
.. class:: TextFile([filename=None, file=None, **options])
1547
This class provides a file-like object that takes care of all the things you
1548
commonly want to do when processing a text file that has some line-by-line
1549
syntax: strip comments (as long as ``#`` is your comment character), skip blank
1550
lines, join adjacent lines by escaping the newline (ie. backslash at end of
1551
line), strip leading and/or trailing whitespace. All of these are optional and
1552
independently controllable.
1554
The class provides a :meth:`warn` method so you can generate warning messages
1555
that report physical line number, even if the logical line in question spans
1556
multiple physical lines. Also provides :meth:`unreadline` for implementing
1557
line-at-a-time lookahead.
1559
:class:`TextFile` instances are create with either *filename*, *file*, or both.
1560
:exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
1561
string, and *file* a file object (or something that provides :meth:`readline`
1562
and :meth:`close` methods). It is recommended that you supply at least
1563
*filename*, so that :class:`TextFile` can include it in warning messages. If
1564
*file* is not supplied, :class:`TextFile` creates its own using the
1565
:func:`open` built-in function.
1567
The options are all boolean, and affect the values returned by :meth:`readline`
1569
+------------------+--------------------------------+---------+
1570
| option name | description | default |
1571
+==================+================================+=========+
1572
| *strip_comments* | strip from ``'#'`` to end-of- | true |
1573
| | line, as well as any | |
1574
| | whitespace leading up to the | |
1575
| | ``'#'``\ ---unless it is | |
1576
| | escaped by a backslash | |
1577
+------------------+--------------------------------+---------+
1578
| *lstrip_ws* | strip leading whitespace from | false |
1579
| | each line before returning it | |
1580
+------------------+--------------------------------+---------+
1581
| *rstrip_ws* | strip trailing whitespace | true |
1582
| | (including line terminator!) | |
1583
| | from each line before | |
1584
| | returning it. | |
1585
+------------------+--------------------------------+---------+
1586
| *skip_blanks* | skip lines that are empty | true |
1587
| | \*after\* stripping comments | |
1588
| | and whitespace. (If both | |
1589
| | lstrip_ws and rstrip_ws are | |
1590
| | false, then some lines may | |
1591
| | consist of solely whitespace: | |
1592
| | these will \*not\* be skipped, | |
1593
| | even if *skip_blanks* is | |
1595
+------------------+--------------------------------+---------+
1596
| *join_lines* | if a backslash is the last | false |
1597
| | non-newline character on a | |
1598
| | line after stripping comments | |
1599
| | and whitespace, join the | |
1600
| | following line to it to form | |
1601
| | one logical line; if N | |
1602
| | consecutive lines end with a | |
1603
| | backslash, then N+1 physical | |
1604
| | lines will be joined to form | |
1605
| | one logical line. | |
1606
+------------------+--------------------------------+---------+
1607
| *collapse_join* | strip leading whitespace from | false |
1608
| | lines that are joined to their | |
1609
| | predecessor; only matters if | |
1610
| | ``(join_lines and not | |
1611
| | lstrip_ws)`` | |
1612
+------------------+--------------------------------+---------+
1614
Note that since *rstrip_ws* can strip the trailing newline, the semantics of
1615
:meth:`readline` must differ from those of the builtin file object's
1616
:meth:`readline` method! In particular, :meth:`readline` returns ``None`` for
1617
end-of-file: an empty string might just be a blank line (or an all-whitespace
1618
line), if *rstrip_ws* is true but *skip_blanks* is not.
1621
.. method:: TextFile.open(filename)
1623
Open a new file *filename*. This overrides any *file* or *filename* constructor
1627
.. method:: TextFile.close()
1629
Close the current file and forget everything we know about it (including the
1630
filename and the current line number).
1633
.. method:: TextFile.warn(msg[,line=None])
1635
Print (to stderr) a warning message tied to the current logical line in the
1636
current file. If the current logical line in the file spans multiple physical
1637
lines, the warning refers to the whole range, such as ``"lines 3-5"``. If
1638
*line* is supplied, it overrides the current line number; it may be a list or
1639
tuple to indicate a range of physical lines, or an integer for a single
1643
.. method:: TextFile.readline()
1645
Read and return a single logical line from the current file (or from an internal
1646
buffer if lines have previously been "unread" with :meth:`unreadline`). If the
1647
*join_lines* option is true, this may involve reading multiple physical lines
1648
concatenated into a single string. Updates the current line number, so calling
1649
:meth:`warn` after :meth:`readline` emits a warning about the physical line(s)
1650
just read. Returns ``None`` on end-of-file, since the empty string can occur
1651
if *rstrip_ws* is true but *strip_blanks* is not.
1654
.. method:: TextFile.readlines()
1656
Read and return the list of all logical lines remaining in the current file.
1657
This updates the current line number to the last line of the file.
1660
.. method:: TextFile.unreadline(line)
1662
Push *line* (a string) onto an internal buffer that will be checked by future
1663
:meth:`readline` calls. Handy for implementing a parser with line-at-a-time
1664
lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
1665
subsequently re-cleansed (whitespace stripped, or whatever) when read with
1666
:meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
1667
to :meth:`readline`, the lines will be returned most in most recent first order.
1670
:mod:`distutils.version` --- Version number classes
1671
===================================================
1673
.. module:: distutils.version
1674
:synopsis: implements classes that represent module version numbers.
1678
.. % \section{Distutils Commands}
1680
.. % This part of Distutils implements the various Distutils commands, such
1681
.. % as \code{build}, \code{install} \&c. Each command is implemented as a
1682
.. % separate module, with the command name as the name of the module.
1685
:mod:`distutils.cmd` --- Abstract base class for Distutils commands
1686
===================================================================
1688
.. module:: distutils.cmd
1689
:synopsis: This module provides the abstract base class Command. This class is subclassed
1690
by the modules in the distutils.command subpackage.
1693
This module supplies the abstract base class :class:`Command`.
1696
.. class:: Command(dist)
1698
Abstract base class for defining command classes, the "worker bees" of the
1699
Distutils. A useful analogy for command classes is to think of them as
1700
subroutines with local variables called *options*. The options are declared in
1701
:meth:`initialize_options` and defined (given their final values) in
1702
:meth:`finalize_options`, both of which must be defined by every command class.
1703
The distinction between the two is necessary because option values might come
1704
from the outside world (command line, config file, ...), and any options
1705
dependent on other options must be computed after these outside influences have
1706
been processed --- hence :meth:`finalize_options`. The body of the subroutine,
1707
where it does all its work based on the values of its options, is the
1708
:meth:`run` method, which must also be implemented by every command class.
1710
The class constructor takes a single argument *dist*, a :class:`Distribution`
1714
:mod:`distutils.command` --- Individual Distutils commands
1715
==========================================================
1717
.. module:: distutils.command
1718
:synopsis: This subpackage contains one module for each standard Distutils command.
1721
.. % \subsubsection{Individual Distutils commands}
1725
:mod:`distutils.command.bdist` --- Build a binary installer
1726
===========================================================
1728
.. module:: distutils.command.bdist
1729
:synopsis: Build a binary installer for a package
1735
:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
1736
=============================================================================
1738
.. module:: distutils.command.bdist_packager
1739
:synopsis: Abstract base class for packagers
1745
:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
1746
================================================================
1748
.. module:: distutils.command.bdist_dumb
1749
:synopsis: Build a "dumb" installer - a simple archive of files
1755
:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
1756
=================================================================================
1758
.. module:: distutils.command.bdist_msi
1759
:synopsis: Build a binary distribution as a Windows MSI file
1765
:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
1766
===========================================================================================
1768
.. module:: distutils.command.bdist_rpm
1769
:synopsis: Build a binary distribution as a Redhat RPM and SRPM
1775
:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
1776
====================================================================
1778
.. module:: distutils.command.bdist_wininst
1779
:synopsis: Build a Windows installer
1785
:mod:`distutils.command.sdist` --- Build a source distribution
1786
==============================================================
1788
.. module:: distutils.command.sdist
1789
:synopsis: Build a source distribution
1795
:mod:`distutils.command.build` --- Build all files of a package
1796
===============================================================
1798
.. module:: distutils.command.build
1799
:synopsis: Build all files of a package
1805
:mod:`distutils.command.build_clib` --- Build any C libraries in a package
1806
==========================================================================
1808
.. module:: distutils.command.build_clib
1809
:synopsis: Build any C libraries in a package
1815
:mod:`distutils.command.build_ext` --- Build any extensions in a package
1816
========================================================================
1818
.. module:: distutils.command.build_ext
1819
:synopsis: Build any extensions in a package
1825
:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
1826
===========================================================================
1828
.. module:: distutils.command.build_py
1829
:synopsis: Build the .py/.pyc files of a package
1832
.. class:: build_py(Command)
1834
.. class:: build_py_2to3(build_py)
1836
Alternative implementation of build_py which also runs the
1837
2to3 conversion library on each .py file that is going to be
1838
installed. To use this in a setup.py file for a distribution
1839
that is designed to run with both Python 2.x and 3.x, add::
1842
from distutils.command.build_py import build_py_2to3 as build_py
1844
from distutils.command.build_py import build_py
1846
to your setup.py, and later::
1848
cmdclass = {'build_py':build_py}
1850
to the invocation of setup().
1853
:mod:`distutils.command.build_scripts` --- Build the scripts of a package
1854
=========================================================================
1856
.. module:: distutils.command.build_scripts
1857
:synopsis: Build the scripts of a package
1863
:mod:`distutils.command.clean` --- Clean a package build area
1864
=============================================================
1866
.. module:: distutils.command.clean
1867
:synopsis: Clean a package build area
1873
:mod:`distutils.command.config` --- Perform package configuration
1874
=================================================================
1876
.. module:: distutils.command.config
1877
:synopsis: Perform package configuration
1883
:mod:`distutils.command.install` --- Install a package
1884
======================================================
1886
.. module:: distutils.command.install
1887
:synopsis: Install a package
1893
:mod:`distutils.command.install_data` --- Install data files from a package
1894
===========================================================================
1896
.. module:: distutils.command.install_data
1897
:synopsis: Install data files from a package
1903
:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
1904
======================================================================================
1906
.. module:: distutils.command.install_headers
1907
:synopsis: Install C/C++ header files from a package
1913
:mod:`distutils.command.install_lib` --- Install library files from a package
1914
=============================================================================
1916
.. module:: distutils.command.install_lib
1917
:synopsis: Install library files from a package
1923
:mod:`distutils.command.install_scripts` --- Install script files from a package
1924
================================================================================
1926
.. module:: distutils.command.install_scripts
1927
:synopsis: Install script files from a package
1933
:mod:`distutils.command.register` --- Register a module with the Python Package Index
1934
=====================================================================================
1936
.. module:: distutils.command.register
1937
:synopsis: Register a module with the Python Package Index
1940
The ``register`` command registers the package with the Python Package Index.
1941
This is described in more detail in :pep:`301`.
1946
Creating a new Distutils command
1947
================================
1949
This section outlines the steps to create a new Distutils command.
1951
A new command lives in a module in the :mod:`distutils.command` package. There
1952
is a sample template in that directory called :file:`command_template`. Copy
1953
this file to a new module with the same name as the new command you're
1954
implementing. This module should implement a class with the same name as the
1955
module (and the command). So, for instance, to create the command
1956
``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
1957
:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
1958
it so that it's implementing the class :class:`peel_banana`, a subclass of
1959
:class:`distutils.cmd.Command`.
1961
Subclasses of :class:`Command` must define the following methods.
1964
.. method:: Command.initialize_options()(S)
1966
et default values for all the options that this command supports. Note that
1967
these defaults may be overridden by other commands, by the setup script, by
1968
config files, or by the command-line. Thus, this is not the place to code
1969
dependencies between options; generally, :meth:`initialize_options`
1970
implementations are just a bunch of ``self.foo = None`` assignments.
1973
.. method:: Command.finalize_options()
1975
Set final values for all the options that this command supports. This is
1976
always called as late as possible, ie. after any option assignments from the
1977
command-line or from other commands have been done. Thus, this is the place
1978
to to code option dependencies: if *foo* depends on *bar*, then it is safe to
1979
set *foo* from *bar* as long as *foo* still has the same value it was
1980
assigned in :meth:`initialize_options`.
1983
.. method:: Command.run()
1985
A command's raison d'etre: carry out the action it exists to perform, controlled
1986
by the options initialized in :meth:`initialize_options`, customized by other
1987
commands, the setup script, the command-line, and config files, and finalized in
1988
:meth:`finalize_options`. All terminal output and filesystem interaction should
1989
be done by :meth:`run`.
1991
*sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
1992
as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The
1993
parent of a family of commands defines *sub_commands* as a class attribute; it's
1994
a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
1995
and *predicate* a function, a string or None. *predicate* is a method of
1996
the parent command that determines whether the corresponding command is
1997
applicable in the current situation. (Eg. we ``install_headers`` is only
1998
applicable if we have any C header files to install.) If *predicate* is None,
1999
that command is always applicable.
2001
*sub_commands* is usually defined at the \*end\* of a class, because predicates
2002
can be methods of the class, so they must already have been defined. The
2003
canonical example is the :command:`install` command.
added
removed
Doc/distutils/apiref.rst
