[Python-checkins] CVS: distutils/doc/dist dist.tex,1.24,1.25
Greg Ward
python-dev@python.org
Wed, 6 Sep 2000 19:40:41 -0700
Update of /cvsroot/python/distutils/doc/dist
In directory slayer.i.sourceforge.net:/tmp/cvs-serv26691
Modified Files:
dist.tex
Log Message:
Greatly enhanced the section on creating built distributions; in
particular wrote up creating RPMs in detail.
Other scattered improvements.
Index: dist.tex
===================================================================
RCS file: /cvsroot/python/distutils/doc/dist/dist.tex,v
retrieving revision 1.24
retrieving revision 1.25
diff -C2 -r1.24 -r1.25
*** dist.tex 2000/09/06 01:37:35 1.24
--- dist.tex 2000/09/07 02:40:37 1.25
***************
*** 4,7 ****
--- 4,9 ----
\usepackage{distutils}
+ % $Id$
+
\title{Distributing Python Modules}
***************
*** 715,720 ****
\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}
--- 717,722 ----
\item[(1)] default on Windows
\item[(2)] default on Unix
! \item[(3)] requires either external \program{zip} utility or
! \module{zipfile} module (not part of the standard Python library)
\item[(4)] requires external utilities: \program{tar} and possibly one
of \program{gzip}, \program{bzip2}, or \program{compress}
***************
*** 885,889 ****
installer; for Debian-based Linux users, it's a Debian package; and so
forth. Obviously, no one person will be able to create built
! distributions for every platform under the sun, so the Distutils is
designed to enable module developers to concentrate on their
specialty---writing code and creating source distributions---while an
--- 887,891 ----
installer; for Debian-based Linux users, it's a Debian package; and so
forth. Obviously, no one person will be able to create built
! distributions for every platform under the sun, so the Distutils are
designed to enable module developers to concentrate on their
specialty---writing code and creating source distributions---while an
***************
*** 909,931 ****
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,
--- 911,936 ----
in this case), does a ``fake'' installation (also in the \file{build}
directory), and creates the default type of built distribution for my
! platform. The default format for built distributions is a ``dumb'' tar
! file on Unix, and an simple executable installer on Windows. (That tar
! file is considered ``dumb'' because it has to 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 right place installs the Distutils just as though you had
! downloaded the source distribution and run \code{python setup.py
! install}. (The ``right place'' is either the root of the filesystem or
! Python's \filevar{prefix} directory, depending on the options given to
! the \command{bdist\_dumb} command; the default is to make dumb
! distributions relative to \filevar{prefix}.)
!
! 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. And creating ``smart'' built distributions,
! such as an RPM package or an executable installer for Windows, is a big
! win for users even if your distribution doesn't include any extensions.
! The \command{bdist} command has a \longprogramopt{formats} option,
similar to the \command{sdist} command, which you can use to select the
types of built distribution to generate: for example,
***************
*** 940,950 ****
\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}
--- 945,955 ----
\begin{tableiii}{l|l|c}{code}%
{Format}{Description}{Notes}
! \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(1),(3)}
! \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(3)}
! \lineiii{tar}{tar file (\file{.tar})}{(3)}
! \lineiii{zip}{zip file (\file{.zip})}{(4)}
! \lineiii{rpm}{RPM}{(5)}
! \lineiii{srpm}{source RPM}{(5) \XXX{to do!}}
! \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(6)}
%\lineiii{wise}{Wise installer for Windows}{(3)}
\end{tableiii}
***************
*** 954,957 ****
--- 959,969 ----
\item[(1)] default on Unix
\item[(2)] default on Windows \XXX{to-do!}
+ \item[(3)] requires external utilities: \program{tar} and possibly one
+ of \program{gzip}, \program{bzip2}, or \program{compress}
+ \item[(4)] requires either external \program{zip} utility or
+ \module{zipfile} module (not part of the standard Python library)
+ \item[(5)] requires external \program{rpm} utility, version 3.0.4 or
+ better (use \code{rpm --version} to find out which version you have)
+ \item[(6)] \XXX{requirements for \command{bdist\_wininst}?}
%\item[(3)] not implemented yet
\end{description}
***************
*** 974,977 ****
--- 986,1118 ----
\end{tableii}
+ The following sections give details on the individual \command{bdist\_*}
+ commands.
+
+
+ \subsection{Creating dumb built distributions}
+ \label{creating-dumb}
+
+ \XXX{Need to document absolute vs. prefix-relative packages here, but
+ first I have to implement it!}
+
+
+ \subsection{Creating RPM packages}
+ \label{creating-rpms}
+
+ The RPM format is used by many of popular Linux distributions, including
+ Red Hat, SuSE, and Mandrake. If one of these (or any of the other
+ RPM-based Linux distributions) is your usual environment, creating RPM
+ packages for other users of that same distribution is trivial.
+ Depending on the complexity of your module distribution and differences
+ between Linux distributions, you may also be able to create RPMs that
+ work on different RPM-based distributions.
+
+ The usual way to create an RPM of your module distribution is to run the
+ \command{bdist\_rpm} command:
+ \begin{verbatim}
+ python setup.py bdist_rpm
+ \end{verbatim}
+ or the \command{bdist} command with the \longprogramopt{format} option:
+ \begin{verbatim}
+ python setup.py bdist --formats=rpm
+ \end{verbatim}
+ The former allows you to specify RPM-specific options; the latter allows
+ you to easily specify multiple formats in one run. If you need to do
+ both, you can explicitly specify multiple \command{bdist\_*} commands
+ and their options:
+ \begin{verbatim}
+ python setup.py bdist_rpm --packager="John Doe <jdoe@python.net>" \
+ bdist_wininst --target_version="2.0"
+ \end{verbatim}
+
+ Creating RPM packages is driven by a \file{.spec} file, much as using
+ the Distutils is driven by the setup script. To make your life easier,
+ the \command{bdist\_rpm} command normally creates a \file{.spec} file
+ based on the information you supply in the setup script, on the command
+ line, and in any Distutils configuration files. Various options and
+ section in the \file{.spec} file are derived from options in the setup
+ script as follows:
+ \begin{tableii}{l|l}{textrm}%
+ {RPM \file{.spec} file option or section}{Distutils setup script option}
+ \lineii{Name}{\option{name}}
+ \lineii{Summary (in preamble)}{\option{description}}
+ \lineii{Version}{\option{version}}
+ \lineii{Vendor}{\option{author} and \option{author\_email}, or \\&
+ \option{maintainer} and \option{maintainer\_email}}
+ \lineii{Copyright}{\option{licence}}
+ \lineii{Url}{\option{url}}
+ \lineii{\%description (section)}{\option{long\_description}}
+ \end{tableii}
+
+ Additionally, there many options in \file{.spec} files that don't have
+ corresponding options in the setup script. Most of these are handled
+ through options to the \command{bdist\_rpm} command as follows:
+ \begin{tableiii}{l|l|l}{textrm}%
+ {RPM \file{.spec} file option or section}%
+ {\command{bdist\_rpm} option}%
+ {default value}
+ \lineiii{Release}{\option{release}}{``1''}
+ \lineiii{Group}{\option{group}}{``Development/Libraries''}
+ \lineiii{Vendor}{\option{vendor}}{(see above)}
+ \lineiii{Packager}{packager}{(none)}
+ \lineiii{Provides}{provides}{(none)}
+ \lineiii{Requires}{requires}{(none)}
+ \lineiii{Conflicts}{conflicts}{(none)}
+ \lineiii{Obsoletes}{obsoletes}{(none)}
+ \lineiii{Distribution}{\option{distribution\_name}}{(none)}
+ \lineiii{BuildRequires}{\option{build\_requires}}{(none)}
+ \lineiii{Icon}{\option{icon}}{(none)}
+ \end{tableiii}
+ Obviously, supplying even a few of these options on the command-line
+ would be tedious and error-prone, so it's usually best to put them in
+ the setup configuration file, \file{setup.cfg}---see
+ section~\ref{setup-config}. If you distribute or package many Python
+ module distributions, you might want to put options that apply to all of
+ them in your personal Distutils configuration file
+ (\file{\textasciitilde/.pydistutils.cfg}).
+
+ There are three steps to building a binary RPM package, all of which are
+ handled automatically by the Distutils:
+ \begin{enumerate}
+ \item create a \file{.spec} file, which describes the package (analogous
+ to the Distutils setup script; in fact, much of the information in the
+ setup script winds up in the \file{.spec} file)
+ \item create the source RPM
+ \item create the ``binary'' RPM (which may or may not contain binary
+ code, depending on whether your module distribution contains Python
+ extensions)
+ \end{enumerate}
+ Normally, RPM bundles the last two steps together; when you use the
+ Distutils, all three steps are typically bundled together.
+
+ If you wish, you can separate these three steps. You can use the
+ \longprogramopt{spec-only} option to make \command{bdist\_rpm} just
+ create the \file{.spec} file and exit; in this case, the \file{.spec}
+ file will be written to the ``distribution directory''---normally
+ \file{dist/}, but customizable with the \longprogramopt{dist-dir}
+ option. (Normally, the \file{.spec} file winds up deep in the ``build
+ tree,'' in a temporary directory created by \command{bdist\_rpm}.)
+
+ \XXX{this isn't implemented yet---is it needed?!}
+ You can also specify a custom \file{.spec} file with the
+ \longprogramopt{spec-file} option; used in conjunctin with
+ \longprogramopt{spec-only}, this gives you an opportunity to customize
+ the \file{.spec} file manually:
+ \begin{verbatim}
+ > python setup.py bdist_rpm --spec-only
+ # ...edit dist/FooBar-1.0.spec
+ > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
+ \end{verbatim}
+ (Although a better way to do this is probably to override the standard
+ \command{bdist\_rpm} command with one that writes whatever else you want
+ to the \file{.spec} file; see section~\ref{extending} for information on
+ extending the Distutils.)
+
+
+ \subsection{Creating Windows installers}
+ \label{creating-wininst}
+
+
+
\section{Examples}
\label{examples}
***************
*** 1060,1063 ****
--- 1201,1205 ----
\XXX{fragment moved down from above: needs context!}
+
The manifest template commands are:
\begin{tableii}{ll}{command}{Command}{Description}
***************
*** 1086,1089 ****
--- 1228,1232 ----
platform-specific: on Unix it is anything except slash; on Windows
anything except backslash or colon; on Mac OS anything except colon.
+
\XXX{Windows and Mac OS support not there yet}