From b65289745679d674ba5c356c3dbebb1f90bacd7a Mon Sep 17 00:00:00 2001 From: Greg Ward Date: Thu, 7 Sep 2000 02:40:37 +0000 Subject: Greatly enhanced the section on creating built distributions; in particular wrote up creating RPMs in detail. Other scattered improvements. --- Doc/dist/dist.tex | 195 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 169 insertions(+), 26 deletions(-) diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex index 4ac9c32..679d9fd 100644 --- a/Doc/dist/dist.tex +++ b/Doc/dist/dist.tex @@ -3,6 +3,8 @@ \usepackage{times} \usepackage{distutils} +% $Id$ + \title{Distributing Python Modules} \author{Greg Ward} @@ -714,8 +716,8 @@ to create a gzipped tarball and a zip file. The available formats are: \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[(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} \end{description} @@ -884,7 +886,7 @@ installers of your module distribution: for users of RPM-based Linux systems, it's a binary RPM; for Windows users, it's an executable 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 +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 intermediary species of \emph{packager} springs up to turn source @@ -908,25 +910,28 @@ python setup.py bdist 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. 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.) +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 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, +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, \begin{verbatim} @@ -939,13 +944,13 @@ 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{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} @@ -953,6 +958,13 @@ The available formats for built distributions are: \begin{description} \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} @@ -973,6 +985,135 @@ each, are: %\lineii{bdist\_wise}{wise} \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 " \ + 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} @@ -1059,6 +1200,7 @@ This command installs all (Python) scripts in the distribution. \XXX{fragment moved down from above: needs context!} + The manifest template commands are: \begin{tableii}{ll}{command}{Command}{Description} \lineii{include \var{pat1} \var{pat2} ... } @@ -1085,6 +1227,7 @@ characters in \var{range} (e.g., \code{a-z}, \code{a-zA-Z}, \code{a-f0-9\_.}). The definition of ``regular filename character'' is 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} -- cgit v0.12