[Python-checkins] CVS: distutils/doc/dist dist.tex,1.23,1.24
Greg Ward
python-dev@python.org
Tue, 5 Sep 2000 18:37:39 -0700
Update of /cvsroot/python/distutils/doc/dist
In directory slayer.i.sourceforge.net:/tmp/cvs-serv25122
Modified Files:
dist.tex
Log Message:
General overhaul of the "Creating a Source Distribution" section --
better explanation of manifest files, in particular.
Index: dist.tex
===================================================================
RCS file: /cvsroot/python/distutils/doc/dist/dist.tex,v
retrieving revision 1.23
retrieving revision 1.24
diff -C2 -r1.23 -r1.24
*** dist.tex 2000/09/04 20:07:15 1.23
--- dist.tex 2000/09/06 01:37:35 1.24
***************
*** 692,701 ****
(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}
You can specify as many formats as you like using the
\longprogramopt{formats} option, for example:
--- 692,699 ----
(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 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:
***************
*** 706,714 ****
\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{bztar}{bzip2'ed tar file (\file{.tar.gz})}{(4)}
\lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(4)}
! \lineiii{tar}{tar file (\file{.tar})}{}
\end{tableiii}
--- 704,712 ----
\begin{tableiii}{l|l|c}{code}%
{Format}{Description}{Notes}
! \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})}{(4)}
\end{tableiii}
***************
*** 716,732 ****
\begin{description}
\item[(1)] default on Windows
! \item[(2)] 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}
\label{manifest}
! Without any additional information, the \command{sdist} command puts a
! minimal set of files into the source distribution:
\begin{itemize}
\item all Python source files implied by the \option{py\_modules} and
--- 714,732 ----
\begin{description}
\item[(1)] default on Windows
! \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[(4)] requires external utilities: \program{tar} and possibly one
of \program{gzip}, \program{bzip2}, or \program{compress}
\end{description}
+
! \subsection{Specifying the files to distribute}
\label{manifest}
! 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
***************
*** 739,751 ****
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}
\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.)
The manifest template has one command per line, where each command
--- 739,758 ----
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}), \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
! 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
***************
*** 761,774 ****
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}.
!
! 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).
Following the Distutils' own manifest template, let's trace how the
--- 768,795 ----
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}. 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 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
***************
*** 779,799 ****
\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)
\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
\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
--- 800,821 ----
\file{distutils/command} subdirectories (because packages
corresponding to those two directories were mentioned in the
! \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 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
***************
*** 810,813 ****
--- 832,840 ----
\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
***************
*** 816,822 ****
generated or read in) to create the source distribution archive(s)
\end{itemize}
! There are a couple of options that modify this behaviour.
! First, 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
--- 843,855 ----
generated or read in) to create the source distribution archive(s)
\end{itemize}
! 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.}
! 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
***************
*** 831,841 ****
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.
--- 864,870 ----
python setup.py sdist --manifest-only
\end{verbatim}
! \longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.
! \programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and
! \programopt{-f} for \longprogramopt{force-manifest}.