General overhaul of the "Creating a Source Distribution" section --
better explanation of manifest files, in particular.
diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex
index abf749d..4ac9c32 100644
--- a/Doc/dist/dist.tex
+++ b/Doc/dist/dist.tex
@@ -691,12 +691,10 @@
\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 @@
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 @@
(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 @@
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 @@
\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 @@
\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 @@
\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}