General overhaul of the "Creating a Source Distribution" section --
better explanation of manifest files, in particular.
This commit is contained in:
Greg Ward
parent
239e1d5e50
commit
54589d4d97
|
|
@ -691,12 +691,10 @@ python setup.py sdist
|
|||
\end{verbatim}
|
||||
(assuming you haven't specified any \command{sdist} options in the setup
|
||||
script or config file), \command{sdist} creates the archive of the
|
||||
default format for the current platform. The default formats are:
|
||||
\begin{tableii}{ll}{textrm}%
|
||||
{Platform}{Default archive format for source distributions}
|
||||
\lineii{Unix}{gzipped tar file (\file{.tar.gz})}
|
||||
\lineii{Windows}{zip file}
|
||||
\end{tableii}
|
||||
default format for the current platform. The default format is gzip'ed
|
||||
tar file (\file{.tar.gz}) on Unix, and ZIP file on Windows. \XXX{no Mac
|
||||
OS support here}
|
||||
|
||||
You can specify as many formats as you like using the
|
||||
\longprogramopt{formats} option, for example:
|
||||
\begin{verbatim}
|
||||
|
|
@ -705,29 +703,31 @@ python setup.py sdist --formats=gztar,zip
|
|||
to create a gzipped tarball and a zip file. The available formats are:
|
||||
\begin{tableiii}{l|l|c}{code}%
|
||||
{Format}{Description}{Notes}
|
||||
\lineiii{zip}{zip file (\file{.zip})}{(1),(2)}
|
||||
\lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(3),(4)}
|
||||
\lineiii{zip}{zip file (\file{.zip})}{(1),(3)}
|
||||
\lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(2),(4)}
|
||||
\lineiii{bztar}{bzip2'ed tar file (\file{.tar.gz})}{(4)}
|
||||
\lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(4)}
|
||||
\lineiii{tar}{tar file (\file{.tar})}{}
|
||||
\lineiii{tar}{tar file (\file{.tar})}{(4)}
|
||||
\end{tableiii}
|
||||
|
||||
\noindent Notes:
|
||||
\begin{description}
|
||||
\item[(1)] default on Windows
|
||||
\item[(2)] under both Unix and Windows, requires either external
|
||||
\item[(2)] default on Unix
|
||||
\item[(3)] under both Unix and Windows, requires either external
|
||||
Info-ZIP utility \emph{or} the \module{zipfile} module
|
||||
\item[(3)] default on Unix
|
||||
\item[(4)] requires external utilities: \program{tar} and possibly one
|
||||
of \program{gzip}, \program{bzip2}, or \program{compress}
|
||||
\end{description}
|
||||
|
||||
|
||||
\subsection{The manifest and manifest template}
|
||||
|
||||
\subsection{Specifying the files to distribute}
|
||||
\label{manifest}
|
||||
|
||||
Without any additional information, the \command{sdist} command puts a
|
||||
minimal set of files into the source distribution:
|
||||
If you don't supply an explicit list of files (or instructions on how to
|
||||
generate one), the \command{sdist} command puts a minimal default set
|
||||
into the source distribution:
|
||||
\begin{itemize}
|
||||
\item all Python source files implied by the \option{py\_modules} and
|
||||
\option{packages} options
|
||||
|
|
@ -738,15 +738,22 @@ minimal set of files into the source distribution:
|
|||
(currently, the Distutils don't do anything with test scripts except
|
||||
include them in source distributions, but in the future there will be
|
||||
a standard for testing Python module distributions)
|
||||
\item \file{README.txt} (or \file{README}) and \file{setup.py}
|
||||
\item \file{README.txt} (or \file{README}), \file{setup.py} (or whatever
|
||||
you called your setup script), and \file{setup.cfg}
|
||||
\end{itemize}
|
||||
Sometimes this is enough, but usually you will want to specify
|
||||
additional files to distribute. The typical way to do this is to write
|
||||
a \emph{manifest template}, called \file{MANIFEST.in} by default. The
|
||||
\command{sdist} command processes this template and generates a manifest
|
||||
file, \file{MANIFEST}. (If you prefer, you can skip the manifest
|
||||
template and generate the manifest yourself: it just lists one file per
|
||||
line.)
|
||||
manifest template is just a list of instructions for how to generate
|
||||
your manifest file, \file{MANIFEST}, which is the exact list of files to
|
||||
include in your source distribution. The \command{sdist} command
|
||||
processes this template and generates a manifest based on its
|
||||
instructions and what it finds in the filesystem.
|
||||
|
||||
If you prefer to roll your own manifest file, the format is simple: one
|
||||
filename 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 described above does not apply in this case.
|
||||
|
||||
The manifest template has one command per line, where each command
|
||||
specifies a set of files to include or exclude from the source
|
||||
|
|
@ -760,16 +767,30 @@ prune examples/sample?/build
|
|||
The meanings should be fairly clear: include all files in the
|
||||
distribution root matching \code{*.txt}, all files anywhere under the
|
||||
\file{examples} directory matching \code{*.txt} or \code{*.py}, and
|
||||
exclude all directories matching \code{examples/sample?/build}. There
|
||||
are several other commands available in the manifest template
|
||||
mini-language; see section~\ref{sdist-cmd}.
|
||||
exclude all directories matching \code{examples/sample?/build}. All of
|
||||
this is done \emph{after} the standard include set, so you can exclude
|
||||
files from the standard set with explicit instructions in the manifest
|
||||
template. (Or, you can use the \longprogramopt{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 very much matters:
|
||||
initially, we have the list of default files as described above, and
|
||||
each command in the template adds to or removes from that list of files.
|
||||
When we have fully processed the manifest template, we have our complete
|
||||
list of files. This list is written to the manifest for future
|
||||
reference, and then used to build the source distribution archive(s).
|
||||
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 to or removes from that list of files. Once we have
|
||||
fully processed the manifest template, we remove files that should not
|
||||
be included in the source distribution:
|
||||
\begin{itemize}
|
||||
\item all files in the Distutils ``build'' tree (default \file{build/})
|
||||
\item all files in directories named \file{RCS} or \file{CVS}
|
||||
\end{itemize}
|
||||
Now we have our complete list of files, which is written to the manifest
|
||||
for future reference, and then used to build the source distribution
|
||||
archive(s).
|
||||
|
||||
You can disable the default set of included files with the
|
||||
\longprogramopt{no-defaults} option, and you can disable the standard
|
||||
exclude set with \longprogramopt{no-prune}.
|
||||
|
||||
Following the Distutils' own manifest template, let's trace how the
|
||||
\command{sdist} command builds the list of files to include in the
|
||||
|
|
@ -778,23 +799,24 @@ Distutils source distribution:
|
|||
\item include all Python source files in the \file{distutils} and
|
||||
\file{distutils/command} subdirectories (because packages
|
||||
corresponding to those two directories were mentioned in the
|
||||
\option{packages} option in the setup script)
|
||||
\item include \file{test/test*.py} (always included)
|
||||
\item include \file{README.txt} and \file{setup.py} (always included)
|
||||
\option{packages} option in the setup script---see
|
||||
section~\ref{setup-script})
|
||||
\item include \file{README.txt}, \file{setup.py}, and \file{setup.cfg}
|
||||
(standard files)
|
||||
\item include \file{test/test*.py} (standard files)
|
||||
\item include \file{*.txt} in the distribution root (this will find
|
||||
\file{README.txt} a second time, but such redundancies are weeded out
|
||||
later)
|
||||
\item in the sub-tree under \file{examples}, include anything matching
|
||||
\file{*.txt}
|
||||
\item in the sub-tree under \file{examples}, include anything matching
|
||||
\file{*.py}
|
||||
\item remove all files in the sub-trees starting at directories matching
|
||||
\file{examples/sample?/build}---this may exclude files included by the
|
||||
previous two steps, so it's important that the \code{prune} command in
|
||||
the manifest template comes after the two \code{recursive-include}
|
||||
commands
|
||||
\item include anything matching \file{*.txt} or \file{*.py} in the
|
||||
sub-tree under \file{examples},
|
||||
\item exclude all files in the sub-trees starting at directories
|
||||
matching \file{examples/sample?/build}---this may exclude files
|
||||
included by the previous two steps, so it's important that the
|
||||
\code{prune} command in the manifest template comes after the
|
||||
\code{recursive-include} command
|
||||
\item exclude the entire \file{build} tree, and any \file{RCS} or
|
||||
\file{CVS} directories
|
||||
\end{enumerate}
|
||||
|
||||
Just like in the setup script, file and directory names in the manifest
|
||||
template should always be slash-separated; the Distutils will take care
|
||||
of converting them to the standard representation on your platform.
|
||||
|
|
@ -809,15 +831,26 @@ follows:
|
|||
\begin{itemize}
|
||||
\item if the manifest file, \file{MANIFEST} doesn't exist, read
|
||||
\file{MANIFEST.in} and create the manifest
|
||||
\item if neither \file{MANIFEST} nor \file{MANIFEST.in} exist, create a
|
||||
manifest with just the default file set\footnote{In versions of the
|
||||
Distutils up to and including 0.9.2 (Python 2.0b1), this feature was
|
||||
broken; use the \programopt{-f} (\longprogramopt{force-manifest})
|
||||
option to work around the bug.}
|
||||
\item 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}
|
||||
\item use the list of files now in \file{MANIFEST} (either just
|
||||
generated or read in) to create the source distribution archive(s)
|
||||
\end{itemize}
|
||||
There are a couple of options that modify this behaviour.
|
||||
There are a couple of options that modify this behaviour. First, use
|
||||
the \longprogramopt{no-defaults} and \longprogramopt{no-prune} to
|
||||
disable the standard ``include'' and ``exclude'' sets.\footnote{Note
|
||||
that if you have no manifest template, no manifest, and use the
|
||||
\longprogramopt{no-defaults}, you will get an empty manifest. Another
|
||||
bug in Distutils 0.9.2 and earlier causes an uncaught exception in
|
||||
this case. The workaround is: Don't Do That.}
|
||||
|
||||
First, you might want to force the manifest to be regenerated---for
|
||||
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:
|
||||
|
|
@ -830,13 +863,9 @@ source distribution:
|
|||
\begin{verbatim}
|
||||
python setup.py sdist --manifest-only
|
||||
\end{verbatim}
|
||||
(\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.)
|
||||
|
||||
If you don't want to use the default file set, you can supply the
|
||||
\longprogramopt{no-defaults} option. If you use
|
||||
\longprogramopt{no-defaults} and don't supply a manifest template (or
|
||||
it's empty, or nothing matches the patterns in it), then your source
|
||||
distribution will be empty.
|
||||
\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.
|
||||
\programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and
|
||||
\programopt{-f} for \longprogramopt{force-manifest}.
|
||||
|
||||
|
||||
\section{Creating Built Distributions}
|
||||
|
|
|
|||
Loading…
Reference in New Issue