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