Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Comment out section titles for sections that have not been written yet; 

there is no need to clutter a reader's life with those useless things.

Make the snippets of Python code conform to the standard style.

Suppress the "Contents" page for HTML; it is not needed for small documents
in the online environment since LaTeX2HTML generates lots of tables of links
anyway.

Various markup consistency nits.
This commit is contained in:
Fred Drake 2001-03-01 18:35:43 +00:00
parent f89ad5ed6b
commit a09262e860
1 changed files with 141 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
Doc/dist/dist.tex vendored
View File

@ -22,7 +22,13 @@
build/release/install mechanics. build/release/install mechanics.
\end{abstract} \end{abstract}
% The ugly "%begin{latexonly}" pseudo-environment supresses the table
% of contents for HTML generation.
%
%begin{latexonly}
\tableofcontents \tableofcontents
%end{latexonly}
\section{Introduction} \section{Introduction}
\label{intro} \label{intro}
@ -88,6 +94,7 @@ it.\footnote{But be careful about putting arbitrarily expensive
all you want to do is distribute a module called \module{foo}, contained 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 in a file \file{foo.py}, then your setup script can be as little as
this: this:
\begin{verbatim} \begin{verbatim}
from distutils.core import setup from distutils.core import setup
setup(name="foo", setup(name="foo",
@ -111,9 +118,11 @@ Some observations:
To create a source distribution for this module, you would create a To create a source distribution for this module, you would create a
setup script, \file{setup.py}, containing the above code, and run: setup script, \file{setup.py}, containing the above code, and run:
\begin{verbatim} \begin{verbatim}
python setup.py sdist python setup.py sdist
\end{verbatim} \end{verbatim}
which will create an archive file (e.g., tarball on \UNIX, ZIP file on which will create an archive file (e.g., tarball on \UNIX, ZIP file on
Windows) containing your setup script, \file{setup.py}, and your module, Windows) containing your setup script, \file{setup.py}, and your module,
\file{foo.py}. The archive file will be named \file{Foo-1.0.tar.gz} (or \file{foo.py}. The archive file will be named \file{Foo-1.0.tar.gz} (or
@ -122,9 +131,11 @@ Windows) containing your setup script, \file{setup.py}, and your module,
If an end-user wishes to install your \module{foo} module, all she has If an end-user wishes to install your \module{foo} module, all she has
to do is download \file{Foo-1.0.tar.gz} (or \file{.zip}), unpack it, to do is download \file{Foo-1.0.tar.gz} (or \file{.zip}), unpack it,
and---from the \file{Foo-1.0} directory---run and---from the \file{Foo-1.0} directory---run
\begin{verbatim} \begin{verbatim}
python setup.py install python setup.py install
\end{verbatim} \end{verbatim}
which will ultimately copy \file{foo.py} to the appropriate directory which will ultimately copy \file{foo.py} to the appropriate directory
for third-party modules in their Python installation. for third-party modules in their Python installation.
@ -142,9 +153,11 @@ running on a Windows machine, and want to make things easy for other
Windows users, you can create an executable installer (the most Windows users, you can create an executable installer (the most
appropriate type of built distribution for this platform) with the appropriate type of built distribution for this platform) with the
\command{bdist\_wininst} command. For example: \command{bdist\_wininst} command. For example:
\begin{verbatim} \begin{verbatim}
python setup.py bdist_wininst python setup.py bdist_wininst
\end{verbatim} \end{verbatim}
will create an executable installer, \file{Foo-1.0.win32.exe}, in the will create an executable installer, \file{Foo-1.0.win32.exe}, in the
current directory. current directory.
@ -152,14 +165,17 @@ Currently (Distutils 0.9.2), the only other useful built
distribution format is RPM, implemented by the \command{bdist\_rpm} distribution format is RPM, implemented by the \command{bdist\_rpm}
command. For example, the following command will create an RPM file command. For example, the following command will create an RPM file
called \file{Foo-1.0.noarch.rpm}: called \file{Foo-1.0.noarch.rpm}:
\begin{verbatim} \begin{verbatim}
python setup.py bdist_rpm python setup.py bdist_rpm
\end{verbatim} \end{verbatim}
(This uses the \command{rpm} command, so has to be run on an RPM-based (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.) system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.)
You can find out what distribution formats are available at any time by You can find out what distribution formats are available at any time by
running running
\begin{verbatim} \begin{verbatim}
python setup.py bdist --help-formats python setup.py bdist --help-formats
\end{verbatim} \end{verbatim}
@ -255,10 +271,10 @@ setup (name = "Distutils",
author="Greg Ward", author="Greg Ward",
author_email="gward@python.net", author_email="gward@python.net",
url="http://www.python.org/sigs/distutils-sig/", url="http://www.python.org/sigs/distutils-sig/",
packages=['distutils', 'distutils.command'], packages=['distutils', 'distutils.command'],
) )
\end{verbatim} \end{verbatim}
There are only two differences between this and the trivial one-file There are only two differences between this and the trivial one-file
distribution presented in section~\ref{simple-example}: more distribution presented in section~\ref{simple-example}: more
meta-data, and the specification of pure Python modules by package, meta-data, and the specification of pure Python modules by package,
@ -282,6 +298,7 @@ This, of course, only applies to pathnames given to Distutils functions.
If you, for example, use standard python functions such as glob.glob If you, for example, use standard python functions such as glob.glob
or os.listdir to specify files, you should be careful to write portable or os.listdir to specify files, you should be careful to write portable
code instead of hardcoding path separators: code instead of hardcoding path separators:
\begin{verbatim} \begin{verbatim}
glob.glob(os.path.join('mydir', 'subdir', '*.html')) glob.glob(os.path.join('mydir', 'subdir', '*.html'))
os.listdir(os.path.join('mydir', 'subdir')) os.listdir(os.path.join('mydir', 'subdir'))
@ -311,9 +328,11 @@ 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 ``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}, \file{lib}, modules in the \module{foo} package are in \file{lib/foo},
and so forth. Then you would put and so forth. Then you would put
\begin{verbatim} \begin{verbatim}
package_dir = {'': 'lib'} package_dir = {'': 'lib'}
\end{verbatim} \end{verbatim}
in your setup script. (The keys to this dictionary are package names, 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 and an empty package name stands for the root package. The values are
directory names relative to your distribution root.) In this case, when directory names relative to your distribution root.) In this case, when
@ -323,9 +342,11 @@ you say \code{packages = ['foo']}, you are promising that the file
Another possible convention is to put the \module{foo} package right in Another possible convention is to put the \module{foo} package right in
\file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This \file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This
would be written in the setup script as would be written in the setup script as
\begin{verbatim} \begin{verbatim}
package_dir = {'foo': 'lib'} package_dir = {'foo': 'lib'}
\end{verbatim} \end{verbatim}
A \code{\var{package}: \var{dir}} entry in the \option{package\_dir} A \code{\var{package}: \var{dir}} entry in the \option{package\_dir}
dictionary implicitly applies to all packages below \var{package}, so dictionary implicitly applies to all packages below \var{package}, so
the \module{foo.bar} case is automatically handled here. In this the \module{foo.bar} case is automatically handled here. In this
@ -346,9 +367,11 @@ rather than listing packages---especially the case of a single module
that goes in the ``root package'' (i.e., no package at all). This that goes in the ``root package'' (i.e., no package at all). This
simplest case was shown in section~\ref{simple-example}; here is a simplest case was shown in section~\ref{simple-example}; here is a
slightly more involved example: slightly more involved example:
\begin{verbatim} \begin{verbatim}
py_modules = ['mod1', 'pkg.mod2'] py_modules = ['mod1', 'pkg.mod2']
\end{verbatim} \end{verbatim}
This describes two modules, one of them in the ``root'' package, the This describes two modules, one of them in the ``root'' package, the
other in the \module{pkg} package. Again, the default package/directory other in the \module{pkg} package. Again, the default package/directory
layout implies that these two modules can be found in \file{mod1.py} and layout implies that these two modules can be found in \file{mod1.py} and
@ -375,13 +398,16 @@ single extension module. Suppose your distribution includes a single
extension, called \module{foo} and implemented by \file{foo.c}. If no extension, called \module{foo} and implemented by \file{foo.c}. If no
additional instructions to the compiler/linker are needed, describing additional instructions to the compiler/linker are needed, describing
this extension is quite simple: this extension is quite simple:
\begin{verbatim} \begin{verbatim}
Extension("foo", ["foo.c"]) Extension("foo", ["foo.c"])
\end{verbatim} \end{verbatim}
The \class{Extension} class can be imported from The \class{Extension} class can be imported from
\module{distutils.core}, along with \function{setup()}. Thus, the setup \module{distutils.core}, along with \function{setup()}. Thus, the setup
script for a module distribution that contains only this one extension script for a module distribution that contains only this one extension
and nothing else might be: and nothing else might be:
\begin{verbatim} \begin{verbatim}
from distutils.core import setup, Extension from distutils.core import setup, Extension
setup(name="foo", version="1.0", setup(name="foo", version="1.0",
@ -398,13 +424,17 @@ explained in the following sections.
The first argument to the \class{Extension} constructor is always the The first argument to the \class{Extension} constructor is always the
name of the extension, including any package names. For example, name of the extension, including any package names. For example,
\begin{verbatim} \begin{verbatim}
Extension("foo", ["src/foo1.c", "src/foo2.c"]) Extension("foo", ["src/foo1.c", "src/foo2.c"])
\end{verbatim} \end{verbatim}
describes an extension that lives in the root package, while describes an extension that lives in the root package, while
\begin{verbatim} \begin{verbatim}
Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"]) Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"])
\end{verbatim} \end{verbatim}
describes the same extension in the \module{pkg} package. The source describes the same extension in the \module{pkg} package. The source
files and resulting object code are identical in both cases; the only files and resulting object code are identical in both cases; the only
difference is where in the filesystem (and therefore where in Python's difference is where in the filesystem (and therefore where in Python's
@ -413,6 +443,7 @@ namespace hierarchy) the resulting extension lives.
If you have a number of extensions all in the same package (or all under If you have a number of extensions all in the same package (or all under
the same base package), use the \option{ext\_package} keyword argument the same base package), use the \option{ext\_package} keyword argument
to \function{setup()}. For example, to \function{setup()}. For example,
\begin{verbatim} \begin{verbatim}
setup(... setup(...
ext_package="pkg", ext_package="pkg",
@ -420,6 +451,7 @@ setup(...
Extension("subpkg.bar", ["bar.c"])] Extension("subpkg.bar", ["bar.c"])]
) )
\end{verbatim} \end{verbatim}
will compile \file{foo.c} to the extension \module{pkg.foo}, and will compile \file{foo.c} to the extension \module{pkg.foo}, and
\file{bar.c} to \module{pkg.subpkg.bar}. \file{bar.c} to \module{pkg.subpkg.bar}.
@ -458,6 +490,7 @@ define/undefine: \code{include\_dirs}, \code{define\_macros}, and
For example, if your extension requires header files in the For example, if your extension requires header files in the
\file{include} directory under your distribution root, use the \file{include} directory under your distribution root, use the
\code{include\_dirs} option: \code{include\_dirs} option:
\begin{verbatim} \begin{verbatim}
Extension("foo", ["foo.c"], include_dirs=["include"]) Extension("foo", ["foo.c"], include_dirs=["include"])
\end{verbatim} \end{verbatim}
@ -465,9 +498,11 @@ Extension("foo", ["foo.c"], include_dirs=["include"])
You can specify absolute directories there; if you know that your You can specify absolute directories there; if you know that your
extension will only be built on \UNIX{} systems with X11R6 installed to extension will only be built on \UNIX{} systems with X11R6 installed to
\file{/usr}, you can get away with \file{/usr}, you can get away with
\begin{verbatim} \begin{verbatim}
Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"]) Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"])
\end{verbatim} \end{verbatim}
You should avoid this sort of non-portable usage if you plan to You should avoid this sort of non-portable usage if you plan to
distribute your code: it's probably better to write your code to include distribute your code: it's probably better to write your code to include
(e.g.) \code{<X11/Xlib.h>}. (e.g.) \code{<X11/Xlib.h>}.
@ -485,12 +520,14 @@ extensions, the best approach is to include (e.g.)
\file{Numerical} include directory right into your header search path, \file{Numerical} include directory right into your header search path,
though, you can find that directory using the Distutils though, you can find that directory using the Distutils
\module{sysconfig} module: \module{sysconfig} module:
\begin{verbatim} \begin{verbatim}
from distutils.sysconfig import get_python_inc from distutils.sysconfig import get_python_inc
incdir = os.path.join(get_python_inc(plat_specific=1), "Numerical") incdir = os.path.join(get_python_inc(plat_specific=1), "Numerical")
setup(..., setup(...,
Extension(..., include_dirs=[incdir])) Extension(..., include_dirs=[incdir]))
\end{verbatim} \end{verbatim}
Even though this is quite portable---it will work on any Python Even though this is quite portable---it will work on any Python
installation, regardless of platform---it's probably easier to just installation, regardless of platform---it's probably easier to just
write your C code in the sensible way. write your C code in the sensible way.
@ -506,13 +543,16 @@ macro \code{FOO} to \code{None} is the equivalent of a bare
a list of macros to undefine. a list of macros to undefine.
For example: For example:
\begin{verbatim} \begin{verbatim}
Extension(..., Extension(...,
define_macros=[('NDEBUG', '1')], define_macros=[('NDEBUG', '1')],
('HAVE_STRFTIME', None), ('HAVE_STRFTIME', None),
undef_macros=['HAVE_FOO', 'HAVE_BAR']) undef_macros=['HAVE_FOO', 'HAVE_BAR'])
\end{verbatim} \end{verbatim}
is the equivalent of having this at the top of every C source file: is the equivalent of having this at the top of every C source file:
\begin{verbatim} \begin{verbatim}
#define NDEBUG 1 #define NDEBUG 1
#define HAVE_STRFTIME #define HAVE_STRFTIME
@ -532,6 +572,7 @@ search for shared (dynamically loaded) libraries at run-time.
For example, if you need to link against libraries known to be in the For example, if you need to link against libraries known to be in the
standard library search path on target systems standard library search path on target systems
\begin{verbatim} \begin{verbatim}
Extension(..., Extension(...,
libraries=["gdbm", "readline"]) libraries=["gdbm", "readline"])
@ -539,11 +580,13 @@ Extension(...,
If you need to link with libraries in a non-standard location, you'll If you need to link with libraries in a non-standard location, you'll
have to include the location in \code{library\_dirs}: have to include the location in \code{library\_dirs}:
\begin{verbatim} \begin{verbatim}
Extension(..., Extension(...,
library_dirs=["/usr/X11R6/lib"], library_dirs=["/usr/X11R6/lib"],
libraries=["X11", "Xt"]) libraries=["X11", "Xt"])
\end{verbatim} \end{verbatim}
(Again, this sort of non-portable construct should be avoided if you (Again, this sort of non-portable construct should be avoided if you
intend to distribute your code.) intend to distribute your code.)
@ -584,12 +627,14 @@ in this way.
\subsection{Listing additional files} \subsection{Listing additional files}
The \option{data\_files} option can be used to specify additional The \option{data\_files} option can be used to specify additional
files needed by the module distribution: configuration files, files needed by the module distribution: configuration files,
data files, anything which does not fit in the previous categories. data files, anything which does not fit in the previous categories.
\option{data\_files} specify a sequence of \code{(directory, files)} \option{data\_files} specify a sequence of \code{(directory, files)}
pairs in the following way: pairs in the following way:
\begin{verbatim} \begin{verbatim}
setup(... setup(...
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
@ -625,9 +670,6 @@ then you need the Distutils ``auto-configuration'' facility. This
started to appear in Distutils 0.9 but, as of this writing, isn't mature started to appear in Distutils 0.9 but, as of this writing, isn't mature
or stable enough yet for real-world use.) or stable enough yet for real-world use.)
\XXX{should reference description of distutils config files in
``Installing'' manual here}
The setup configuration file is a useful middle-ground between the setup The setup configuration file is a useful middle-ground between the setup
script---which, ideally, would be opaque to installers\footnote{This script---which, ideally, would be opaque to installers\footnote{This
ideal probably won't be achieved until auto-configuration is fully ideal probably won't be achieved until auto-configuration is fully
@ -647,11 +689,13 @@ several useful consequences:
\end{itemize} \end{itemize}
The basic syntax of the configuration file is simple: The basic syntax of the configuration file is simple:
\begin{verbatim} \begin{verbatim}
[command] [command]
option=value option=value
... ...
\end{verbatim} \end{verbatim}
where \var{command} is one of the Distutils commands (e.g. where \var{command} is one of the Distutils commands (e.g.
\command{build\_py}, \command{install}), and \var{option} is one of the \command{build\_py}, \command{install}), and \var{option} is one of the
options that command supports. Any number of options can be supplied options that command supports. Any number of options can be supplied
@ -662,6 +706,7 @@ split across multiple lines simply by indenting the continuation lines.
You can find out the list of options supported by a particular command You can find out the list of options supported by a particular command
with the universal \longprogramopt{help} option, e.g. with the universal \longprogramopt{help} option, e.g.
\begin{verbatim} \begin{verbatim}
> python setup.py --help build_ext > python setup.py --help build_ext
[...] [...]
@ -675,6 +720,7 @@ Options for 'build_ext' command:
--undef (-U) C preprocessor macros to undefine --undef (-U) C preprocessor macros to undefine
[...] [...]
\end{verbatim} \end{verbatim}
Or consult section \ref{reference} of this document (the command Or consult section \ref{reference} of this document (the command
reference). reference).
@ -687,17 +733,21 @@ want the compiled extension file (\file{ext.so} on \UNIX, say) to be put
in the same source directory as your pure Python modules in the same source directory as your pure Python modules
\module{pkg.mod1} and \module{pkg.mod2}. You can always use the \module{pkg.mod1} and \module{pkg.mod2}. You can always use the
\longprogramopt{inplace} option on the command-line to ensure this: \longprogramopt{inplace} option on the command-line to ensure this:
\begin{verbatim} \begin{verbatim}
python setup.py build_ext --inplace python setup.py build_ext --inplace
\end{verbatim} \end{verbatim}
But this requires that you always specify the \command{build\_ext} But this requires that you always specify the \command{build\_ext}
command explicitly, and remember to provide \longprogramopt{inplace}. command explicitly, and remember to provide \longprogramopt{inplace}.
An easier way is to ``set and forget'' this option, by encoding it in An easier way is to ``set and forget'' this option, by encoding it in
\file{setup.cfg}, the configuration file for this distribution: \file{setup.cfg}, the configuration file for this distribution:
\begin{verbatim} \begin{verbatim}
[build_ext] [build_ext]
inplace=1 inplace=1
\end{verbatim} \end{verbatim}
This will affect all builds of this module distribution, whether or not This will affect all builds of this module distribution, whether or not
you explcitly specify \command{build\_ext}. If you include you explcitly specify \command{build\_ext}. If you include
\file{setup.cfg} in your source distribution, it will also affect \file{setup.cfg} in your source distribution, it will also affect
@ -717,6 +767,7 @@ files installed). But some of it has to be supplied as options to
\command{bdist\_rpm}, which would be very tedious to do on the \command{bdist\_rpm}, which would be very tedious to do on the
command-line for every run. Hence, here is a snippet from the command-line for every run. Hence, here is a snippet from the
Distutils' own \file{setup.cfg}: Distutils' own \file{setup.cfg}:
\begin{verbatim} \begin{verbatim}
[bdist_rpm] [bdist_rpm]
release = 1 release = 1
@ -727,19 +778,29 @@ doc_files = CHANGES.txt
doc/ doc/
examples/ examples/
\end{verbatim} \end{verbatim}
Note that the \option{doc\_files} option is simply a Note that the \option{doc\_files} option is simply a
whitespace-separated string split across multiple lines for readability. whitespace-separated string split across multiple lines for readability.
\begin{seealso}
\seetitle[../inst/config-syntax.html]{Installing Python
Modules}{More information on the configuration files is
available in the manual for system administrators.}
\end{seealso}
\section{Creating a Source Distribution} \section{Creating a Source Distribution}
\label{source-dist} \label{source-dist}
As shown in section~\ref{simple-example}, you use the As shown in section~\ref{simple-example}, you use the
\command{sdist} command to create a source distribution. In the \command{sdist} command to create a source distribution. In the
simplest case, simplest case,
\begin{verbatim} \begin{verbatim}
python setup.py sdist python setup.py sdist
\end{verbatim} \end{verbatim}
(assuming you haven't specified any \command{sdist} options in the setup (assuming you haven't specified any \command{sdist} options in the setup
script or config file), \command{sdist} creates the archive of the script or config file), \command{sdist} creates the archive of the
default format for the current platform. The default format is gzip'ed default format for the current platform. The default format is gzip'ed
@ -748,9 +809,11 @@ tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows.
You can specify as many formats as you like using the You can specify as many formats as you like using the
\longprogramopt{formats} option, for example: \longprogramopt{formats} option, for example:
\begin{verbatim} \begin{verbatim}
python setup.py sdist --formats=gztar,zip python setup.py sdist --formats=gztar,zip
\end{verbatim} \end{verbatim}
to create a gzipped tarball and a zip file. The available formats are: to create a gzipped tarball and a zip file. The available formats are:
\begin{tableiii}{l|l|c}{code}% \begin{tableiii}{l|l|c}{code}%
{Format}{Description}{Notes} {Format}{Description}{Notes}
@ -810,11 +873,13 @@ The manifest template has one command per line, where each command
specifies a set of files to include or exclude from the source specifies a set of files to include or exclude from the source
distribution. For an example, again we turn to the Distutils' own distribution. For an example, again we turn to the Distutils' own
manifest template: manifest template:
\begin{verbatim} \begin{verbatim}
include *.txt include *.txt
recursive-include examples *.txt *.py recursive-include examples *.txt *.py
prune examples/sample?/build prune examples/sample?/build
\end{verbatim} \end{verbatim}
The meanings should be fairly clear: include all files in the The meanings should be fairly clear: include all files in the
distribution root matching \code{*.txt}, all files anywhere under the distribution root matching \code{*.txt}, all files anywhere under the
\file{examples} directory matching \code{*.txt} or \code{*.py}, and \file{examples} directory matching \code{*.txt} or \code{*.py}, and
@ -905,15 +970,18 @@ Second, you might want to force the manifest to be regenerated---for
example, if you have added or removed files or directories that match an example, if you have added or removed files or directories that match an
existing pattern in the manifest template, you should regenerate the existing pattern in the manifest template, you should regenerate the
manifest: manifest:
\begin{verbatim} \begin{verbatim}
python setup.py sdist --force-manifest python setup.py sdist --force-manifest
\end{verbatim} \end{verbatim}
Or, you might just want to (re)generate the manifest, but not create a Or, you might just want to (re)generate the manifest, but not create a
source distribution: source distribution:
\begin{verbatim} \begin{verbatim}
python setup.py sdist --manifest-only python setup.py sdist --manifest-only
\end{verbatim} \end{verbatim}
\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}. \longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.
\programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and \programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and
\programopt{-f} for \longprogramopt{force-manifest}. \programopt{-f} for \longprogramopt{force-manifest}.
@ -953,9 +1021,11 @@ distributions.
As a simple example, if I run the following command in the Distutils As a simple example, if I run the following command in the Distutils
source tree: source tree:
\begin{verbatim} \begin{verbatim}
python setup.py bdist python setup.py bdist
\end{verbatim} \end{verbatim}
then the Distutils builds my module distribution (the Distutils itself then the Distutils builds my module distribution (the Distutils itself
in this case), does a ``fake'' installation (also in the \file{build} in this case), does a ``fake'' installation (also in the \file{build}
directory), and creates the default type of built distribution for my directory), and creates the default type of built distribution for my
@ -983,9 +1053,11 @@ win for users even if your distribution doesn't include any extensions.
The \command{bdist} command has a \longprogramopt{formats} option, The \command{bdist} command has a \longprogramopt{formats} option,
similar to the \command{sdist} command, which you can use to select the similar to the \command{sdist} command, which you can use to select the
types of built distribution to generate: for example, types of built distribution to generate: for example,
\begin{verbatim} \begin{verbatim}
python setup.py bdist --format=zip python setup.py bdist --format=zip
\end{verbatim} \end{verbatim}
would, when run on a \UNIX{} system, create would, when run on a \UNIX{} system, create
\file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be \file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be
unpacked from the root directory to install the Distutils. unpacked from the root directory to install the Distutils.
@ -1054,17 +1126,22 @@ work on different RPM-based distributions.
The usual way to create an RPM of your module distribution is to run the The usual way to create an RPM of your module distribution is to run the
\command{bdist\_rpm} command: \command{bdist\_rpm} command:
\begin{verbatim} \begin{verbatim}
python setup.py bdist_rpm python setup.py bdist_rpm
\end{verbatim} \end{verbatim}
or the \command{bdist} command with the \longprogramopt{format} option: or the \command{bdist} command with the \longprogramopt{format} option:
\begin{verbatim} \begin{verbatim}
python setup.py bdist --formats=rpm python setup.py bdist --formats=rpm
\end{verbatim} \end{verbatim}
The former allows you to specify RPM-specific options; the latter allows 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 you to easily specify multiple formats in one run. If you need to do
both, you can explicitly specify multiple \command{bdist\_*} commands both, you can explicitly specify multiple \command{bdist\_*} commands
and their options: and their options:
\begin{verbatim} \begin{verbatim}
python setup.py bdist_rpm --packager="John Doe <jdoe@python.net>" \ python setup.py bdist_rpm --packager="John Doe <jdoe@python.net>" \
bdist_wininst --target_version="2.0" bdist_wininst --target_version="2.0"
@ -1143,11 +1220,13 @@ You can also specify a custom \file{.spec} file with the
\longprogramopt{spec-file} option; used in conjunction with \longprogramopt{spec-file} option; used in conjunction with
\longprogramopt{spec-only}, this gives you an opportunity to customize \longprogramopt{spec-only}, this gives you an opportunity to customize
the \file{.spec} file manually: the \file{.spec} file manually:
\begin{verbatim} \begin{verbatim}
> python setup.py bdist_rpm --spec-only > python setup.py bdist_rpm --spec-only
# ...edit dist/FooBar-1.0.spec # ...edit dist/FooBar-1.0.spec
> python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
\end{verbatim} \end{verbatim}
(Although a better way to do this is probably to override the standard (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 \command{bdist\_rpm} command with one that writes whatever else you want
to the \file{.spec} file; see section~\ref{extending} for information on to the \file{.spec} file; see section~\ref{extending} for information on
@ -1165,10 +1244,13 @@ from the meta-dada in the setup script, let the user select a few
Since the meta-data is taken from the setup script, creating Since the meta-data is taken from the setup script, creating
Windows installers is usually as easy as running: Windows installers is usually as easy as running:
\begin{verbatim} \begin{verbatim}
python setup.py bdist_wininst python setup.py bdist_wininst
\end{verbatim} \end{verbatim}
or the \command{bdist} command with the \longprogramopt{format} option: or the \command{bdist} command with the \longprogramopt{format} option:
\begin{verbatim} \begin{verbatim}
python setup.py bdist --formats=wininst python setup.py bdist --formats=wininst
\end{verbatim} \end{verbatim}
@ -1190,42 +1272,42 @@ If you don't want this to happen for some reason, you can run
the bdist_wininst command with the \longprogramopt{no-target-compile} and/or the bdist_wininst command with the \longprogramopt{no-target-compile} and/or
the \longprogramopt{no-target-optimize} option. the \longprogramopt{no-target-optimize} option.
\section{Examples} %\section{Examples}
\label{examples} %\label{examples}
\subsection{Pure Python distribution (by module)} %\subsection{Pure Python distribution (by module)}
\label{pure-mod} %\label{pure-mod}
\subsection{Pure Python distribution (by package)} %\subsection{Pure Python distribution (by package)}
\label{pure-pkg} %\label{pure-pkg}
\subsection{Single extension module} %\subsection{Single extension module}
\label{single-ext} %\label{single-ext}
\subsection{Multiple extension modules} %\subsection{Multiple extension modules}
\label{multiple-ext} %\label{multiple-ext}
\subsection{Putting it all together} %\subsection{Putting it all together}
\section{Extending the Distutils} %\section{Extending the Distutils}
\label{extending} %\label{extending}
\subsection{Extending existing commands} %\subsection{Extending existing commands}
\label{extend-existing} %\label{extend-existing}
\subsection{Writing new commands} %\subsection{Writing new commands}
\label{new-commands} %\label{new-commands}
\XXX{Would an uninstall command be a good example here?} %\XXX{Would an uninstall command be a good example here?}
@ -1233,20 +1315,20 @@ the \longprogramopt{no-target-optimize} option.
\label{reference} \label{reference}
\subsection{Building modules: the \protect\command{build} command family} %\subsection{Building modules: the \protect\command{build} command family}
\label{build-cmds} %\label{build-cmds}
\subsubsection{\protect\command{build}} %\subsubsection{\protect\command{build}}
\label{build-cmd} %\label{build-cmd}
\subsubsection{\protect\command{build\_py}} %\subsubsection{\protect\command{build\_py}}
\label{build-py-cmd} %\label{build-py-cmd}
\subsubsection{\protect\command{build\_ext}} %\subsubsection{\protect\command{build\_ext}}
\label{build-ext-cmd} %\label{build-ext-cmd}
\subsubsection{\protect\command{build\_clib}} %\subsubsection{\protect\command{build\_clib}}
\label{build-clib-cmd} %\label{build-clib-cmd}
\subsection{Installing modules: the \protect\command{install} command family} \subsection{Installing modules: the \protect\command{install} command family}
@ -1257,8 +1339,8 @@ runs the subcommands \command{install\_lib},
\command{install\_data} and \command{install\_data} and
\command{install\_scripts}. \command{install\_scripts}.
\subsubsection{\protect\command{install\_lib}} %\subsubsection{\protect\command{install\_lib}}
\label{install-lib-cmd} %\label{install-lib-cmd}
\subsubsection{\protect\command{install\_data}} \subsubsection{\protect\command{install\_data}}
\label{install-data-cmd} \label{install-data-cmd}
@ -1269,8 +1351,8 @@ This command installs all data files provided with the distribution.
This command installs all (Python) scripts in the distribution. This command installs all (Python) scripts in the distribution.
\subsection{Cleaning up: the \protect\command{clean} command} %\subsection{Cleaning up: the \protect\command{clean} command}
\label{clean-cmd} %\label{clean-cmd}
\subsection{Creating a source distribution: the \subsection{Creating a source distribution: the
@ -1310,24 +1392,18 @@ anything except backslash or colon; on MacOS anything except colon.
\XXX{Windows and MacOS support not there yet} \XXX{Windows and MacOS support not there yet}
\subsection{Creating a ``built'' distribution: the %\subsection{Creating a built distribution: the
\protect\command{bdist} command family} % \protect\command{bdist} command family}
\label{bdist-cmds} %\label{bdist-cmds}
\subsubsection{\protect\command{blib}}
\subsubsection{\protect\command{blib\_dumb}}
\subsubsection{\protect\command{blib\_rpm}}
\subsubsection{\protect\command{blib\_wise}}
%\subsubsection{\protect\command{blib}}
%\subsubsection{\protect\command{blib\_dumb}}
%\subsubsection{\protect\command{blib\_rpm}}
%\subsubsection{\protect\command{blib\_wise}}
\end{document} \end{document}