mirror of https://github.com/python/cpython
reorganized the distutils doc a bit : the MANIFEST.in template system has its own section now. This is easier to find and follow
This commit is contained in:
Tarek Ziadé
parent
001e4a6c07
commit
4f786b20ab
|
|
@ -48,50 +48,6 @@ 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}
|
||||||
|
|
|
||||||
|
|
@ -111,9 +111,68 @@ 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 want to force the manifest to be regenerated---for example, if
|
||||||
|
you have added or removed files or directories that match an existing pattern in
|
||||||
|
the manifest template, you should regenerate the manifest::
|
||||||
|
|
||||||
|
python setup.py sdist --force-manifest
|
||||||
|
|
||||||
|
Or, you might just want to (re)generate the manifest, but not create a source
|
||||||
|
distribution::
|
||||||
|
|
||||||
|
python setup.py sdist --manifest-only
|
||||||
|
|
||||||
|
:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a
|
||||||
|
shortcut for :option:`--manifest-only`, and :option:`-f` for
|
||||||
|
:option:`--force-manifest`.
|
||||||
|
|
||||||
|
.. _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, again we turn to the Distutils' own manifest template::
|
example, let's look at the Distutils' own manifest template::
|
||||||
|
|
||||||
include *.txt
|
include *.txt
|
||||||
recursive-include examples *.txt *.py
|
recursive-include examples *.txt *.py
|
||||||
|
|
@ -125,9 +184,7 @@ 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.) There are
|
:option:`--no-defaults` option to disable the standard set entirely.)
|
||||||
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
|
||||||
|
|
@ -181,44 +238,41 @@ 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
|
||||||
|
--------
|
||||||
|
|
||||||
.. _manifest-options:
|
The manifest template commands are:
|
||||||
|
|
||||||
Manifest-related options
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
========================
|
| Command | Description |
|
||||||
|
+===========================================+===============================================+
|
||||||
The normal course of operations for the :command:`sdist` command is as follows:
|
| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
|
||||||
|
| | patterns |
|
||||||
* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
and create the manifest
|
| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
|
||||||
|
| | patterns |
|
||||||
* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
with just the default file set
|
| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
|
||||||
|
| ...` | the listed patterns |
|
||||||
* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
|
| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
|
||||||
:file:`MANIFEST.in`
|
| ...` | the listed patterns |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
* use the list of files now in :file:`MANIFEST` (either just generated or read
|
| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
|
||||||
in) to create the source distribution archive(s)
|
| | matching --- & any of the listed patterns |
|
||||||
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
There are a couple of options that modify this behaviour. First, use the
|
| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
|
||||||
:option:`--no-defaults` and :option:`--no-prune` to disable the standard
|
| | matching --- & any of the listed patterns |
|
||||||
"include" and "exclude" sets.
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
| :command:`prune dir` | exclude all files under *dir* |
|
||||||
Second, you might want to force the manifest to be regenerated---for example, if
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
you have added or removed files or directories that match an existing pattern in
|
| :command:`graft dir` | include all files under *dir* |
|
||||||
the manifest template, you should regenerate the manifest::
|
+-------------------------------------------+-----------------------------------------------+
|
||||||
|
|
||||||
python setup.py sdist --force-manifest
|
|
||||||
|
|
||||||
Or, you might just want to (re)generate the manifest, but not create a source
|
|
||||||
distribution::
|
|
||||||
|
|
||||||
python setup.py sdist --manifest-only
|
|
||||||
|
|
||||||
:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a
|
|
||||||
shortcut for :option:`--manifest-only`, and :option:`-f` for
|
|
||||||
:option:`--force-manifest`.
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue