2 Standard Build and Install

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.

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 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

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--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 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:

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.

--- 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 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
Unix (pure)	prefix/lib/python2.5/site-packages	/usr/local/lib/python2.5/site-packages	(1)
Unix (non-pure)	exec-prefix/lib/python2.5/site-packages	/usr/local/lib/python2.5/site-packages	(1)
Windows	prefix	C:\Python	(2)

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.