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 X, you open a
Terminal window to get a shell prompt.
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 graphical 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
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--for example, 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
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.
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.
python setup.py build --build-base=/tmp/pybuild/foo-1.0
(Or you could do this permanently with a directive in your system or personal Distutils configuration file; see section 5.) Normally, this isn't necessary.
The default layout for the build tree is as follows:
--- build/ --- lib/ or --- build/ --- lib.<plat>/ temp.<plat>/
<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.
build command runs (whether you run it explicitly,
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 X, which is also Unix-based),
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|
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 very
often the same under Unix and Mac OS X. 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.5 > Python (command line).
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:
Python 2.4 (#26, Aug 7 2004, 17:19:02) Type "help", "copyright", "credits" or "license" for more information. >>> import sys >>> sys.prefix '/usr' >>> sys.exec_prefix '/usr'
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 3. If you want to customize your installation directories more heavily, see section 4 on custom installations.
See About this document... for information on suggesting changes.