5 Custom Installation

Sometimes, the alternate installation schemes described in section 4 just don't do what you want. You might want to tweak just one or two directories while keeping everything under the same base directory, or you might want to completely redefine the installation scheme. In either case, you're creating a custom installation scheme.

You probably noticed the column of ``override options'' in the tables describing the alternate installation schemes above. Those options are how you define a custom installation scheme. These override options can be relative, absolute, or explicitly defined in terms of one of the installation base directories. (There are two installation base directories, and they are normally the same--they only differ when you use the Unix ``prefix scheme'' and supply different --prefix and --exec-prefix options.)

For example, say you're installing a module distribution to your home directory under Unix--but you want scripts to go in ~/scripts rather than ~/bin. As you might expect, you can override this directory with the --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):

python setup.py install --home=~ --install-scripts=scripts

Another Unix example: suppose your Python installation was built and installed with a prefix of /usr/local/python, so under a standard installation scripts will wind up in /usr/local/python/bin. If you want them in /usr/local/bin instead, you would supply this absolute directory for the --install-scripts option:

python setup.py install --install-scripts=/usr/local/bin

(This performs an installation using the ``prefix scheme,'' where the prefix is whatever your Python interpreter was installed with-- /usr/local/python in this case.)

If you maintain Python on Windows, you might want third-party modules to live in a subdirectory of prefix, rather than right in prefix itself. This is almost as easy as customizing the 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:

python setup.py install --install-purelib=Site --install-platlib=Site

The specified installation directories are relative to prefix. Of course, you also have to ensure that these directories are in Python's module search path, e.g. by putting a .pth file in prefix (** should have a section describing .pth files and cross-ref it here **).

If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way to do this is to supply relative paths; for example, if you want to maintain all Python module-related files under python in your 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:

python setup.py install --home=~ \
                        --install-purelib=python/lib \
                        --install-platlib=python/lib.$PLAT \
                        --install-scripts=python/scripts
                        --install-data=python/data

or, equivalently,

python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data

$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)).

Obviously, specifying the entire installation scheme every time you install a new module distribution would be very tedious. Thus, you can put these options into your Distutils config file (see section 6):

[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data

or, equivalently,

[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data

Note that these two are not equivalent if you supply a different installation base directory when you run the setup script. For example,

python setup.py --install-base=/tmp

would install pure modules to /tmp/python/lib in the first case, and to /tmp/lib in the second case. (For the second case, you probably want to supply an installation base of /tmp/python.)

You probably noticed the use of $HOME and $PLAT in the sample configuration file input. These are Distutils configuration variables, which bear a strong resemblance to environment variables. In fact, you can use environment variables in config files--on platforms that have such a notion--but the Distutils additionally define a few extra variables that may not be in your environment, such as $PLAT. (And of course, you can only use the configuration variables supplied by the Distutils on systems that don't have environment variables, such as Mac OS (** true? **).) See section 6 for details.

** need some Windows and Mac OS examples--when would custom installation schemes be needed on those platforms? **

See About this document... for information on suggesting changes.