A bundle of wording improvements, corrections, clarifications, updates,
and so forth.
diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex
index 8f17115..e7d9f44 100644
--- a/Doc/dist/dist.tex
+++ b/Doc/dist/dist.tex
@@ -21,16 +21,16 @@
support for distributing modules, nor have Python users had much support
for installing and maintaining third-party modules. With the
introduction of the Python Distribution Utilities (Distutils for short)
-in Python 2.0, this situation should start to improve.
+in Python 1.6, this situation should start to improve.
This document only covers using the Distutils to distribute your Python
-modules. Using the Distutils does not tie you to Python 2.0, though:
-the Distutils work just fine with Python 1.5, and it is reasonable (and
-expected to become commonplace) to expect users of Python 1.5 to
+modules. Using the Distutils does not tie you to Python 1.6, though:
+the Distutils work just fine with Python 1.5.2, and it is reasonable
+(and expected to become commonplace) to expect users of Python 1.5.2 to
download and install the Distutils separately before they can install
-your modules. Python 2.0 users, of course, won't have to add anything
-to their Python installation in order to use the Distutils to install
-third-party modules.
+your modules. Python 1.6 (or later) users, of course, won't have to add
+anything to their Python installation in order to use the Distutils to
+install third-party modules.
This document concentrates on the role of developer/distributor: if
you're looking for information on installing Python modules, you
@@ -68,9 +68,10 @@
\label{simple-example}
The setup script is usually quite simple, although since it's written in
-Python, there are no arbitrary limits to what you can do. If all you
-want to do is distribute a module called \module{foo}, contained in a
-file \file{foo.py}, then your setup script can be as little as this:
+Python, there are no arbitrary limits to what you can do with it. If
+all you want to do is distribute a module called \module{foo}, contained
+in a file \file{foo.py}, then your setup script can be as little as
+this:
\begin{verbatim}
from distutils.core import setup
setup (name = "foo",
@@ -118,7 +119,6 @@
more often for installers (although most developers will want to install
their own code occasionally).
-\XXX{only partially implemented}%
If you want to make things really easy for your users, you can create
one or more built distributions for them. For instance, if you are
running on a Windows machine, and want to make things easy for other
@@ -128,9 +128,10 @@
\begin{verbatim}
python setup.py bdist_wininst
\end{verbatim}
-will create an executable installer, \file{Foo-1\_0.exe}, in the current
-directory.
+will create an executable installer, \file{Foo-1.0.win32.exe}, in the
+current directory.
+\XXX{not implemented yet}
(Another way to create executable installers for Windows is with the
\command{bdist\_wise} command, which uses Wise---the commercial
installer-generator used to create Python's own installer---to create
@@ -142,11 +143,21 @@
Wise installed on your system for the \command{bdist\_wise} command to
work; it's available from \url{http://foo/bar/baz}.)
-Other \command{bdist} commands exist for other platforms: for example,
-\command{bdist\_rpm} for RPM-based Linux systems, (\command{bdist\_deb})
-for Debian-based Linux systems, and so forth. See
-section~\ref{bdist-cmds} for details on all the \command{bdist}
-commands.
+Currently (Distutils 0.9.1), the are only other useful built
+distribution format is RPM, implemented by the \command{bdist\_rpm}
+command. For example, the following command will create an RPM file
+called \file{Foo-1.0.noarch.rpm}:
+\begin{verbatim}
+python setup.py bdist_rpm
+\end{verbatim}
+(This uses the \command{rpm} command, so has to be run on an RPM-based
+system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.)
+
+You can find out what distribution formats are available at any time by
+running
+\begin{verbatim}
+python setup.py bdist --help-formats
+\end{verbatim}
\subsection{General Python terminology}
@@ -158,9 +169,8 @@
following glossary of common Python terms:
\begin{description}
\item[module] the basic unit of code reusability in Python: a block of
- code imported by some other code. There are three types of modules
- that concern us here: pure Python modules, extension modules, and
- packages.
+ code imported by some other code. Three types of modules concern us
+ here: pure Python modules, extension modules, and packages.
\item[pure Python module] a module written in Python and contained in a
single \file{.py} file (and possibly associated \file{.pyc} and/or
\file{.pyo} files). Sometimes referred to as a ``pure module.''
@@ -224,10 +234,10 @@
Here's a slightly more involved example, which we'll follow for the next
couple of sections: the Distutils' own setup script. (Keep in mind that
-although the Distutils are included with Python 2.0, they also have an
-independent existence so that Python 1.5 users can use them to install
-other module distributions. The Distutils' own setup script is used to
-install the package into Python 1.5.)
+although the Distutils are included with Python 1.6 and later, they also
+have an independent existence so that Python 1.5.2 users can use them to
+install other module distributions. The Distutils' own setup script,
+shown here, is used to install the package into Python 1.5.2.)
\begin{verbatim}
#!/usr/bin/env python
@@ -236,7 +246,7 @@
setup (name = "Distutils",
version = "1.0",
- description = "Python Module Distribution Utilities",
+ description = "Python Distribution Utilities",
author = "Greg Ward",
author_email = "gward@python.net",
url = "http://www.python.org/sigs/distutils-sig/",
@@ -284,17 +294,17 @@
If you use a different convention to lay out your source directory,
that's no problem: you just have to supply the \option{package\_dir}
option to tell the Distutils about your convention. For example, say
-you keep all Python source under \file{lib}, so that modules not in any
-package are right in \file{lib}, modules in the \module{foo} package
-are in \file{lib/foo}, and so forth. Then you would put
+you keep all Python source under \file{lib}, so that modules in the
+``root package'' (i.e., not in any package at all) are right in
+\file{lib}, modules in the \module{foo} package are in \file{lib/foo},
+and so forth. Then you would put
\begin{verbatim}
package_dir = {'': 'lib'}
\end{verbatim}
in your setup script. (The keys to this dictionary are package names,
-and an empty package name stands for the ``root package,'' i.e. no
-package at all. The values are directory names relative to your
-distribution root.) In this case, when you say
-\code{packages = ['foo']}, you are promising that the file
+and an empty package name stands for the root package. The values are
+directory names relative to your distribution root.) In this case, when
+you say \code{packages = ['foo']}, you are promising that the file
\file{lib/foo/\_\_init\_\_.py} exists.
Another possible convention is to put the \module{foo} package right in
@@ -337,15 +347,11 @@
\subsection{Describing extension modules}
\label{sec:describing-extensions}
-\XXX{be sure to describe the whole \code{build\_info} dict, including
- \code{extra\_compile\_args} and \code{extra\_link\_args}}
\section{Writing the Setup Configuration File}
\label{setup-config}
-\XXX{not implemented yet!}
-
Often, it's not possible to write down everything needed to build a
distribution \emph{a priori}. You need to get some information from the
user, or from the user's system, in order to proceed. For example, you
@@ -491,8 +497,9 @@
\begin{itemize}
\item if the manifest file, \file{MANIFEST} doesn't exist, read
\file{MANIFEST.in} and create the manifest
-\item if \file{MANIFEST.in} is more recent than \file{MANIFEST},
- recreate \file{MANIFEST} by reading \file{MANIFEST.in}
+\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}
@@ -505,8 +512,6 @@
\begin{verbatim}
python setup.py sdist --force-manifest
\end{verbatim}
-\XXX{this is stupid, but is there a better way to do it without
- reprocessing MANIFEST.in every single bloody time?}
Or, you might just want to (re)generate the manifest, but not create a
source distribution:
@@ -562,54 +567,57 @@
then the Distutils builds my module distribution (the Distutils itself
in this case), does a ``fake'' installation (also in the \file{build}
directory), and creates the default type of built distribution for my
-platform. In Distutils 0.8, only two types of built distribution are
-supported: \code{gztar} (default on non-Linux Unix) and \code{zip}
-(default on Windows). Thus, the above command on a Unix system creates
-\file{Distutils-0.8.built-posix.tar.gz}; unpacking this tarball from
-Python's \filevar{prefix} directory installs the Distutils just as
-though you had downloaded the source distribution and run \code{python
- setup.py install}. Obviously, for pure Python distributions, this
-isn't a huge win---but for non-pure distributions, which include
-extensions that would need to be compiled, it can mean the difference
-between someone being able to use your extensions or not.
+platform. Currently, the default format for built distributions is a
+``dumb'' archive---tarball on Unix, ZIP file on Windows. (These are
+called ``dumb'' built distributions, because they must be unpacked in a
+specific location to work.)
+
+Thus, the above command on a Unix system creates
+\file{Distutils-0.9.1.\filevar{plat}.tar.gz}; unpacking this tarball
+from the root of the filesystemq installs the Distutils just as though
+you had downloaded the source distribution and run \code{python setup.py
+ install}. (Assuming that the target system has their Python
+installation laid out the same as you do---another reason these are
+called ``dumb'' distributions.) Obviously, for pure Python
+distributions, this isn't a huge win---but for non-pure distributions,
+which include extensions that would need to be compiled, it can mean the
+difference between someone being able to use your extensions or not.
\XXX{filenames are inaccurate here!}
The \command{bdist} command has a \longprogramopt{format} option,
-similar to the \command{sdist} command, that you can use to select which
-formats to generate: for example,
+similar to the \command{sdist} command, which you can use to select the
+types of built distribution to generate: for example,
\begin{verbatim}
python setup.py bdist --format=zip
\end{verbatim}
would, when run on a Unix system, create
-\file{Distutils-0.8.built-posix.tar.gz}---again, this archive would be
-unpacked from Python's \filevar{prefix} directory to install the
-Distutils.
+\file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be
+unpacked from the root directory to install the Distutils.
The available formats for built distributions are:
\begin{tableiii}{l|l|c}{code}%
{Format}{Description}{Notes}
- \lineiii{zip}{zip file (\file{.zip})}{(1)}
- \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(2)}
+ \lineiii{zip}{zip file (\file{.zip})}{}
+ \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(1)}
\lineiii{ztar}{compressed tar file (\file{.tar.Z})}{}
\lineiii{tar}{tar file (\file{.tar})}{}
- \lineiii{rpm}{RPM}{(3)}
- \lineiii{srpm}{source RPM}{}
- \lineiii{wise}{Wise installer for Windows}{}
+ \lineiii{rpm}{RPM}{}
+ \lineiii{srpm}{source RPM}{\XXX{to do!}}
+ \lineiii{wininst}{self-extracting ZIP file for Windows}{(2)}
+ %\lineiii{wise}{Wise installer for Windows}{(3)}
\end{tableiii}
\noindent Notes:
\begin{description}
-\item[(1)] default on Windows
-\item[(2)] default on Unix
-\item[(3)] not implemented yet; will be default on RPM-based Linux
- systems
-\item[(5)] not implemented yet; will be default on Windows
+\item[(1)] default on Unix
+\item[(2)] default on Windows \XXX{to-do!}
+%\item[(3)] not implemented yet
\end{description}
You don't have to use the \command{bdist} command with the
\longprogramopt{formats} option; you can also use the command that
-directly implements the format you're interested in. Many of these
+directly implements the format you're interested in. Some of these
\command{bdist} ``sub-commands'' actually generate several similar
formats; for instance, the \command{bdist\_dumb} command generates all
the ``dumb'' archive formats (\code{tar}, \code{ztar}, \code{gztar}, and
@@ -620,7 +628,8 @@
{Command}{Formats}
\lineii{bdist\_dumb}{tar, ztar, gztar, zip}
\lineii{bdist\_rpm}{rpm, srpm}
- \lineii{bdist\_wise}{wise}
+ \lineii{bdist\_wininst}{wininst}
+ %\lineii{bdist\_wise}{wise}
\end{tableii}
\section{Examples}