%Abstract this!
%\end{abstract}
+
+% The ugly "%begin{latexonly}" pseudo-environment supresses the table
+% of contents for HTML generation.
+%
+%begin{latexonly}
\tableofcontents
+%end{latexonly}
+
\section{Introduction}
\label{intro}
setup script \file{setup.py}, and a \file{README.txt} (or possibly
\file{README}), which should explain that building and installing the
module distribution is a simple matter of running
+
\begin{verbatim}
python setup.py install
\end{verbatim}
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}
+
On \UNIX, you'd run this command from a shell prompt; on Windows, you
have to open a command prompt window (``DOS box'') and do it there; on
MacOS, things are a tad more complicated (see below).
distribution unpacks into. For example, if you've just downloaded a
module source distribution \file{foo-1.0.tar.gz} onto a
\UNIX{} system, the normal thing to do is:
+
\begin{verbatim}
gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
cd foo-1.0
command-line tool (such as \program{unzip} or \program{pkunzip}) to
unpack the archive. Then, open a command prompt window (``DOS box''),
and run:
+
\begin{verbatim}
cd c:\Temp\foo-1.0
python setup.py install
For example, you can build everything in one step, and then install
everything in a second step, by invoking the setup script twice:
+
\begin{verbatim}
python setup.py build
python setup.py install
\end{verbatim}
+
(If you do this, you will notice that running the \command{install}
command first runs the \command{build} command, which---in this
case---quickly notices that it has nothing to do, since everything in
concerned with speed, or want to keep the source tree pristine, you can
change the build directory with the \longprogramopt{build-base} option.
For example:
+
\begin{verbatim}
python setup.py build --build-base=/tmp/pybuild/foo-1.0
\end{verbatim}
+
(Or you could do this permanently with a directive in your system or
personal Distutils configuration file; see
section~\ref{config-files}.) Normally, this isn't necessary.
The default layout for the build tree is as follows:
+
\begin{verbatim}
--- build/ --- lib/
or
--- build/ --- lib.<plat>/
temp.<plat>/
\end{verbatim}
+
where \code{<plat>} expands to a brief description of the current
OS/hardware platform and Python version. The first form, with just a
\file{lib} directory, is used for ``pure module distributions''---that
\end{itemize}
-\subsection{Tweaking compiler/linker flags}
-\label{tweak-flags}
+%\subsection{Tweaking compiler/linker flags}
+%\label{tweak-flags}
\subsection{Using non-Microsoft compilers on Windows}
The idea behind the ``home scheme'' is that you build and maintain a
personal stash of Python modules, probably under your home directory.
Installing a new module distribution is as simple as
+
\begin{verbatim}
python setup.py install --home=<dir>
\end{verbatim}
+
where you can supply any directory you like for the \longprogramopt{home}
option. Lazy typists can just type a tilde (\code{\textasciitilde}); the
\command{install} command will expand this to your home directory:
+
\begin{verbatim}
python setup.py install --home=~
\end{verbatim}
modules from source, you probably want them to go in
\file{/usr/local/lib/python1.\filevar{X}} rather than
\file{/usr/lib/python1.\filevar{X}}. This can be done with
+
\begin{verbatim}
/usr/bin/python setup.py install --prefix=/usr/local
\end{verbatim}
but those modules would have to be installed to, say,
\file{/mnt/\filevar{@server}/export/lib/python1.\filevar{X}}. This
could be done with
+
\begin{verbatim}
/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
\end{verbatim}
under \UNIX, there's no point in having separate \longprogramopt{prefix}
and \longprogramopt{home} options. Just use the \longprogramopt{prefix}
option to specify a base directory, e.g.
+
\begin{verbatim}
python setup.py install --prefix="\Temp\Python"
\end{verbatim}
+
to install modules to the \file{\textbackslash{}Temp} directory on the current
drive.
\longprogramopt{install-scripts} option; in this case, it makes most
sense to supply a relative path, which will be interpreted relative to
the installation base directory (your home directory, in this case):
+
\begin{verbatim}
python setup.py install --home=~ --install-scripts=scripts
\end{verbatim}
installation scripts will wind up in \file{/usr/local/python/bin}. If
you want them in \file{/usr/local/bin} instead, you would supply this
absolute directory for the \longprogramopt{install-scripts} option:
+
\begin{verbatim}
python setup.py install --install-scripts=/usr/local/bin
\end{verbatim}
+
(This performs an installation using the ``prefix scheme,'' where the
prefix is whatever your Python interpreter was installed with---
\file{/usr/local/python} in this case.)
script installation directory---you just have to remember that there are
two types of modules to worry about, pure modules and non-pure modules
(i.e., modules from a non-pure distribution). For example:
+
\begin{verbatim}
python setup.py install --install-purelib=Site --install-platlib=Site
\end{verbatim}
+
The specified installation directories are relative to \filevar{prefix}.
Of course, you also have to ensure that these directories are in
Python's module search path, e.g. by putting a \file{.pth} file in
home directory, and you want a separate directory for each platform that
you use your home directory from, you might define the following
installation scheme:
+
\begin{verbatim}
python setup.py install --home=~ \
--install-purelib=python/lib \
--install-scripts=python/scripts
--install-data=python/data
\end{verbatim}
+% $ % -- bow to font-lock
+
or, equivalently,
+
\begin{verbatim}
python setup.py install --home=~/python \
--install-purelib=lib \
--install-scripts=scripts
--install-data=data
\end{verbatim}
+% $ % -- bow to font-lock
+
\code{\$PLAT} is not (necessarily) an environment variable---it will be
expanded by the Distutils as it parses your command line options (just
as it does when parsing your configuration file(s)).
install a new module distribution would be very tedious. Thus, you can
put these options into your Distutils config file (see
section~\ref{config-files}):
+
\begin{verbatim}
[install]
install-base=$HOME
install-scripts=python/scripts
install-data=python/data
\end{verbatim}
+
or, equivalently,
+
\begin{verbatim}
[install]
install-base=$HOME/python
install-scripts=scripts
install-data=data
\end{verbatim}
+
Note that these two are \emph{not} equivalent if you supply a different
installation base directory when you run the setup script. For example,
+
\begin{verbatim}
python setup.py --install-base=/tmp
\end{verbatim}
+
would install pure modules to \filevar{/tmp/python/lib} in the first
case, and to \filevar{/tmp/lib} in the second case. (For the second
case, you probably want to supply an installation base of
For example, the following is a complete config file that just forces
all commands to run quietly by default:
+
\begin{verbatim}
[global]
verbose=0
You could override the default ``build base'' directory and make the
\command{build*} commands always forcibly rebuild all files with the
following:
+
\begin{verbatim}
[build]
build-base=blib
force=1
\end{verbatim}
+
which corresponds to the command-line arguments
+
\begin{verbatim}
python setup.py build --build-base=blib --force
\end{verbatim}
+
except that including the \command{build} command on the command-line
means that command will be run. Including a particular command in
config files has no such implication; it only means that if the command
You can find out the complete list of options for any command using the
\longprogramopt{help} option, e.g.:
+
\begin{verbatim}
python setup.py build --help
\end{verbatim}
+
and you can find out the complete list of global options by using
\longprogramopt{help} without a command:
+
\begin{verbatim}
python setup.py --help
\end{verbatim}
+
See also the ``Reference'' section of the ``Distributing Python
Modules'' manual.
-\section{Pre-Distutils Conventions}
-\label{pre-distutils}
-
+%\section{Pre-Distutils Conventions}
+%\label{pre-distutils}
-\subsection{The Makefile.pre.in file}
-\label{makefile-pre-in}
+%\subsection{The Makefile.pre.in file}
+%\label{makefile-pre-in}
-\subsection{Installing modules manually}
-\label{manual-install}
+%\subsection{Installing modules manually}
+%\label{manual-install}
\end{document}
projects / python / commitdiff