As described in section 1.2, building and installing
a module distribution using the Distutils is usually one simple command:
python setup.py install
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
Mac OS, things are a tad more complicated (see below).
2.1 Platform variations
You should always run the setup command from the distribution root
directory, i.e. the top-level subdirectory that the module source
distribution unpacks into. For example, if you've just downloaded a
module source distribution foo-1.0.tar.gz onto a
Unix system, the normal thing to do is:
gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install
On Windows, you'd probably download foo-1.0.zip. If you
downloaded the archive file to C:\Temp, then it
would unpack into C:\Temp\foo-1.0;
you can use either a archive manipulator with a grapical user interface
(such as WinZip) or a command-line tool (such as unzip or
pkunzip) to unpack the archive. Then, open a command prompt
window (``DOS box''), and run:
cd c:\Temp\foo-1.0
python setup.py install
On Mac OS, you have to go through a bit more effort to supply
command-line arguments to the setup script:
hit option-double-click on the script's icon (or option-drop it
onto the Python interpreter's icon)
press the ``Set unix-style command line'' button
set the ``Keep stdio window open on termination'' if you're
interested in seeing the output of the setup script (which is usually
voluminous and often useful)
when the command-line dialog pops up, enter ``install'' (you
can, of course, enter any Distutils command-line as described in this
document or in Distributing Python
Modules: just leave off the initial python setup.py and
you'll be fine)
** this should change: every Distutils setup script will need
command-line arguments for every run (and should probably keep stdout
around), so all this should happen automatically for setup scripts **
2.2 Splitting the job up
Running setup.py install builds and installs all modules in one
run. If you prefer to work incrementally--especially useful if you
want to customize the build process, or if things are going wrong--you
can use the setup script to do one thing at a time. This is
particularly helpful when the build and install will be done by
different users--e.g., you might want to build a module distribution
and hand it off to a system administrator for installation (or do it
yourself, with super-user privileges).
For example, you can build everything in one step, and then install
everything in a second step, by invoking the setup script twice:
python setup.py build
python setup.py install
(If you do this, you will notice that running the install
command first runs the build command, which--in this
case--quickly notices that it has nothing to do, since everything in
the build directory is up-to-date.)
You may not need this ability to break things down often if all you do
is install modules downloaded off the 'net, but it's very handy for more
advanced tasks. If you get into distributing your own Python modules
and extensions, you'll run lots of individual Distutils commands on
their own.
2.3 How building works
As implied above, the build command is responsible for putting
the files to install into a build directory. By default, this is
build under the distribution root; if you're excessively
concerned with speed, or want to keep the source tree pristine, you can
change the build directory with the --build-base option.
For example:
(Or you could do this permanently with a directive in your system or
personal Distutils configuration file; see
section 6.) Normally, this isn't necessary.
The default layout for the build tree is as follows:
--- build/ --- lib/
or
--- build/ --- lib.<plat>/
temp.<plat>/
where <plat> expands to a brief description of the current
OS/hardware platform and Python version. The first form, with just a
lib directory, is used for ``pure module distributions''--that
is, module distributions that include only pure Python modules. If a
module distribution contains any extensions (modules written in C/C++),
then the second form, with two <plat> directories, is used. In
that case, the temp.plat directory holds temporary
files generated by the compile/link process that don't actually get
installed. In either case, the lib (or
lib.plat) directory contains all Python modules (pure
Python and extensions) that will be installed.
In the future, more directories will be added to handle Python scripts,
documentation, binary executables, and whatever else is needed to handle
the job of installing Python modules and applications.
2.4 How installation works
After the build command runs (whether you run it explicitly,
or the install command does it for you), the work of the
install command is relatively simple: all it has to do is copy
everything under build/lib (or build/lib.plat)
to your chosen installation directory.
If you don't choose an installation directory--i.e., if you just run
setup.py install--then the install command installs to
the standard location for third-party Python modules. This location
varies by platform and by how you built/installed Python itself. On
Unix and Mac OS, it also depends on whether the module distribution
being installed is pure Python or contains extensions (``non-pure''):
Platform
Standard installation location
Default value
Notes
Unix (pure)
prefix/lib/python2.0/site-packages
/usr/local/lib/python2.0/site-packages
(1)
Unix (non-pure)
exec-prefix/lib/python2.0/site-packages
/usr/local/lib/python2.0/site-packages
(1)
Windows
prefix
C:\Python
(2)
Mac OS (pure)
prefix:Lib:site-packages
Python:Lib:site-packages
Mac OS (non-pure)
prefix:Lib:site-packages
Python:Lib:site-packages
Notes:
(1)
Most Linux distributions include Python as a standard part of
the system, so prefix and exec-prefix are usually
both /usr on Linux. If you build Python yourself on Linux (or
any Unix-like system), the default prefix and
exec-prefix are /usr/local.
(2)
The default installation directory on Windows was
C:\Program Files\Python under
Python 1.6a1, 1.5.2, and earlier.
prefix and exec-prefix stand for the directories
that Python is installed to, and where it finds its libraries at
run-time. They are always the same under Windows and Mac OS, and very
often the same under Unix. You can find out what your Python
installation uses for prefix and exec-prefix by
running Python in interactive mode and typing a few simple commands.
Under Unix, just type python at the shell prompt. Under
Windows, choose Start > Programs > Python
2.1 > Python (command line). Under Mac OS, ** ??? **.
Once the interpreter is started, you type Python code at the
prompt. For example, on my Linux system, I type the three Python
statements shown below, and get the output as shown, to find out my
prefix and exec-prefix:
If you don't want to install modules to the standard location, or if you
don't have permission to write there, then you need to read about
alternate installations in section 4. If you want to
customize your installation directories more heavily, see
section 5 on custom installations.