reverted distutils doc to its 3.1 state
This commit is contained in:
parent
b00a75f175
commit
96c45a984f
|
@ -21,9 +21,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
|
||||||
.. function:: setup(arguments)
|
.. function:: setup(arguments)
|
||||||
|
|
||||||
The basic do-everything function that does most everything you could ever ask
|
The basic do-everything function that does most everything you could ever ask
|
||||||
for from a Distutils method.
|
for from a Distutils method. See XXXXX
|
||||||
|
|
||||||
.. See XXXXX
|
|
||||||
|
|
||||||
The setup function takes a large number of arguments. These are laid out in the
|
The setup function takes a large number of arguments. These are laid out in the
|
||||||
following table.
|
following table.
|
||||||
|
@ -149,11 +147,11 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
|
||||||
In addition, the :mod:`distutils.core` module exposed a number of classes that
|
In addition, the :mod:`distutils.core` module exposed a number of classes that
|
||||||
live elsewhere.
|
live elsewhere.
|
||||||
|
|
||||||
* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
|
* :class:`Extension` from :mod:`distutils.extension`
|
||||||
|
|
||||||
* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
|
* :class:`Command` from :mod:`distutils.cmd`
|
||||||
|
|
||||||
* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
|
* :class:`Distribution` from :mod:`distutils.dist`
|
||||||
|
|
||||||
A short description of each of these follows, but see the relevant module for
|
A short description of each of these follows, but see the relevant module for
|
||||||
the full reference.
|
the full reference.
|
||||||
|
@ -997,7 +995,7 @@ directories.
|
||||||
errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
|
errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
|
||||||
true).
|
true).
|
||||||
|
|
||||||
.. XXX Some of this could be replaced with the shutil module?
|
**\*\*** Some of this could be replaced with the shutil module? **\*\***
|
||||||
|
|
||||||
|
|
||||||
:mod:`distutils.file_util` --- Single file operations
|
:mod:`distutils.file_util` --- Single file operations
|
||||||
|
@ -1313,7 +1311,8 @@ provides the following additional features:
|
||||||
the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
|
the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
|
||||||
command line sets *verbose* to false.
|
command line sets *verbose* to false.
|
||||||
|
|
||||||
.. XXX Should be replaced with :mod:`optparse`.
|
**\*\*** Should be replaced with :mod:`optik` (which is also now known as
|
||||||
|
:mod:`optparse` in Python 2.3 and later). **\*\***
|
||||||
|
|
||||||
|
|
||||||
.. function:: fancy_getopt(options, negative_opt, object, args)
|
.. function:: fancy_getopt(options, negative_opt, object, args)
|
||||||
|
@ -1681,8 +1680,8 @@ lines, and joining lines with backslashes.
|
||||||
===================================================================
|
===================================================================
|
||||||
|
|
||||||
.. module:: distutils.cmd
|
.. module:: distutils.cmd
|
||||||
:synopsis: This module provides the abstract base class Command. This class
|
:synopsis: This module provides the abstract base class Command. This class is subclassed
|
||||||
is subclassed by the modules in the distutils.command subpackage.
|
by the modules in the distutils.command subpackage.
|
||||||
|
|
||||||
|
|
||||||
This module supplies the abstract base class :class:`Command`.
|
This module supplies the abstract base class :class:`Command`.
|
||||||
|
@ -1692,84 +1691,20 @@ This module supplies the abstract base class :class:`Command`.
|
||||||
|
|
||||||
Abstract base class for defining command classes, the "worker bees" of the
|
Abstract base class for defining command classes, the "worker bees" of the
|
||||||
Distutils. A useful analogy for command classes is to think of them as
|
Distutils. A useful analogy for command classes is to think of them as
|
||||||
subroutines with local variables called *options*. The options are declared
|
subroutines with local variables called *options*. The options are declared in
|
||||||
in :meth:`initialize_options` and defined (given their final values) in
|
:meth:`initialize_options` and defined (given their final values) in
|
||||||
:meth:`finalize_options`, both of which must be defined by every command
|
:meth:`finalize_options`, both of which must be defined by every command class.
|
||||||
class. The distinction between the two is necessary because option values
|
The distinction between the two is necessary because option values might come
|
||||||
might come from the outside world (command line, config file, ...), and any
|
from the outside world (command line, config file, ...), and any options
|
||||||
options dependent on other options must be computed after these outside
|
dependent on other options must be computed after these outside influences have
|
||||||
influences have been processed --- hence :meth:`finalize_options`. The body
|
been processed --- hence :meth:`finalize_options`. The body of the subroutine,
|
||||||
of the subroutine, where it does all its work based on the values of its
|
where it does all its work based on the values of its options, is the
|
||||||
options, is the :meth:`run` method, which must also be implemented by every
|
:meth:`run` method, which must also be implemented by every command class.
|
||||||
command class.
|
|
||||||
|
|
||||||
The class constructor takes a single argument *dist*, a :class:`Distribution`
|
The class constructor takes a single argument *dist*, a :class:`Distribution`
|
||||||
instance.
|
instance.
|
||||||
|
|
||||||
|
|
||||||
Creating a new Distutils command
|
|
||||||
================================
|
|
||||||
|
|
||||||
This section outlines the steps to create a new Distutils command.
|
|
||||||
|
|
||||||
A new command lives in a module in the :mod:`distutils.command` package. There
|
|
||||||
is a sample template in that directory called :file:`command_template`. Copy
|
|
||||||
this file to a new module with the same name as the new command you're
|
|
||||||
implementing. This module should implement a class with the same name as the
|
|
||||||
module (and the command). So, for instance, to create the command
|
|
||||||
``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
|
|
||||||
:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
|
|
||||||
it so that it's implementing the class :class:`peel_banana`, a subclass of
|
|
||||||
:class:`distutils.cmd.Command`.
|
|
||||||
|
|
||||||
Subclasses of :class:`Command` must define the following methods.
|
|
||||||
|
|
||||||
.. method:: Command.initialize_options()
|
|
||||||
|
|
||||||
Set default values for all the options that this command supports. Note that
|
|
||||||
these defaults may be overridden by other commands, by the setup script, by
|
|
||||||
config files, or by the command-line. Thus, this is not the place to code
|
|
||||||
dependencies between options; generally, :meth:`initialize_options`
|
|
||||||
implementations are just a bunch of ``self.foo = None`` assignments.
|
|
||||||
|
|
||||||
|
|
||||||
.. method:: Command.finalize_options()
|
|
||||||
|
|
||||||
Set final values for all the options that this command supports. This is
|
|
||||||
always called as late as possible, ie. after any option assignments from the
|
|
||||||
command-line or from other commands have been done. Thus, this is the place
|
|
||||||
to to code option dependencies: if *foo* depends on *bar*, then it is safe to
|
|
||||||
set *foo* from *bar* as long as *foo* still has the same value it was
|
|
||||||
assigned in :meth:`initialize_options`.
|
|
||||||
|
|
||||||
|
|
||||||
.. method:: Command.run()
|
|
||||||
|
|
||||||
A command's raison d'etre: carry out the action it exists to perform,
|
|
||||||
controlled by the options initialized in :meth:`initialize_options`,
|
|
||||||
customized by other commands, the setup script, the command-line, and config
|
|
||||||
files, and finalized in :meth:`finalize_options`. All terminal output and
|
|
||||||
filesystem interaction should be done by :meth:`run`.
|
|
||||||
|
|
||||||
|
|
||||||
.. attribute:: Command.sub_commands
|
|
||||||
|
|
||||||
*sub_commands* formalizes the notion of a "family" of commands,
|
|
||||||
e.g. ``install`` as the parent with sub-commands ``install_lib``,
|
|
||||||
``install_headers``, etc. The parent of a family of commands defines
|
|
||||||
*sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
|
|
||||||
predicate)``, with *command_name* a string and *predicate* a function, a
|
|
||||||
string or ``None``. *predicate* is a method of the parent command that
|
|
||||||
determines whether the corresponding command is applicable in the current
|
|
||||||
situation. (E.g. we ``install_headers`` is only applicable if we have any C
|
|
||||||
header files to install.) If *predicate* is ``None``, that command is always
|
|
||||||
applicable.
|
|
||||||
|
|
||||||
*sub_commands* is usually defined at the *end* of a class, because
|
|
||||||
predicates can be methods of the class, so they must already have been
|
|
||||||
defined. The canonical example is the :command:`install` command.
|
|
||||||
|
|
||||||
|
|
||||||
:mod:`distutils.command` --- Individual Distutils commands
|
:mod:`distutils.command` --- Individual Distutils commands
|
||||||
==========================================================
|
==========================================================
|
||||||
|
|
||||||
|
@ -2008,3 +1943,76 @@ The ``register`` command registers the package with the Python Package Index.
|
||||||
This is described in more detail in :pep:`301`.
|
This is described in more detail in :pep:`301`.
|
||||||
|
|
||||||
.. % todo
|
.. % todo
|
||||||
|
|
||||||
|
:mod:`distutils.command.check` --- Check the meta-data of a package
|
||||||
|
===================================================================
|
||||||
|
|
||||||
|
.. module:: distutils.command.check
|
||||||
|
:synopsis: Check the metadata of a package
|
||||||
|
|
||||||
|
|
||||||
|
The ``check`` command performs some tests on the meta-data of a package.
|
||||||
|
For example, it verifies that all required meta-data are provided as
|
||||||
|
the arguments passed to the :func:`setup` function.
|
||||||
|
|
||||||
|
.. % todo
|
||||||
|
|
||||||
|
|
||||||
|
Creating a new Distutils command
|
||||||
|
================================
|
||||||
|
|
||||||
|
This section outlines the steps to create a new Distutils command.
|
||||||
|
|
||||||
|
A new command lives in a module in the :mod:`distutils.command` package. There
|
||||||
|
is a sample template in that directory called :file:`command_template`. Copy
|
||||||
|
this file to a new module with the same name as the new command you're
|
||||||
|
implementing. This module should implement a class with the same name as the
|
||||||
|
module (and the command). So, for instance, to create the command
|
||||||
|
``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
|
||||||
|
:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
|
||||||
|
it so that it's implementing the class :class:`peel_banana`, a subclass of
|
||||||
|
:class:`distutils.cmd.Command`.
|
||||||
|
|
||||||
|
Subclasses of :class:`Command` must define the following methods.
|
||||||
|
|
||||||
|
|
||||||
|
.. method:: Command.initialize_options()
|
||||||
|
|
||||||
|
Set default values for all the options that this command supports. Note that
|
||||||
|
these defaults may be overridden by other commands, by the setup script, by
|
||||||
|
config files, or by the command-line. Thus, this is not the place to code
|
||||||
|
dependencies between options; generally, :meth:`initialize_options`
|
||||||
|
implementations are just a bunch of ``self.foo = None`` assignments.
|
||||||
|
|
||||||
|
|
||||||
|
.. method:: Command.finalize_options()
|
||||||
|
|
||||||
|
Set final values for all the options that this command supports. This is
|
||||||
|
always called as late as possible, ie. after any option assignments from the
|
||||||
|
command-line or from other commands have been done. Thus, this is the place
|
||||||
|
to to code option dependencies: if *foo* depends on *bar*, then it is safe to
|
||||||
|
set *foo* from *bar* as long as *foo* still has the same value it was
|
||||||
|
assigned in :meth:`initialize_options`.
|
||||||
|
|
||||||
|
|
||||||
|
.. method:: Command.run()
|
||||||
|
|
||||||
|
A command's raison d'etre: carry out the action it exists to perform, controlled
|
||||||
|
by the options initialized in :meth:`initialize_options`, customized by other
|
||||||
|
commands, the setup script, the command-line, and config files, and finalized in
|
||||||
|
:meth:`finalize_options`. All terminal output and filesystem interaction should
|
||||||
|
be done by :meth:`run`.
|
||||||
|
|
||||||
|
*sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
|
||||||
|
as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The
|
||||||
|
parent of a family of commands defines *sub_commands* as a class attribute; it's
|
||||||
|
a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
|
||||||
|
and *predicate* a function, a string or None. *predicate* is a method of
|
||||||
|
the parent command that determines whether the corresponding command is
|
||||||
|
applicable in the current situation. (Eg. we ``install_headers`` is only
|
||||||
|
applicable if we have any C header files to install.) If *predicate* is None,
|
||||||
|
that command is always applicable.
|
||||||
|
|
||||||
|
*sub_commands* is usually defined at the \*end\* of a class, because predicates
|
||||||
|
can be methods of the class, so they must already have been defined. The
|
||||||
|
canonical example is the :command:`install` command.
|
||||||
|
|
|
@ -146,8 +146,8 @@ commands.
|
||||||
Creating dumb built distributions
|
Creating dumb built distributions
|
||||||
=================================
|
=================================
|
||||||
|
|
||||||
.. XXX Need to document absolute vs. prefix-relative packages here, but first
|
**\*\*** Need to document absolute vs. prefix-relative packages here, but first
|
||||||
I have to implement it!
|
I have to implement it! **\*\***
|
||||||
|
|
||||||
|
|
||||||
.. _creating-rpms:
|
.. _creating-rpms:
|
||||||
|
@ -241,8 +241,7 @@ tedious and error-prone, so it's usually best to put them in the setup
|
||||||
configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If
|
configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If
|
||||||
you distribute or package many Python module distributions, you might want to
|
you distribute or package many Python module distributions, you might want to
|
||||||
put options that apply to all of them in your personal Distutils configuration
|
put options that apply to all of them in your personal Distutils configuration
|
||||||
file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable
|
file (:file:`~/.pydistutils.cfg`).
|
||||||
this file, you can pass the --no-user-cfg option to setup.py.
|
|
||||||
|
|
||||||
There are three steps to building a binary RPM package, all of which are
|
There are three steps to building a binary RPM package, all of which are
|
||||||
handled automatically by the Distutils:
|
handled automatically by the Distutils:
|
||||||
|
|
|
@ -48,6 +48,50 @@ This command installs all (Python) scripts in the distribution.
|
||||||
.. % \label{clean-cmd}
|
.. % \label{clean-cmd}
|
||||||
|
|
||||||
|
|
||||||
|
.. _sdist-cmd:
|
||||||
|
|
||||||
|
Creating a source distribution: the :command:`sdist` command
|
||||||
|
============================================================
|
||||||
|
|
||||||
|
**\*\*** fragment moved down from above: needs context! **\*\***
|
||||||
|
|
||||||
|
The manifest template commands are:
|
||||||
|
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| Command | Description |
|
||||||
|
+===========================================+===============================================+
|
||||||
|
| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
|
||||||
|
| | patterns |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
|
||||||
|
| | patterns |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
|
||||||
|
| ...` | the listed patterns |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
|
||||||
|
| ...` | the listed patterns |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
|
||||||
|
| | matching --- & any of the listed patterns |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
|
||||||
|
| | matching --- & any of the listed patterns |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| :command:`prune dir` | exclude all files under *dir* |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| :command:`graft dir` | include all files under *dir* |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
|
||||||
|
The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
|
||||||
|
regular filename characters, ``?`` matches any single regular filename
|
||||||
|
character, and ``[range]`` matches any of the characters in *range* (e.g.,
|
||||||
|
``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename
|
||||||
|
character" is platform-specific: on Unix it is anything except slash; on Windows
|
||||||
|
anything except backslash or colon.
|
||||||
|
|
||||||
|
**\*\*** Windows support not there yet **\*\***
|
||||||
|
|
||||||
.. % \section{Creating a built distribution: the
|
.. % \section{Creating a built distribution: the
|
||||||
.. % \protect\command{bdist} command family}
|
.. % \protect\command{bdist} command family}
|
||||||
.. % \label{bdist-cmds}
|
.. % \label{bdist-cmds}
|
||||||
|
|
|
@ -233,6 +233,58 @@ With exactly the same source tree layout, this extension can be put in the
|
||||||
ext_modules=[Extension('foopkg.foo', ['foo.c'])],
|
ext_modules=[Extension('foopkg.foo', ['foo.c'])],
|
||||||
)
|
)
|
||||||
|
|
||||||
|
Checking a package
|
||||||
|
==================
|
||||||
|
|
||||||
|
The ``check`` command allows you to verify if your package meta-data
|
||||||
|
meet the minimum requirements to build a distribution.
|
||||||
|
|
||||||
|
To run it, just call it using your :file:`setup.py` script. If something is
|
||||||
|
missing, ``check`` will display a warning.
|
||||||
|
|
||||||
|
Let's take an example with a simple script::
|
||||||
|
|
||||||
|
from distutils.core import setup
|
||||||
|
|
||||||
|
setup(name='foobar')
|
||||||
|
|
||||||
|
Running the ``check`` command will display some warnings::
|
||||||
|
|
||||||
|
$ python setup.py check
|
||||||
|
running check
|
||||||
|
warning: check: missing required meta-data: version, url
|
||||||
|
warning: check: missing meta-data: either (author and author_email) or
|
||||||
|
(maintainer and maintainer_email) must be supplied
|
||||||
|
|
||||||
|
|
||||||
|
If you use the reStructuredText syntax in the `long_description` field and
|
||||||
|
`docutils <http://docutils.sourceforge.net/>`_ is installed you can check if
|
||||||
|
the syntax is fine with the ``check`` command, using the `restructuredtext`
|
||||||
|
option.
|
||||||
|
|
||||||
|
For example, if the :file:`setup.py` script is changed like this::
|
||||||
|
|
||||||
|
from distutils.core import setup
|
||||||
|
|
||||||
|
desc = """\
|
||||||
|
My description
|
||||||
|
=============
|
||||||
|
|
||||||
|
This is the description of the ``foobar`` package.
|
||||||
|
"""
|
||||||
|
|
||||||
|
setup(name='foobar', version='1', author='tarek',
|
||||||
|
author_email='tarek@ziade.org',
|
||||||
|
url='http://example.com', long_description=desc)
|
||||||
|
|
||||||
|
Where the long description is broken, ``check`` will be able to detect it
|
||||||
|
by using the `docutils` parser::
|
||||||
|
|
||||||
|
$ pythontrunk setup.py check --restructuredtext
|
||||||
|
running check
|
||||||
|
warning: check: Title underline too short. (line 2)
|
||||||
|
warning: check: Could not finish the parsing.
|
||||||
|
|
||||||
.. % \section{Multiple extension modules}
|
.. % \section{Multiple extension modules}
|
||||||
.. % \label{multiple-ext}
|
.. % \label{multiple-ext}
|
||||||
|
|
||||||
|
|
|
@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that
|
||||||
should be copied into packages in addition to :file:`.py` files as a
|
should be copied into packages in addition to :file:`.py` files as a
|
||||||
convenience.
|
convenience.
|
||||||
|
|
||||||
Most distutils command implementations are subclasses of the
|
Most distutils command implementations are subclasses of the :class:`Command`
|
||||||
:class:`distutils.cmd.Command` class. New commands may directly inherit from
|
class from :mod:`distutils.cmd`. New commands may directly inherit from
|
||||||
:class:`Command`, while replacements often derive from :class:`Command`
|
:class:`Command`, while replacements often derive from :class:`Command`
|
||||||
indirectly, directly subclassing the command they are replacing. Commands are
|
indirectly, directly subclassing the command they are replacing. Commands are
|
||||||
required to derive from :class:`Command`.
|
required to derive from :class:`Command`.
|
||||||
|
|
|
@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the
|
||||||
SWIG on the interface file and compile the resulting C/C++ file into your
|
SWIG on the interface file and compile the resulting C/C++ file into your
|
||||||
extension.
|
extension.
|
||||||
|
|
||||||
.. XXX SWIG support is rough around the edges and largely untested!
|
**\*\*** SWIG support is rough around the edges and largely untested! **\*\***
|
||||||
|
|
||||||
This warning notwithstanding, options to SWIG can be currently passed like
|
This warning notwithstanding, options to SWIG can be currently passed like
|
||||||
this::
|
this::
|
||||||
|
@ -326,7 +326,7 @@ include the location in ``library_dirs``::
|
||||||
(Again, this sort of non-portable construct should be avoided if you intend to
|
(Again, this sort of non-portable construct should be avoided if you intend to
|
||||||
distribute your code.)
|
distribute your code.)
|
||||||
|
|
||||||
.. XXX Should mention clib libraries here or somewhere else!
|
**\*\*** Should mention clib libraries here or somewhere else! **\*\***
|
||||||
|
|
||||||
|
|
||||||
Other options
|
Other options
|
||||||
|
|
|
@ -26,16 +26,16 @@ to create a gzipped tarball and a zip file. The available formats are:
|
||||||
+===========+=========================+=========+
|
+===========+=========================+=========+
|
||||||
| ``zip`` | zip file (:file:`.zip`) | (1),(3) |
|
| ``zip`` | zip file (:file:`.zip`) | (1),(3) |
|
||||||
+-----------+-------------------------+---------+
|
+-----------+-------------------------+---------+
|
||||||
| ``gztar`` | gzip'ed tar file | \(2) |
|
| ``gztar`` | gzip'ed tar file | (2),(4) |
|
||||||
| | (:file:`.tar.gz`) | |
|
| | (:file:`.tar.gz`) | |
|
||||||
+-----------+-------------------------+---------+
|
+-----------+-------------------------+---------+
|
||||||
| ``bztar`` | bzip2'ed tar file | |
|
| ``bztar`` | bzip2'ed tar file | \(4) |
|
||||||
| | (:file:`.tar.bz2`) | |
|
| | (:file:`.tar.bz2`) | |
|
||||||
+-----------+-------------------------+---------+
|
+-----------+-------------------------+---------+
|
||||||
| ``ztar`` | compressed tar file | \(4) |
|
| ``ztar`` | compressed tar file | \(4) |
|
||||||
| | (:file:`.tar.Z`) | |
|
| | (:file:`.tar.Z`) | |
|
||||||
+-----------+-------------------------+---------+
|
+-----------+-------------------------+---------+
|
||||||
| ``tar`` | tar file (:file:`.tar`) | |
|
| ``tar`` | tar file (:file:`.tar`) | \(4) |
|
||||||
+-----------+-------------------------+---------+
|
+-----------+-------------------------+---------+
|
||||||
|
|
||||||
Notes:
|
Notes:
|
||||||
|
@ -51,16 +51,8 @@ Notes:
|
||||||
of the standard Python library since Python 1.6)
|
of the standard Python library since Python 1.6)
|
||||||
|
|
||||||
(4)
|
(4)
|
||||||
requires the :program:`compress` program. Notice that this format is now
|
requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
|
||||||
pending for deprecation and will be removed in the future versions of Python.
|
:program:`bzip2`, or :program:`compress`
|
||||||
|
|
||||||
When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or
|
|
||||||
``tar``) under Unix, you can specify the ``owner`` and ``group`` names
|
|
||||||
that will be set for each member of the archive.
|
|
||||||
|
|
||||||
For example, if you want all files of the archive to be owned by root::
|
|
||||||
|
|
||||||
python setup.py sdist --owner=root --group=root
|
|
||||||
|
|
||||||
|
|
||||||
.. _manifest:
|
.. _manifest:
|
||||||
|
@ -76,10 +68,10 @@ source distribution:
|
||||||
:option:`packages` options
|
:option:`packages` options
|
||||||
|
|
||||||
* all C source files mentioned in the :option:`ext_modules` or
|
* all C source files mentioned in the :option:`ext_modules` or
|
||||||
:option:`libraries` options
|
:option:`libraries` options (
|
||||||
|
|
||||||
.. XXX Getting C library sources is currently broken -- no
|
**\*\*** getting C library sources currently broken---no
|
||||||
:meth:`get_source_files` method in :file:`build_clib.py`!
|
:meth:`get_source_files` method in :file:`build_clib.py`! **\*\***)
|
||||||
|
|
||||||
* scripts identified by the :option:`scripts` option
|
* scripts identified by the :option:`scripts` option
|
||||||
See :ref:`distutils-installing-scripts`.
|
See :ref:`distutils-installing-scripts`.
|
||||||
|
@ -111,60 +103,9 @@ per line, regular files (or symlinks to them) only. If you do supply your own
|
||||||
:file:`MANIFEST`, you must specify everything: the default set of files
|
:file:`MANIFEST`, you must specify everything: the default set of files
|
||||||
described above does not apply in this case.
|
described above does not apply in this case.
|
||||||
|
|
||||||
See :ref:`manifest_template` section for a syntax reference.
|
|
||||||
|
|
||||||
.. _manifest-options:
|
|
||||||
|
|
||||||
Manifest-related options
|
|
||||||
========================
|
|
||||||
|
|
||||||
The normal course of operations for the :command:`sdist` command is as follows:
|
|
||||||
|
|
||||||
* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
|
|
||||||
and create the manifest
|
|
||||||
|
|
||||||
* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
|
|
||||||
with just the default file set
|
|
||||||
|
|
||||||
* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
|
|
||||||
recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
|
|
||||||
:file:`MANIFEST.in`
|
|
||||||
|
|
||||||
* use the list of files now in :file:`MANIFEST` (either just generated or read
|
|
||||||
in) to create the source distribution archive(s)
|
|
||||||
|
|
||||||
There are a couple of options that modify this behaviour. First, use the
|
|
||||||
:option:`--no-defaults` and :option:`--no-prune` to disable the standard
|
|
||||||
"include" and "exclude" sets.
|
|
||||||
|
|
||||||
Second, you might just want to (re)generate the manifest, but not create a
|
|
||||||
source distribution::
|
|
||||||
|
|
||||||
python setup.py sdist --manifest-only
|
|
||||||
|
|
||||||
:option:`-o` is a sortcut for :option:`--manifest-only`.
|
|
||||||
|
|
||||||
.. _manifest_template:
|
|
||||||
|
|
||||||
The MANIFEST.in template
|
|
||||||
========================
|
|
||||||
|
|
||||||
A :file:`MANIFEST.in` file can be added in a project to define the list of
|
|
||||||
files to include in the distribution built by the :command:`sdist` command.
|
|
||||||
|
|
||||||
When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file
|
|
||||||
and interpret it to generate the :file:`MANIFEST` file that contains the
|
|
||||||
list of files that will be included in the package.
|
|
||||||
|
|
||||||
This mechanism can be used when the default list of files is not enough.
|
|
||||||
(See :ref:`manifest`).
|
|
||||||
|
|
||||||
Principle
|
|
||||||
---------
|
|
||||||
|
|
||||||
The manifest template has one command per line, where each command specifies a
|
The manifest template has one command per line, where each command specifies a
|
||||||
set of files to include or exclude from the source distribution. For an
|
set of files to include or exclude from the source distribution. For an
|
||||||
example, let's look at the Distutils' own manifest template::
|
example, again we turn to the Distutils' own manifest template::
|
||||||
|
|
||||||
include *.txt
|
include *.txt
|
||||||
recursive-include examples *.txt *.py
|
recursive-include examples *.txt *.py
|
||||||
|
@ -176,7 +117,9 @@ matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
|
||||||
:file:`examples/sample?/build`. All of this is done *after* the standard
|
:file:`examples/sample?/build`. All of this is done *after* the standard
|
||||||
include set, so you can exclude files from the standard set with explicit
|
include set, so you can exclude files from the standard set with explicit
|
||||||
instructions in the manifest template. (Or, you can use the
|
instructions in the manifest template. (Or, you can use the
|
||||||
:option:`--no-defaults` option to disable the standard set entirely.)
|
:option:`--no-defaults` option to disable the standard set entirely.) There are
|
||||||
|
several other commands available in the manifest template mini-language; see
|
||||||
|
section :ref:`sdist-cmd`.
|
||||||
|
|
||||||
The order of commands in the manifest template matters: initially, we have the
|
The order of commands in the manifest template matters: initially, we have the
|
||||||
list of default files as described above, and each command in the template adds
|
list of default files as described above, and each command in the template adds
|
||||||
|
@ -230,41 +173,36 @@ should always be slash-separated; the Distutils will take care of converting
|
||||||
them to the standard representation on your platform. That way, the manifest
|
them to the standard representation on your platform. That way, the manifest
|
||||||
template is portable across operating systems.
|
template is portable across operating systems.
|
||||||
|
|
||||||
Commands
|
|
||||||
--------
|
|
||||||
|
|
||||||
The manifest template commands are:
|
.. _manifest-options:
|
||||||
|
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
Manifest-related options
|
||||||
| Command | Description |
|
========================
|
||||||
+===========================================+===============================================+
|
|
||||||
| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
|
The normal course of operations for the :command:`sdist` command is as follows:
|
||||||
| | patterns |
|
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
|
||||||
| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
|
and create the manifest
|
||||||
| | patterns |
|
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
|
||||||
| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
|
with just the default file set
|
||||||
| ...` | the listed patterns |
|
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
|
||||||
| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
|
recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
|
||||||
| ...` | the listed patterns |
|
:file:`MANIFEST.in`
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
|
||||||
| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
|
* use the list of files now in :file:`MANIFEST` (either just generated or read
|
||||||
| | matching --- & any of the listed patterns |
|
in) to create the source distribution archive(s)
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
|
||||||
| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
|
There are a couple of options that modify this behaviour. First, use the
|
||||||
| | matching --- & any of the listed patterns |
|
:option:`--no-defaults` and :option:`--no-prune` to disable the standard
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
"include" and "exclude" sets.
|
||||||
| :command:`prune dir` | exclude all files under *dir* |
|
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
Second, you might just want to (re)generate the manifest, but not create a source
|
||||||
| :command:`graft dir` | include all files under *dir* |
|
distribution::
|
||||||
+-------------------------------------------+-----------------------------------------------+
|
|
||||||
|
python setup.py sdist --manifest-only
|
||||||
|
|
||||||
|
:option:`-o` is a shortcut for :option:`--manifest-only`.
|
||||||
|
|
||||||
The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
|
|
||||||
regular filename characters, ``?`` matches any single regular filename
|
|
||||||
character, and ``[range]`` matches any of the characters in *range* (e.g.,
|
|
||||||
``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename
|
|
||||||
character" is platform-specific: on Unix it is anything except slash; on Windows
|
|
||||||
anything except backslash or colon.
|
|
||||||
|
|
||||||
|
|
|
@ -60,13 +60,13 @@ in the package::
|
||||||
setup(name='Distutils',
|
setup(name='Distutils',
|
||||||
long_description=open('README.txt'))
|
long_description=open('README.txt'))
|
||||||
|
|
||||||
In that case, :file:`README.txt` is a regular reStructuredText text file located
|
In that case, `README.txt` is a regular reStructuredText text file located
|
||||||
in the root of the package besides :file:`setup.py`.
|
in the root of the package besides `setup.py`.
|
||||||
|
|
||||||
To prevent registering broken reStructuredText content, you can use the
|
To prevent registering broken reStructuredText content, you can use the
|
||||||
:program:`rst2html` program that is provided by the :mod:`docutils` package
|
:program:`rst2html` program that is provided by the `docutils` package
|
||||||
and check the ``long_description`` from the command line::
|
and check the ``long_description`` from the command line::
|
||||||
|
|
||||||
$ python setup.py --long-description | rst2html.py > output.html
|
$ python setup.py --long-description | rst2html.py > output.html
|
||||||
|
|
||||||
:mod:`docutils` will display a warning if there's something wrong with your syntax.
|
`docutils` will display a warning if there's something wrong with your syntax.
|
||||||
|
|
Loading…
Reference in New Issue