31
31
+====================+================================+=============================================================+
32
32
| *name* | The name of the package | a string |
33
33
+--------------------+--------------------------------+-------------------------------------------------------------+
34
| *version* | The version number of the | See :mod:`distutils.version` |
34
| *version* | The version number of the | a string |
36
| | :mod:`distutils.version` | |
36
37
+--------------------+--------------------------------+-------------------------------------------------------------+
37
38
| *description* | A single line describing the | a string |
49
50
| | maintainer, if different from | |
51
52
+--------------------+--------------------------------+-------------------------------------------------------------+
52
| *maintainer_email* | The email address of the | |
53
| *maintainer_email* | The email address of the | a string |
53
54
| | current maintainer, if | |
54
55
| | different from the author | |
55
56
+--------------------+--------------------------------+-------------------------------------------------------------+
56
| *url* | A URL for the package | a URL |
57
| *url* | A URL for the package | a string |
58
59
+--------------------+--------------------------------+-------------------------------------------------------------+
59
| *download_url* | A URL to download the package | a URL |
60
| *download_url* | A URL to download the package | a string |
60
61
+--------------------+--------------------------------+-------------------------------------------------------------+
61
62
| *packages* | A list of Python packages that | a list of strings |
62
63
| | distutils will manipulate | |
68
69
| | files to be built and | |
70
71
+--------------------+--------------------------------+-------------------------------------------------------------+
71
| *ext_modules* | A list of Python extensions to | A list of instances of |
72
| *ext_modules* | A list of Python extensions to | a list of instances of |
72
73
| | be built | :class:`distutils.core.Extension` |
73
74
+--------------------+--------------------------------+-------------------------------------------------------------+
74
| *classifiers* | A list of categories for the | The list of available |
75
| | package | categorizations is available on `PyPI |
76
| | | <http://pypi.python.org/pypi?:action=list_classifiers>`_. |
75
| *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI |
76
| | package | <http://pypi.python.org/pypi?:action=list_classifiers>`_. |
77
77
+--------------------+--------------------------------+-------------------------------------------------------------+
78
| *distclass* | the :class:`Distribution` | A subclass of |
78
| *distclass* | the :class:`Distribution` | a subclass of |
79
79
| | class to use | :class:`distutils.core.Distribution` |
80
80
+--------------------+--------------------------------+-------------------------------------------------------------+
81
81
| *script_name* | The name of the setup.py | a string |
85
85
| *script_args* | Arguments to supply to the | a list of strings |
86
86
| | setup script | |
87
87
+--------------------+--------------------------------+-------------------------------------------------------------+
88
| *options* | default options for the setup | a string |
88
| *options* | default options for the setup | a dictionary |
90
90
+--------------------+--------------------------------+-------------------------------------------------------------+
91
91
| *license* | The license for the package | a string |
92
92
+--------------------+--------------------------------+-------------------------------------------------------------+
93
| *keywords* | Descriptive meta-data, see | |
93
| *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string |
95
95
+--------------------+--------------------------------+-------------------------------------------------------------+
96
| *platforms* | | a list of strings or a comma-separated string |
97
97
+--------------------+--------------------------------+-------------------------------------------------------------+
98
98
| *cmdclass* | A mapping of command names to | a dictionary |
99
99
| | :class:`Command` subclasses | |
165
165
+------------------------+--------------------------------+---------------------------+
166
166
| argument name | value | type |
167
167
+========================+================================+===========================+
168
| *name* | the full name of the | string |
168
| *name* | the full name of the | a string |
169
169
| | extension, including any | |
170
170
| | packages --- ie. *not* a | |
171
171
| | filename or pathname, but | |
172
172
| | Python dotted name | |
173
173
+------------------------+--------------------------------+---------------------------+
174
| *sources* | list of source filenames, | string |
174
| *sources* | list of source filenames, | a list of strings |
175
175
| | relative to the distribution | |
176
176
| | root (where the setup script | |
177
177
| | lives), in Unix form (slash- | |
184
184
| | as source for a Python | |
185
185
| | extension. | |
186
186
+------------------------+--------------------------------+---------------------------+
187
| *include_dirs* | list of directories to search | string |
187
| *include_dirs* | list of directories to search | a list of strings |
188
188
| | for C/C++ header files (in | |
189
189
| | Unix form for portability) | |
190
190
+------------------------+--------------------------------+---------------------------+
191
| *define_macros* | list of macros to define; each | (string, string) tuple or |
192
| | macro is defined using a | (name, ``None``) |
191
| *define_macros* | list of macros to define; each | a list of tuples |
192
| | macro is defined using a | |
193
193
| | 2-tuple ``(name, value)``, | |
194
194
| | where *value* is | |
195
195
| | either the string to define it | |
200
200
| | on Unix C compiler command | |
202
202
+------------------------+--------------------------------+---------------------------+
203
| *undef_macros* | list of macros to undefine | string |
203
| *undef_macros* | list of macros to undefine | a list of strings |
204
204
| | explicitly | |
205
205
+------------------------+--------------------------------+---------------------------+
206
| *library_dirs* | list of directories to search | string |
206
| *library_dirs* | list of directories to search | a list of strings |
207
207
| | for C/C++ libraries at link | |
209
209
+------------------------+--------------------------------+---------------------------+
210
| *libraries* | list of library names (not | string |
210
| *libraries* | list of library names (not | a list of strings |
211
211
| | filenames or paths) to link | |
213
213
+------------------------+--------------------------------+---------------------------+
214
| *runtime_library_dirs* | list of directories to search | string |
214
| *runtime_library_dirs* | list of directories to search | a list of strings |
215
215
| | for C/C++ libraries at run | |
216
216
| | time (for shared extensions, | |
217
217
| | this is when the extension is | |
219
219
+------------------------+--------------------------------+---------------------------+
220
| *extra_objects* | list of extra files to link | string |
220
| *extra_objects* | list of extra files to link | a list of strings |
221
221
| | with (eg. object files not | |
222
222
| | implied by 'sources', static | |
223
223
| | library that must be | |
224
224
| | explicitly specified, binary | |
225
225
| | resource files, etc.) | |
226
226
+------------------------+--------------------------------+---------------------------+
227
| *extra_compile_args* | any extra platform- and | string |
227
| *extra_compile_args* | any extra platform- and | a list of strings |
228
228
| | compiler-specific information | |
229
229
| | to use when compiling the | |
230
230
| | source files in 'sources'. For | |
235
235
| | for other platforms it could | |
236
236
| | be anything. | |
237
237
+------------------------+--------------------------------+---------------------------+
238
| *extra_link_args* | any extra platform- and | string |
238
| *extra_link_args* | any extra platform- and | a list of strings |
239
239
| | compiler-specific information | |
240
240
| | to use when linking object | |
241
241
| | files together to create the | |
244
244
| | Similar interpretation as for | |
245
245
| | 'extra_compile_args'. | |
246
246
+------------------------+--------------------------------+---------------------------+
247
| *export_symbols* | list of symbols to be exported | string |
247
| *export_symbols* | list of symbols to be exported | a list of strings |
248
248
| | from a shared extension. Not | |
249
249
| | used on all platforms, and not | |
250
250
| | generally necessary for Python | |
252
252
| | export exactly one symbol: | |
253
253
| | ``init`` + extension_name. | |
254
254
+------------------------+--------------------------------+---------------------------+
255
| *depends* | list of files that the | string |
255
| *depends* | list of files that the | a list of strings |
256
256
| | extension depends on | |
257
257
+------------------------+--------------------------------+---------------------------+
258
| *language* | extension language (i.e. | string |
258
| *language* | extension language (i.e. | a string |
259
259
| | ``'c'``, ``'c++'``, | |
260
260
| | ``'objc'``). Will be detected | |
261
261
| | from the source extensions if | |
449
449
Define a preprocessor macro for all compilations driven by this compiler object.
450
450
The optional parameter *value* should be a string; if it is not supplied, then
451
451
the macro will be defined without an explicit value and the exact outcome
452
depends on the compiler used (XXX true? does ANSI say anything about this?)
452
depends on the compiler used.
454
.. XXX true? does ANSI say anything about this?
455
457
.. method:: CCompiler.undefine_macro(name)
604
606
*output_libname* should be a library name, not a filename; the filename will be
605
607
inferred from the library name. *output_dir* is the directory where the library
606
file will be put. XXX defaults to what?
610
.. XXX defaults to what?
608
612
*debug* is a boolean; if true, debugging information will be included in the
609
613
library (note that on most platforms, it is the compile step where this matters:
724
728
Invokes :func:`distutils.util.execute` This method invokes a Python function
725
729
*func* with the given arguments *args*, after logging and taking into account
726
the *dry_run* flag. XXX see also.
729
733
.. method:: CCompiler.spawn(cmd)
731
735
Invokes :func:`distutils.util.spawn`. This invokes an external process to run
732
the given command. XXX see also.
735
739
.. method:: CCompiler.mkpath(name[, mode=511])
737
741
Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any
738
missing ancestor directories. XXX see also.
742
missing ancestor directories.
741
745
.. method:: CCompiler.move_file(src, dst)
743
Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see
747
Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*.
747
750
.. method:: CCompiler.announce(msg[, level=1])
749
Write a message using :func:`distutils.log.debug`. XXX see also.
752
Write a message using :func:`distutils.log.debug`.
752
755
.. method:: CCompiler.warn(msg)
874
877
prefix of all files and directories in the archive. *root_dir* and *base_dir*
875
878
both default to the current directory. Returns the name of the archive file.
877
.. XXX This should be changed to support bz2 files.
880
881
.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
887
888
possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
888
889
or :file:`.Z`). Return the output filename.
890
.. XXX This should be replaced with calls to the :mod:`tarfile` module.
893
892
.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
1000
999
errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
1003
.. XXX Some of this could be replaced with the shutil module?
1006
1003
:mod:`distutils.file_util` --- Single file operations
1007
1004
=====================================================
1204
1199
.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
1206
1201
Byte-compile a collection of Python source files to either :file:`.pyc` or
1207
:file:`.pyo` files in the same directory. *py_files* is a list of files to
1208
compile; any files that don't end in :file:`.py` are silently skipped.
1209
*optimize* must be one of the following:
1202
:file:`.pyo` files in a :file:`__pycache__` subdirectory (see :pep:`3147`).
1203
*py_files* is a list of files to compile; any files that don't end in
1204
:file:`.py` are silently skipped. *optimize* must be one of the following:
1211
1206
* ``0`` - don't optimize (generate :file:`.pyc`)
1212
1207
* ``1`` - normal optimization (like ``python -O``)
1231
1226
is used by the script generated in indirect mode; unless you know what you're
1232
1227
doing, leave it set to ``None``.
1229
.. versionchanged:: 3.2.3
1230
Create ``.pyc`` or ``.pyo`` files with an :func:`import magic tag
1231
<imp.get_tag>` in their name, in a :file:`__pycache__` subdirectory
1232
instead of files without tag in the current directory.
1235
1235
.. function:: rfc822_escape(header)
1316
1316
the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
1317
1317
command line sets *verbose* to false.
1319
.. XXX Should be replaced with optparse
1321
1319
.. function:: fancy_getopt(options, negative_opt, object, args)
1323
1321
Wrapper function. *options* is a list of ``(long_option, short_option,
1398
1393
:synopsis: A simple logging mechanism, 282-style
1401
.. XXX Should be replaced with standard :mod:`logging` module.
1405
1396
:mod:`distutils.spawn` --- Spawn a sub-process
1406
1397
==============================================
1740
1731
Set final values for all the options that this command supports. This is
1741
1732
always called as late as possible, ie. after any option assignments from the
1742
1733
command-line or from other commands have been done. Thus, this is the place
1743
to to code option dependencies: if *foo* depends on *bar*, then it is safe to
1734
to code option dependencies: if *foo* depends on *bar*, then it is safe to
1744
1735
set *foo* from *bar* as long as *foo* still has the same value it was
1745
1736
assigned in :meth:`initialize_options`.