Subsections

- 2.1 Platform variations
- 2.2 Splitting the job up
- 2.3 How building works
- 2.4 How installation works

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

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

      Python 1.5.2 (#1, Apr 18 1999, 16:03:16)  [GCC pgcc-2.91.60 19981201 (egcs-1.1.1  on linux2
      Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
      >>> 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 4. If you want to customize your installation directories more heavily, see section 5 on custom installations.