880801501b
The code I fixed to comply with PEP 3147 still had one bug: When run under python -O, some paths for pyc files would be pyo, because I called imp.cache_from_source without explicit debug_override argument in some places, and under -O that would return .pyo (this is well explained in the imp docs). Now all code (util.byte_compile, build_py, install_lib) can create .pyo files according to options given by users, without interference from the calling Python’s own optimize mode. On a related topic, I also removed the code that prevented byte compilation under python -B. The rationale is that packaging gives control over the creation of pyc files to the user with its own explicit option, and the behavior should not be changed if the calling Python happens to run with -B for whatever reason. I will argue that this is a bug fix and ask to be allowed to backport this change to distutils. Finally, I moved one nugget of information about the --compile and --optimize options from the source into the doc. It clears up a misunderstanding that I (and maybe other people) had.
375 lines
10 KiB
ReStructuredText
375 lines
10 KiB
ReStructuredText
.. _packaging-command-reference:
|
|
|
|
*****************
|
|
Command Reference
|
|
*****************
|
|
|
|
This reference briefly documents all standard Packaging commands and some of
|
|
their options.
|
|
|
|
.. FIXME does not work: Use pysetup run --help-commands to list all
|
|
standard and extra commands availavble on your system, with their
|
|
description. Use pysetup run <command> --help to get help about the options
|
|
of one command.
|
|
|
|
.. XXX sections from this document should be merged with other docs (e.g. check
|
|
and upload with uploading.rst, install_* with install/install.rst, etc.);
|
|
there is no value in partially duplicating information. this file could
|
|
however serve as an index, i.e. just a list of all commands with links to
|
|
every section that describes options or usage
|
|
|
|
|
|
Preparing distributions
|
|
=======================
|
|
|
|
:command:`check`
|
|
----------------
|
|
|
|
Perform some tests on the metadata of a distribution.
|
|
|
|
For example, it verifies that all required metadata fields are provided in the
|
|
:file:`setup.cfg` file.
|
|
|
|
.. TODO document reST checks
|
|
|
|
|
|
:command:`test`
|
|
---------------
|
|
|
|
Run a test suite.
|
|
|
|
When doing test-driven development, or running automated builds that need
|
|
testing before they are installed for downloading or use, it's often useful to
|
|
be able to run a project's unit tests without actually installing the project
|
|
anywhere. The :command:`test` command runs project's unit tests without
|
|
actually installing it, by temporarily putting the project's source on
|
|
:data:`sys.path`, after first running :command:`build_ext -i` to ensure that any
|
|
C extensions are built.
|
|
|
|
You can use this command in one of two ways: either by specifying a
|
|
unittest-compatible test suite for your project (or any callable that returns
|
|
it) or by passing a test runner function that will run your tests and display
|
|
results in the console. Both options take a Python dotted name in the form
|
|
``package.module.callable`` to specify the object to use.
|
|
|
|
If none of these options are specified, Packaging will try to perform test
|
|
discovery using either unittest (for Python 3.2 and higher) or unittest2 (for
|
|
older versions, if installed).
|
|
|
|
.. this is a pseudo-command name used to disambiguate the options in indexes and
|
|
links
|
|
.. program:: packaging test
|
|
|
|
.. cmdoption:: --suite=NAME, -s NAME
|
|
|
|
Specify the test suite (or module, class, or method) to be run. The default
|
|
for this option can be set by in the project's :file:`setup.cfg` file:
|
|
|
|
.. code-block:: cfg
|
|
|
|
[test]
|
|
suite = mypackage.tests.get_all_tests
|
|
|
|
.. cmdoption:: --runner=NAME, -r NAME
|
|
|
|
Specify the test runner to be called.
|
|
|
|
|
|
:command:`config`
|
|
-----------------
|
|
|
|
Perform distribution configuration.
|
|
|
|
|
|
The build step
|
|
==============
|
|
|
|
This step is mainly useful to compile C/C++ libraries or extension modules. The
|
|
build commands can be run manually to check for syntax errors or packaging
|
|
issues (for example if the addition of a new source file was forgotten in the
|
|
:file:`setup.cfg` file), and is also run automatically by commands which need
|
|
it. Packaging checks the mtime of source and built files to avoid re-building
|
|
if it's not necessary.
|
|
|
|
|
|
:command:`build`
|
|
----------------
|
|
|
|
Build all files of a distribution, delegating to the other :command:`build_*`
|
|
commands to do the work.
|
|
|
|
|
|
:command:`build_clib`
|
|
---------------------
|
|
|
|
Build C libraries.
|
|
|
|
|
|
:command:`build_ext`
|
|
--------------------
|
|
|
|
Build C/C++ extension modules.
|
|
|
|
|
|
:command:`build_py`
|
|
-------------------
|
|
|
|
Build the Python modules (just copy them to the build directory) and
|
|
:term:`byte-compile <bytecode>` them to :file:`.pyc` and/or :file:`.pyo` files.
|
|
|
|
The byte compilation is controlled by two sets of options:
|
|
|
|
- ``--compile`` and ``--no-compile`` are used to control the creation of
|
|
:file:`.pyc` files; the default is ``--no-compile``.
|
|
|
|
- ``--optimize N`` (or ``-ON``) is used to control the creation of :file:`.pyo`
|
|
files: ``-O1`` turns on basic optimizations, ``-O2`` also discards docstrings,
|
|
``-O0`` does not create :file:`.pyo` files; the default is ``-O0``.
|
|
|
|
You can mix and match these options: for example, ``--no-compile --optimize 2``
|
|
will create :file:`.pyo` files but no :file:`.pyc` files.
|
|
|
|
.. XXX these option roles do not work
|
|
|
|
Calling Python with :option:`-O` or :option:`-B` does not control the creation
|
|
of bytecode files, only the options described above do.
|
|
|
|
|
|
:command:`build_scripts`
|
|
------------------------
|
|
Build the scripts (just copy them to the build directory and adjust their
|
|
shebang if they're Python scripts).
|
|
|
|
|
|
:command:`clean`
|
|
----------------
|
|
|
|
Clean the build tree of the release.
|
|
|
|
.. program:: packaging clean
|
|
|
|
.. cmdoption:: --all, -a
|
|
|
|
Remove build directories for modules, scripts, etc., not only temporary build
|
|
by-products.
|
|
|
|
|
|
Creating source and built distributions
|
|
=======================================
|
|
|
|
:command:`sdist`
|
|
----------------
|
|
|
|
Build a source distribution for a release.
|
|
|
|
It is recommended that you always build and upload a source distribution. Users
|
|
of OSes with easy access to compilers and users of advanced packaging tools will
|
|
prefer to compile from source rather than using pre-built distributions. For
|
|
Windows users, providing a binary installer is also recommended practice.
|
|
|
|
|
|
:command:`bdist`
|
|
----------------
|
|
|
|
Build a binary distribution for a release.
|
|
|
|
This command will call other :command:`bdist_*` commands to create one or more
|
|
distributions depending on the options given. The default is to create a
|
|
.tar.gz archive on Unix and a zip archive on Windows or OS/2.
|
|
|
|
.. program:: packaging bdist
|
|
|
|
.. cmdoption:: --formats
|
|
|
|
Binary formats to build (comma-separated list).
|
|
|
|
.. cmdoption:: --show-formats
|
|
|
|
Dump list of available formats.
|
|
|
|
|
|
:command:`bdist_dumb`
|
|
---------------------
|
|
|
|
Build a "dumb" installer, a simple archive of files that could be unpacked under
|
|
``$prefix`` or ``$exec_prefix``.
|
|
|
|
|
|
:command:`bdist_wininst`
|
|
------------------------
|
|
|
|
Build a Windows installer.
|
|
|
|
|
|
:command:`bdist_msi`
|
|
--------------------
|
|
|
|
Build a `Microsoft Installer`_ (.msi) file.
|
|
|
|
.. _Microsoft Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
|
|
|
|
In most cases, the :command:`bdist_msi` installer is a better choice than the
|
|
:command:`bdist_wininst` installer, because it provides better support for Win64
|
|
platforms, allows administrators to perform non-interactive installations, and
|
|
allows installation through group policies.
|
|
|
|
|
|
Publishing distributions
|
|
========================
|
|
|
|
:command:`register`
|
|
-------------------
|
|
|
|
This command registers the current release with the Python Package Index. This
|
|
is described in more detail in :PEP:`301`.
|
|
|
|
.. TODO explain user and project registration with the web UI
|
|
|
|
|
|
:command:`upload`
|
|
-----------------
|
|
|
|
Upload source and/or binary distributions to PyPI.
|
|
|
|
The distributions have to be built on the same command line as the
|
|
:command:`upload` command; see :ref:`packaging-package-upload` for more info.
|
|
|
|
.. program:: packaging upload
|
|
|
|
.. cmdoption:: --sign, -s
|
|
|
|
Sign each uploaded file using GPG (GNU Privacy Guard). The ``gpg`` program
|
|
must be available for execution on the system ``PATH``.
|
|
|
|
.. cmdoption:: --identity=NAME, -i NAME
|
|
|
|
Specify the identity or key name for GPG to use when signing. The value of
|
|
this option will be passed through the ``--local-user`` option of the
|
|
``gpg`` program.
|
|
|
|
.. cmdoption:: --show-response
|
|
|
|
Display the full response text from server; this is useful for debugging
|
|
PyPI problems.
|
|
|
|
.. cmdoption:: --repository=URL, -r URL
|
|
|
|
The URL of the repository to upload to. Defaults to
|
|
http://pypi.python.org/pypi (i.e., the main PyPI installation).
|
|
|
|
.. cmdoption:: --upload-docs
|
|
|
|
Also run :command:`upload_docs`. Mainly useful as a default value in
|
|
:file:`setup.cfg` (on the command line, it's shorter to just type both
|
|
commands).
|
|
|
|
|
|
:command:`upload_docs`
|
|
----------------------
|
|
|
|
Upload HTML documentation to PyPI.
|
|
|
|
PyPI now supports publishing project documentation at a URI of the form
|
|
``http://packages.python.org/<project>``. :command:`upload_docs` will create
|
|
the necessary zip file out of a documentation directory and will post to the
|
|
repository.
|
|
|
|
Note that to upload the documentation of a project, the corresponding version
|
|
must already be registered with PyPI, using the :command:`register` command ---
|
|
just like with :command:`upload`.
|
|
|
|
Assuming there is an ``Example`` project with documentation in the subdirectory
|
|
:file:`docs`, for example::
|
|
|
|
Example/
|
|
example.py
|
|
setup.cfg
|
|
docs/
|
|
build/
|
|
html/
|
|
index.html
|
|
tips_tricks.html
|
|
conf.py
|
|
index.txt
|
|
tips_tricks.txt
|
|
|
|
You can simply specify the directory with the HTML files in your
|
|
:file:`setup.cfg` file:
|
|
|
|
.. code-block:: cfg
|
|
|
|
[upload_docs]
|
|
upload-dir = docs/build/html
|
|
|
|
|
|
.. program:: packaging upload_docs
|
|
|
|
.. cmdoption:: --upload-dir
|
|
|
|
The directory to be uploaded to the repository. By default documentation
|
|
is searched for in ``docs`` (or ``doc``) directory in project root.
|
|
|
|
.. cmdoption:: --show-response
|
|
|
|
Display the full response text from server; this is useful for debugging
|
|
PyPI problems.
|
|
|
|
.. cmdoption:: --repository=URL, -r URL
|
|
|
|
The URL of the repository to upload to. Defaults to
|
|
http://pypi.python.org/pypi (i.e., the main PyPI installation).
|
|
|
|
|
|
The install step
|
|
================
|
|
|
|
These commands are used by end-users of a project using :program:`pysetup` or
|
|
another compatible installer. Each command will run the corresponding
|
|
:command:`build_*` command and then move the built files to their destination on
|
|
the target system.
|
|
|
|
|
|
:command:`install_dist`
|
|
-----------------------
|
|
|
|
Install a distribution, delegating to the other :command:`install_*` commands to
|
|
do the work. See :ref:`packaging-how-install-works` for complete usage
|
|
instructions.
|
|
|
|
|
|
:command:`install_data`
|
|
-----------------------
|
|
|
|
Install data files.
|
|
|
|
|
|
:command:`install_distinfo`
|
|
---------------------------
|
|
|
|
Install files recording details of the installation as specified in :PEP:`376`.
|
|
|
|
|
|
:command:`install_headers`
|
|
--------------------------
|
|
|
|
Install C/C++ header files.
|
|
|
|
|
|
:command:`install_lib`
|
|
----------------------
|
|
|
|
Install all modules (extensions and pure Python).
|
|
|
|
.. XXX what about C libraries created with build_clib?
|
|
|
|
Similarly to ``build_py``, there are options to control the compilation of
|
|
Python code to :term:`bytecode` files (see above). By default, :file:`.pyc`
|
|
files will be created (``--compile``) and :file:`.pyo` files will not
|
|
(``--optimize 0``).
|
|
|
|
|
|
:command:`install_scripts`
|
|
--------------------------
|
|
|
|
Install scripts.
|