From 781380c1f8f78e269bd06f28700e17bebd0a5143 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Thu, 19 Feb 2004 23:17:46 +0000
Subject: - "Mac OS" should always include the space - comment out
documentation for a non-existant feature (--spec-file) that the comments
indicate isn't clearly needed - lots of minor markup adjustments to get a
more consistent presentation
---
Doc/dist/dist.tex | 56 ++++++++++++++++++++++++++++++++-----------------------
1 file changed, 33 insertions(+), 23 deletions(-)
diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex
index f33e01b..d75ede7 100644
--- a/Doc/dist/dist.tex
+++ b/Doc/dist/dist.tex
@@ -295,9 +295,9 @@ platform-neutral representation into whatever is appropriate on your
current platform before actually using the pathname. This makes your
setup script portable across operating systems, which of course is one
of the major goals of the Distutils. In this spirit, all pathnames in
-this document are slash-separated. (MacOS programmers should keep in
+this document are slash-separated. (Mac OS programmers should keep in
mind that the \emph{absence} of a leading slash indicates a relative
-path, the opposite of the MacOS convention with colons.)
+path, the opposite of the Mac OS convention with colons.)
This, of course, only applies to pathnames given to Distutils
functions. If you, for example, use standard Python functions such as
@@ -964,7 +964,7 @@ python setup.py sdist
script or config file), \command{sdist} creates the archive of the
default format for the current platform. The default format is a gzip'ed
tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows.
-\XXX{no MacOS support here}
+\XXX{no Mac OS support here}
You can specify as many formats as you like using the
\longprogramopt{formats} option, for example:
@@ -974,6 +974,7 @@ python setup.py sdist --formats=gztar,zip
\end{verbatim}
to create a gzipped tarball and a zip file. The available formats are:
+
\begin{tableiii}{l|l|c}{code}%
{Format}{Description}{Notes}
\lineiii{zip}{zip file (\file{.zip})}{(1),(3)}
@@ -1007,7 +1008,7 @@ into the source distribution:
\option{packages} options
\item all C source files mentioned in the \option{ext\_modules} or
\option{libraries} options (\XXX{getting C library sources currently
- broken -- no get\_source\_files() method in build\_clib.py!})
+ broken---no \method{get_source_files()} method in \file{build_clib.py}!})
\item anything that looks like a test script: \file{test/test*.py}
(currently, the Distutils don't do anything with test scripts except
include them in source distributions, but in the future there will be
@@ -1219,6 +1220,7 @@ would, when run on a \UNIX{} system, create
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{gztar}{gzipped tar file (\file{.tar.gz})}{(1),(3)}
@@ -1255,6 +1257,7 @@ the ``dumb'' archive formats (\code{tar}, \code{ztar}, \code{gztar}, and
\code{zip}), and \command{bdist\_rpm} generates both binary and source
RPMs. The \command{bdist} sub-commands, and the formats generated by
each, are:
+
\begin{tableii}{l|l}{command}%
{Command}{Formats}
\lineii{bdist\_dumb}{tar, ztar, gztar, zip}
@@ -1314,6 +1317,7 @@ based on the information you supply in the setup script, on the command
line, and in any Distutils configuration files. Various options and
sections 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}}
@@ -1329,6 +1333,7 @@ script as follows:
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}%
@@ -1345,6 +1350,7 @@ through options to the \command{bdist\_rpm} command as follows:
\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
@@ -1355,6 +1361,7 @@ them in your personal Distutils configuration file
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
@@ -1364,32 +1371,33 @@ handled automatically by the Distutils:
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
+\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}.)
+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 conjunction 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.)
+% \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 conjunction 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.)
\subsection{Creating Windows Installers}
@@ -1859,6 +1867,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} ... }
{include all files matching any of the listed patterns}
@@ -1877,15 +1886,16 @@ The manifest template commands are:
\lineii{prune \var{dir}}{exclude all files under \var{dir}}
\lineii{graft \var{dir}}{include all files under \var{dir}}
\end{tableii}
+
The patterns here are \UNIX-style ``glob'' patterns: \code{*} matches any
sequence of regular filename characters, \code{?} matches any single
regular filename character, and \code{[\var{range}]} matches any of the
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 MacOS anything except colon.
+anything except backslash or colon; on Mac OS anything except colon.
-\XXX{Windows and MacOS support not there yet}
+\XXX{Windows and Mac OS support not there yet}
%\subsection{Creating a built distribution: the
--
cgit v0.12