\tableofcontents
\section{Introduction}
-\label{sec:intro}
+\label{intro}
In the past, Python module developers have not had much infrastructure
support for distributing modules, nor have Python users had much support
\section{Concepts \& Terminology}
-\label{sec:concepts}
+\label{concepts}
Using the Distutils is quite simple, both for module developers and for
users/administrators installing third-party modules. As a developer,
\subsection{A simple example}
-\label{sec:simple-example}
+\label{simple-example}
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
\subsection{General Python terminology}
-\label{sec:python-terms}
+\label{python-terms}
If you're reading this document, you probably have a good idea of what
modules, extensions, and so forth are. Nevertheless, just to be sure
\subsection{Distutils-specific terminology}
-\label{sec:distutils-term}
+\label{distutils-term}
The following terms apply more specifically to the domain of
distributing Python modules using the Distutils:
\section{Writing the Setup Script}
-\label{sec:setup-script}
+\label{setup-script}
The setup script is the centre of all activity in building,
distributing, and installing modules using the Distutils. The main
purpose of the setup script is to describe your module distribution to
the Distutils, so that the various commands that operate on your modules
-do the right thing. As we saw in section~\ref{sec:simple-example}
+do the right thing. As we saw in section~\ref{simple-example}
above, the setup script consists mainly of a call to \function{setup()},
and all information supplied to the Distutils is suppled as keyword
arguments to \function{setup()}.
)
\end{verbatim}
There are only two differences between this and the trivial one-file
-distribution presented in section~\ref{sec:simple-example}: more
+distribution presented in section~\ref{simple-example}: more
meta-data, and the specification of pure Python modules by package,
rather than by module. This is important since the Distutils consist of
a couple of dozen modules split into (so far) two packages; an explicit
\subsection{Package directories}
-\label{sec:package-dirs}
+\label{package-dirs}
The \option{packages} option tells the Distutils to process (build,
distribute, install, etc.) all pure Python modules found in each package
\subsection{Listing individual modules}
-\label{sec:listing-modules}
+\label{listing-modules}
For a small module distribution, you might prefer to list all modules
rather than listing packages---especially the case of a single module
that goes in the ``root package'' (i.e., no package at all). This
-simplest case was shown in section~\ref{sec:simple-example}; here is a
+simplest case was shown in section~\ref{simple-example}; here is a
slightly more involved example:
\begin{verbatim}
py_modules = ['mod1', 'pkg.mod2']
\section{Writing the Setup Configuration File}
-\label{sec:setup-config}
+\label{setup-config}
\XXX{not implemented yet!}
\section{Creating a Source Distribution}
-\label{sec:source-dist}
+\label{source-dist}
-As shown in section~\ref{sec: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
simplest case,
\begin{verbatim}
\subsection{The manifest and manifest template}
-\label{sec:manifest}
+\label{manifest}
Without any additional information, the \command{sdist} command puts a
minimal set of files into the source distribution:
\file{examples} directory matching \code{*.txt} or \code{*.py}, and
exclude all directories matching \code{examples/sample?/build}. There
are several other commands available in the manifest template
-mini-language; see section~\ref{sec:sdist-cmd}.
+mini-language; see section~\ref{sdist-cmd}.
The order of commands in the manifest template very much matters:
initially, we have the list of default files as described above, and
\subsection{Manifest-related options}
-\label{sec:manifest-options}
+\label{manifest-options}
The normal course of operations for the \command{sdist} command is as
follows:
\section{Creating Built Distributions}
-\label{sec:built-dist}
+\label{built-dist}
A ``built distribution'' is what you're probably used to thinking of
either as a ``binary package'' or an ``installer'' (depending on your
\end{tableii}
\section{Examples}
-\label{sec:examples}
+\label{examples}
\subsection{Pure Python distribution (by module)}
-\label{sec:pure-mod}
+\label{pure-mod}
\subsection{Pure Python distribution (by package)}
-\label{sec:pure-pkg}
+\label{pure-pkg}
\subsection{Single extension module}
-\label{sec:single-ext}
+\label{single-ext}
\subsection{Multiple extension modules}
-\label{sec:multiple-ext}
+\label{multiple-ext}
\subsection{Putting it all together}
\section{Extending the Distutils}
-\label{sec:extending}
+\label{extending}
\subsection{Extending existing commands}
-\label{sec:extend-existing}
+\label{extend-existing}
\subsection{Writing new commands}
-\label{sec:new-commands}
+\label{new-commands}
\section{Reference}
-\label{sec:ref}
+\label{ref}
\subsection{Building modules: the \protect\command{build} command family}
-\label{sec:build-cmds}
+\label{build-cmds}
\subsubsection{\protect\command{build}}
-\label{sec:build-cmd}
+\label{build-cmd}
\subsubsection{\protect\command{build\_py}}
-\label{sec:build-py-cmd}
+\label{build-py-cmd}
\subsubsection{\protect\command{build\_ext}}
-\label{sec:build-ext-cmd}
+\label{build-ext-cmd}
\subsubsection{\protect\command{build\_clib}}
-\label{sec:build-clib-cmd}
+\label{build-clib-cmd}
\subsection{Installing modules: the \protect\command{install} command family}
-\label{sec:install-cmd}
+\label{install-cmd}
\subsection{Cleaning up: the \protect\command{clean} command}
-\label{sec:clean-cmd}
+\label{clean-cmd}
\subsection{Creating a source distribution: the \protect\command{sdist} command}
-\label{sec:sdist-cmd}
+\label{sdist-cmd}
\XXX{fragment moved down from above: needs context!}
\subsection{Creating a ``built'' distribution: the
\protect\command{bdist} command family}
-\label{sec:bdist-cmds}
+\label{bdist-cmds}
\subsubsection{\protect\command{blib}}
\tableofcontents
\section{Introduction}
-\label{sec:intro}
+\label{intro}
Although Python's extensive standard library covers many programming
needs, there often comes a time when you need to add some new
\subsection{Best case: trivial installation}
-\label{sec:trivial-inst}
+\label{trivial-inst}
In the best case, someone will have prepared a special version of the
module distribution you want to install that is targeted specifically at
\subsection{The new standard: Distutils}
-\label{sec:new-standard}
+\label{new-standard}
If you download a module source distribution, you can tell pretty
quickly if was packaged and distributed in the standard way, i.e. using
\subsection{The old way: no standards}
-\label{sec:old-way}
+\label{old-way}
Before the Distutils, there was no infrastructure to support installing
third-party modules in a consistent, standardized way. Thus, it's not
here.
All of the pre-Distutils material is tucked away in
-section~\ref{sec:pre-distutils}.
+section~\ref{pre-distutils}.
\section{Standard Build and Install}
-\label{sec:normal-install}
+\label{normal-install}
-As described in section~\ref{sec:new-standard}, building and installing
+As described in section~\ref{new-standard}, building and installing
a module distribution using the Distutils is usually one simple command:
\begin{verbatim}
python setup.py install
\end{verbatim}
(Or you could do this permanently with a directive in your system or
personal Distutils configuration file; see
-section~\ref{sec:config-files}.) Normally, this isn't necessary.
+section~\ref{config-files}.) Normally, this isn't necessary.
The default layout for the build tree is as follows:
\begin{verbatim}
\end{tableiii}}
\section{Alternate Installation}
-\label{sec:alt-install}
+\label{alt-install}
Often, it is necessary or desirable to install modules to a location
other than the standard location for third-party Python modules. For
\subsection{Alternate installation: Unix (the home scheme)}
-\label{sec:alt-unix-prefix}
+\label{alt-unix-prefix}
Under Unix, there are two ways to perform an alternate installation.
The ``prefix scheme'' is similar to how alternate installation works
{home}{/share}
\subsection{Alternate installation: Unix (the prefix scheme)}
-\label{sec:alt-unix-home}
+\label{alt-unix-home}
The ``prefix scheme'' is useful when you wish to use one Python
installation to perform the build/install (i.e., to run the setup
\subsection{Alternate installation: Windows}
-\label{sec:alt-windows}
+\label{alt-windows}
Since Windows has no conception of a user's home directory, and since
the standard Python installation under Windows is simpler than that
\subsection{Alternate installation: Mac~OS}
-\label{sec:alt-macos}
+\label{alt-macos}
Like Windows, Mac~OS has no notion of home directories (or even of
users), and a fairly simple standard Python installation. Thus, only a
\section{Custom Installation}
-\label{sec:custom-install}
+\label{custom-install}
Sometimes, the alternate installation schemes described in
-section~\ref{sec:alt-install} just don't do what you want. You might
+section~\ref{alt-install} just don't do what you want. You might
want to tweak just one or two directories while keeping everything under
the same base directory, or you might want to completely redefine the
installation scheme. In either case, you're creating a \emph{custom
Obviously, specifying the entire installation scheme every time you
install a new module distribution would be very tedious. Thus, you can
put these options into your Distutils config file (see
-section~\ref{sec:config-files}):
+section~\ref{config-files}):
\begin{verbatim}
[install]
install-base=$HOME
\code{\$PLAT}. (And of course, you can only use the configuration
variables supplied by the Distutils on systems that don't have
environment variables, such as Mac~OS (\XXX{true?}).) See
-section~\ref{sec:config-files} for details.
+section~\ref{config-files} for details.
\XXX{need some Windows and Mac~OS examples---when would custom
installation schemes be needed on those platforms?}
\section{Distutils Configuration Files}
-\label{sec:config-files}
+\label{config-files}
\XXX{not even implemented yet, much less documented!}
\section{Pre-Distutils Conventions}
-\label{sec:pre-distutils}
+\label{pre-distutils}
\subsection{The Makefile.pre.in file}
-\label{sec:makefile-pre-in}
+\label{makefile-pre-in}
\subsection{Installing modules manually}
-\label{sec:manual-install}
+\label{manual-install}
projects / python / commitdiff