[Python-checkins] CVS: distutils/doc/dist dist.tex,1.18,1.19
Greg Ward
python-dev@python.org
Fri, 4 Aug 2000 17:43:15 -0700
Update of /cvsroot/python/distutils/doc/dist
In directory slayer.i.sourceforge.net:/tmp/cvs-serv27040
Modified Files:
dist.tex
Log Message:
A bundle of wording improvements, corrections, clarifications, updates,
and so forth.
Index: dist.tex
===================================================================
RCS file: /cvsroot/python/distutils/doc/dist/dist.tex,v
retrieving revision 1.18
retrieving revision 1.19
diff -C2 -r1.18 -r1.19
*** dist.tex 2000/06/30 03:36:41 1.18
--- dist.tex 2000/08/05 00:43:11 1.19
***************
*** 22,35 ****
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.
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
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.
This document concentrates on the role of developer/distributor: if
--- 22,35 ----
for installing and maintaining third-party modules. With the
introduction of the Python Distribution Utilities (Distutils for short)
! 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 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 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
***************
*** 69,75 ****
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:
\begin{verbatim}
from distutils.core import setup
--- 69,76 ----
The setup script is usually quite simple, although since it's written in
! 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
***************
*** 119,123 ****
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
--- 120,123 ----
***************
*** 129,135 ****
python setup.py bdist_wininst
\end{verbatim}
! will create an executable installer, \file{Foo-1\_0.exe}, in the current
! directory.
(Another way to create executable installers for Windows is with the
\command{bdist\_wise} command, which uses Wise---the commercial
--- 129,136 ----
python setup.py bdist_wininst
\end{verbatim}
! 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
***************
*** 143,151 ****
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.
--- 144,162 ----
work; it's available from \url{http://foo/bar/baz}.)
! 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}
***************
*** 159,165 ****
\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.
\item[pure Python module] a module written in Python and contained in a
single \file{.py} file (and possibly associated \file{.pyc} and/or
--- 170,175 ----
\begin{description}
\item[module] the basic unit of code reusability in Python: a block of
! 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
***************
*** 225,232 ****
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.)
\begin{verbatim}
--- 235,242 ----
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 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}
***************
*** 237,241 ****
setup (name = "Distutils",
version = "1.0",
! description = "Python Module Distribution Utilities",
author = "Greg Ward",
author_email = "gward@python.net",
--- 247,251 ----
setup (name = "Distutils",
version = "1.0",
! description = "Python Distribution Utilities",
author = "Greg Ward",
author_email = "gward@python.net",
***************
*** 285,299 ****
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
\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
\file{lib/foo/\_\_init\_\_.py} exists.
--- 295,309 ----
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 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. 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.
***************
*** 338,343 ****
\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}}
--- 348,351 ----
***************
*** 345,350 ****
\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
--- 353,356 ----
***************
*** 492,497 ****
\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 use the list of files now in \file{MANIFEST} (either just
generated or read in) to create the source distribution archive(s)
--- 498,504 ----
\item if the manifest file, \file{MANIFEST} doesn't exist, read
\file{MANIFEST.in} and create the manifest
! \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)
***************
*** 506,511 ****
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
--- 513,516 ----
***************
*** 563,614 ****
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.
\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,
\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.
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{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}{}
\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
\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
\command{bdist} ``sub-commands'' actually generate several similar
formats; for instance, the \command{bdist\_dumb} command generates all
--- 568,622 ----
in this case), does a ``fake'' installation (also in the \file{build}
directory), and creates the default type of built distribution for my
! 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, 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.\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})}{}
! \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}{}
! \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 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. Some of these
\command{bdist} ``sub-commands'' actually generate several similar
formats; for instance, the \command{bdist\_dumb} command generates all
***************
*** 621,625 ****
\lineii{bdist\_dumb}{tar, ztar, gztar, zip}
\lineii{bdist\_rpm}{rpm, srpm}
! \lineii{bdist\_wise}{wise}
\end{tableii}
--- 629,634 ----
\lineii{bdist\_dumb}{tar, ztar, gztar, zip}
\lineii{bdist\_rpm}{rpm, srpm}
! \lineii{bdist\_wininst}{wininst}
! %\lineii{bdist\_wise}{wise}
\end{tableii}