diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index abf749d7248..4ac9c3254b5 100644 --- a/Doc/dist/dist.tex +++ b/Doc/dist/dist.tex @@ -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}