n | .. highlightlang:: none |
| |
| .. _install-index: |
| |
n | .. highlightlang:: none |
| |
| ***************************** |
n | Installing Python Modules |
n | Installing Python Modules |
| ***************************** |
| |
| :Author: Greg Ward |
n | :Release: |version| |
| :Date: |today| |
| |
n | .. % TODO: |
| .. % Fill in XXX comments |
| .. TODO: Fill in XXX comments |
| |
n | .. % The audience for this document includes people who don't know anything |
n | .. The audience for this document includes people who don't know anything |
| .. % about Python and aren't about to learn the language just in order to |
| about Python and aren't about to learn the language just in order to |
| .. % install and maintain it for their users, i.e. system administrators. |
| install and maintain it for their users, i.e. system administrators. |
| .. % Thus, I have to be sure to explain the basics at some point: |
| Thus, I have to be sure to explain the basics at some point: |
| .. % sys.path and PYTHONPATH at least. Should probably give pointers to |
| sys.path and PYTHONPATH at least. Should probably give pointers to |
| .. % other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. |
| other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. |
| .. % |
| |
| .. % Finally, it might be useful to include all the material from my "Care |
| Finally, it might be useful to include all the material from my "Care |
| .. % and Feeding of a Python Installation" talk in here somewhere. Yow! |
| and Feeding of a Python Installation" talk in here somewhere. Yow! |
| |
| XXX: input{boilerplate} :XXX |
| |
| .. topic:: Abstract |
| |
| This document describes the Python Distribution Utilities ("Distutils") from the |
| end-user's point-of-view, describing how to extend the capabilities of a |
| standard Python installation by building and installing third-party Python |
| modules and extensions. |
| |
n | .. % \begin{abstract} |
| .. % \noindent |
| .. % Abstract this! |
| .. % \end{abstract} |
| |
n | .. % The ugly "%begin{latexonly}" pseudo-environment suppresses the table |
| .. % of contents for HTML generation. |
| .. % |
| .. % begin{latexonly} |
| .. % end{latexonly} |
| |
| |
| .. _intro: |
| .. _inst-intro: |
| |
| Introduction |
| ============ |
| |
| Although Python's extensive standard library covers many programming needs, |
| there often comes a time when you need to add some new functionality to your |
| Python installation in the form of third-party modules. This might be necessary |
| to support your own programming, or to support an application that you want to |
| |
| This document is aimed primarily at the people who need to install third-party |
| Python modules: end-users and system administrators who just need to get some |
| Python application running, and existing Python programmers who want to add some |
| new goodies to their toolbox. You don't need to know Python to read this |
| document; there will be some brief forays into using Python's interactive mode |
| to explore your installation, but that's it. If you're looking for information |
| on how to distribute your own Python modules so that others may use them, see |
n | the Distributing Python Modules (XXX reference: ../dist/dist.html) manual. |
n | the :ref:`distutils-index` manual. |
| |
| |
n | .. _trivial-install: |
n | .. _inst-trivial-install: |
| |
| Best case: trivial installation |
| ------------------------------- |
| |
| In the best case, someone will have prepared a special version of the module |
| distribution you want to install that is targeted specifically at your platform |
| and is installed just like any other software on your platform. For example, |
| the module developer might make an executable installer available for Windows |
| |
| If all these things are true, then you already know how to build and install the |
| modules you've just downloaded: Run the command above. Unless you need to |
| install things in a non-standard way or customize the build process, you don't |
| really need this manual. Or rather, the above command is everything you need to |
| get out of this manual. |
| |
| |
n | .. _standard-install: |
n | .. _inst-standard-install: |
| |
| Standard Build and Install |
| ========================== |
| |
n | As described in section :ref:`new-standard`, building and installing a module |
n | As described in section :ref:`inst-new-standard`, 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 :command:`Terminal` window to get a shell prompt. |
| |
| |
n | .. _platform-variations: |
n | .. _inst-platform-variations: |
| |
| 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 |
| :file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do 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. |
| |
| |
n | .. _how-build-works: |
n | .. _inst-how-build-works: |
| |
| How building works |
| ------------------ |
| |
| As implied above, the :command:`build` command is responsible for putting the |
| files to install into a *build directory*. By default, this is :file:`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 |
| :option:`--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 |
n | Distutils configuration file; see section :ref:`config-files`.) Normally, this |
n | Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this |
| isn't necessary. |
| |
| The default layout for the build tree is as follows:: |
| |
| --- build/ --- lib/ |
| or |
| --- build/ --- lib.<plat>/ |
| temp.<plat>/ |
| |
| If you don't choose an installation directory---i.e., if you just run ``setup.py |
| install``\ ---then the :command:`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"): |
| |
n | +-----------------+------------------------------------+--------------------------------------+-------+ |
n | +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ |
| | Platform | Standard installation | Default value | Notes | |
| | Platform | Standard installation location | Default value | Notes | |
| | | location | | | |
| +=================+====================================+======================================+=======+ |
| +=================+=====================================================+==================================================+=======+ |
| | Unix (pure) | :file:`{prefix}/lib/python|version | :file:`/usr/local/lib/python|version | \(1) | |
| | Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | |
| | | |/site-packages` | |/site-packages` | | |
| +-----------------+------------------------------------+--------------------------------------+-------+ |
| +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ |
| | Unix (non-pure) | :file:`{exec- | :file:`/usr/local/lib/python|version | \(1) | |
| | Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | |
| | | prefix}/lib/python|version | |/site-packages` | | |
| | | |/site-packages` | | | |
| +-----------------+------------------------------------+--------------------------------------+-------+ |
| +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ |
| | Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | |
| | Windows | :file:`{prefix}` | :file:`C:\\Python` | \(2) | |
| +-----------------+------------------------------------+--------------------------------------+-------+ |
| +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ |
| |
| Notes: |
| |
| (1) |
| Most Linux distributions include Python as a standard part of the system, so |
| :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on |
| Linux. If you build Python yourself on Linux (or any Unix-like system), the |
| default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`. |
| |
| (2) |
| The default installation directory on Windows was :file:`C:\\Program |
| Files\\Python` under Python 1.6a1, 1.5.2, and earlier. |
| |
| :file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python |
| is installed to, and where it finds its libraries at run-time. They are always |
n | the same under Windows, and very often the same under Unixand Mac OS X. You can |
n | the same under Windows, and very often the same under Unix and Mac OS X. You |
| find out what your Python installation uses for :file:`{prefix}` and |
| can find out what your Python installation uses for :file:`{prefix}` and |
| :file:`{exec-prefix}` by running Python in interactive mode and typing a few |
| simple commands. Under Unix, just type ``python`` at the shell prompt. Under |
n | Windows, choose :menuselection:`Start --> Programs --> Python |version|--> |
n | Windows, choose :menuselection:`Start --> Programs --> Python X.Y --> |
| 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 |
| :file:`{prefix}` and :file:`{exec-prefix}`:: |
| |
n | Python 2.4 (#26, Aug 7 2004, 17:19:02) |
n | 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 |
n | installations in section :ref:`alt-install`. If you want to customize your |
n | installations in section :ref:`inst-alt-install`. If you want to customize your |
| installation directories more heavily, see section :ref:`custom-install` on |
| installation directories more heavily, see section :ref:`inst-custom-install` on |
| custom installations. |
| |
| |
n | .. _alt-install: |
n | .. _inst-alt-install: |
| |
| Alternate Installation |
| ====================== |
| |
| Often, it is necessary or desirable to install modules to a location other than |
| the standard location for third-party Python modules. For example, on a Unix |
| system you might not have permission to write to the standard third-party module |
| directory. Or you might wish to try out a module before making it a standard |
| Unix, lazy typists can just type a tilde (``~``); the :command:`install` command |
| will expand this to your home directory:: |
| |
| python setup.py install --home=~ |
| |
| The :option:`--home` option defines the installation base directory. Files are |
| installed to the following directories under the installation base as follows: |
| |
n | +------------------------------+-----------------------------------+-----------------------------+ |
n | +------------------------------+---------------------------+-----------------------------+ |
| | Type of file | Installation Directory | Override option | |
| | Type of file | Installation Directory | Override option | |
| +==============================+===================================+=============================+ |
| +==============================+===========================+=============================+ |
| | pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-purelib` | |
| | pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | |
| +------------------------------+-----------------------------------+-----------------------------+ |
| +------------------------------+---------------------------+-----------------------------+ |
| | non-pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-platlib` | |
| | non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | |
| +------------------------------+-----------------------------------+-----------------------------+ |
| +------------------------------+---------------------------+-----------------------------+ |
| | scripts | :file:`{home}`:file:`/bin` | :option:`--install-scripts` | |
| | scripts | :file:`{home}/bin` | :option:`--install-scripts` | |
| +------------------------------+-----------------------------------+-----------------------------+ |
| +------------------------------+---------------------------+-----------------------------+ |
| | data | :file:`{home}`:file:`/share` | :option:`--install-data` | |
| | data | :file:`{home}/share` | :option:`--install-data` | |
| +------------------------------+-----------------------------------+-----------------------------+ |
| +------------------------------+---------------------------+-----------------------------+ |
| |
| .. versionchanged:: 2.4 |
| The :option:`--home` option used to be supported only on Unix. |
| |
| |
n | .. _alt-install-home: |
n | .. _inst-alt-install-home: |
| |
| Alternate installation: Unix (the prefix scheme) |
| ------------------------------------------------ |
| |
| The "prefix scheme" is useful when you wish to use one Python installation to |
| perform the build/install (i.e., to run the setup script), but install modules |
| into the third-party module directory of a different Python installation (or |
| something that looks like a different Python installation). If this sounds a |
| |
| In either case, the :option:`--prefix` option defines the installation base, and |
| the :option:`--exec-prefix` option defines the platform-specific installation |
| base, which is used for platform-specific files. (Currently, this just means |
| non-pure module distributions, but could be expanded to C libraries, binary |
| executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to |
| :option:`--prefix`. Files are installed as follows: |
| |
n | +------------------------------+----------------------------------------+-----------------------------+ |
n | +------------------------------+-----------------------------------------------------+-----------------------------+ |
| | Type of file | Installation Directory | Override option | |
| | Type of file | Installation Directory | Override option | |
| +==============================+========================================+=============================+ |
| +==============================+=====================================================+=============================+ |
| | pure module distribution | :file:`{prefix}`:file:`/lib/python2.{X | :option:`--install-purelib` | |
| | pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | |
| | | }/site-packages` | | |
| +------------------------------+----------------------------------------+-----------------------------+ |
| +------------------------------+-----------------------------------------------------+-----------------------------+ |
| | non-pure module distribution | :file:`{exec- | :option:`--install-platlib` | |
| | non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | |
| | | prefix}`:file:`/lib/python2.{X | | |
| | | }/site-packages` | | |
| +------------------------------+----------------------------------------+-----------------------------+ |
| +------------------------------+-----------------------------------------------------+-----------------------------+ |
| | scripts | :file:`{prefix}`:file:`/bin` | :option:`--install-scripts` | |
| | scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | |
| +------------------------------+----------------------------------------+-----------------------------+ |
| +------------------------------+-----------------------------------------------------+-----------------------------+ |
| | data | :file:`{prefix}`:file:`/share` | :option:`--install-data` | |
| | data | :file:`{prefix}/share` | :option:`--install-data` | |
| +------------------------------+----------------------------------------+-----------------------------+ |
| +------------------------------+-----------------------------------------------------+-----------------------------+ |
| |
| There is no requirement that :option:`--prefix` or :option:`--exec-prefix` |
| actually point to an alternate Python installation; if the directories listed |
| above do not already exist, they are created at installation time. |
| |
| Incidentally, the real reason the prefix scheme is important is simply that a |
| standard Unix installation uses the prefix scheme, but with :option:`--prefix` |
| and :option:`--exec-prefix` supplied by Python itself as ``sys.prefix`` and |
| python setup.py install --prefix="\Temp\Python" |
| |
| to install modules to the :file:`\\Temp\\Python` directory on the current drive. |
| |
| The installation base is defined by the :option:`--prefix` option; the |
| :option:`--exec-prefix` option is not supported under Windows. Files are |
| installed as follows: |
| |
n | +------------------------------+-----------------------------------+-----------------------------+ |
n | +------------------------------+---------------------------+-----------------------------+ |
| | Type of file | Installation Directory | Override option | |
| | Type of file | Installation Directory | Override option | |
| +==============================+===================================+=============================+ |
| +==============================+===========================+=============================+ |
| | pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-purelib` | |
| | pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | |
| +------------------------------+-----------------------------------+-----------------------------+ |
| +------------------------------+---------------------------+-----------------------------+ |
| | non-pure module distribution | :file:`{prefix}`:file:`` | :option:`--install-platlib` | |
| | non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | |
| +------------------------------+-----------------------------------+-----------------------------+ |
| +------------------------------+---------------------------+-----------------------------+ |
| | scripts | :file:`{prefix}`:file:`\\Scripts` | :option:`--install-scripts` | |
| | scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | |
| +------------------------------+-----------------------------------+-----------------------------+ |
| +------------------------------+---------------------------+-----------------------------+ |
| | data | :file:`{prefix}`:file:`\\Data` | :option:`--install-data` | |
| | data | :file:`{prefix}\\Data` | :option:`--install-data` | |
| +------------------------------+-----------------------------------+-----------------------------+ |
| +------------------------------+---------------------------+-----------------------------+ |
| |
| |
n | .. _custom-install: |
n | .. _inst-custom-install: |
| |
| Custom Installation |
| =================== |
| |
| Sometimes, the alternate installation schemes described in section |
n | :ref:`alt-install` just don't do what you want. You might want to tweak just |
n | :ref:`inst-alt-install` 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. |
| 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 :file:`{prefix}`. Of |
| course, you also have to ensure that these directories are in Python's module |
| search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See |
n | section :ref:`search-path` to find out how to modify Python's search path. |
n | section :ref:`inst-search-path` to find out how to modify Python's search path. |
| |
| 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 |
n | supply relative paths; for example, if you want to maintain all Python module- |
n | supply relative paths; for example, if you want to maintain all Python |
| related files under :file:`python` in your home directory, and you want a |
| module-related files under :file:`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 |
| |
n | or, equivalently, |
n | or, equivalently, :: |
| |
| .. % $ % -- bow to font-lock |
| |
| :: |
| |
| 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). |
| |
n | .. % $ % -- bow to font-lock |
| |
| Obviously, specifying the entire installation scheme every time you install a |
| new module distribution would be very tedious. Thus, you can put these options |
n | into your Distutils config file (see section :ref:`config-files`):: |
n | into your Distutils config file (see section :ref:`inst-config-files`):: |
| |
| [install] |
| install-base=$HOME |
| install-purelib=python/lib |
| install-platlib=python/lib.$PLAT |
| install-scripts=python/scripts |
| install-data=python/data |
| |
| 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, :: |
| |
n | python setup.py --install-base=/tmp |
n | python setup.py install --install-base=/tmp |
| |
| would install pure modules to :file:`{/tmp/python/lib}` in the first case, and |
| to :file:`{/tmp/lib}` in the second case. (For the second case, you probably |
| want to supply an installation base of :file:`/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, on systems that don't have |
| environment variables, such as Mac OS 9, the configuration variables supplied by |
n | the Distutils are the only ones you can use.) See section :ref:`config-files` |
n | the Distutils are the only ones you can use.) See section :ref:`inst-config-files` |
| for details. |
| |
n | .. % XXX need some Windows examples---when would custom |
n | .. XXX need some Windows examples---when would custom installation schemes be |
| .. % installation schemes be needed on those platforms? |
| needed on those platforms? |
| |
n | |
| .. % XXX I'm not sure where this section should go. |
| .. XXX I'm not sure where this section should go. |
| |
n | |
| .. _search-path: |
| .. _inst-search-path: |
| |
| Modifying Python's Search Path |
| ------------------------------ |
| |
| When the Python interpreter executes an :keyword:`import` statement, it searches |
| for both Python code and extension modules along a search path. A default value |
| for the path is configured into the Python binary when the interpreter is built. |
| You can determine the path by importing the :mod:`sys` module and printing the |
| value of ``sys.path``. :: |
| |
| $ python |
| Python 2.2 (#11, Oct 3 2002, 13:31:27) |
| [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2 |
n | Type ``help'', ``copyright'', ``credits'' or ``license'' for more information. |
n | Type "help", "copyright", "credits" or "license" for more information. |
| >>> import sys |
| >>> sys.path |
n | ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2', |
n | ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2', |
| '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload', |
| '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload', |
| '/usr/local/lib/python2.3/site-packages'] |
| >>> |
| |
| The null string in ``sys.path`` represents the current working directory. |
| |
n | .. % $ <-- bow to font-lock |
| |
| The expected convention for locally installed packages is to put them in the |
n | :file:`.../site-packages/` directory, but you may want to install Python modules |
n | :file:`{...}/site-packages/` directory, but you may want to install Python |
| into some arbitrary directory. For example, your site may have a convention of |
| modules into some arbitrary directory. For example, your site may have a |
| keeping all software related to the web server under :file:`/www`. Add-on |
| convention of keeping all software related to the web server under :file:`/www`. |
| Python modules might then belong in :file:`/www/python`, and in order to import |
| Add-on Python modules might then belong in :file:`/www/python`, and in order to |
| them, this directory must be added to ``sys.path``. There are several different |
| import them, this directory must be added to ``sys.path``. There are several |
| ways to add the directory. |
| different ways to add the directory. |
| |
| The most convenient way is to add a path configuration file to a directory |
| that's already on Python's path, usually to the :file:`.../site-packages/` |
| directory. Path configuration files have an extension of :file:`.pth`, and each |
| line must contain a single path that will be appended to ``sys.path``. (Because |
| the new paths are appended to ``sys.path``, modules in the added directories |
| will not override standard modules. This means you can't use this mechanism for |
| installing fixed versions of standard modules.) |
| |
| Paths can be absolute or relative, in which case they're relative to the |
n | directory containing the :file:`.pth` file. Any directories added to the search |
n | directory containing the :file:`.pth` file. See the documentation of |
| path will be scanned in turn for :file:`.pth` files. See `site module |
| the :mod:`site` module for more information. |
| documentation <http://www.python.org/dev/doc/devel/lib/module-site.html>`_ for |
| more information. |
| |
| A slightly less convenient way is to edit the :file:`site.py` file in Python's |
| standard library, and modify ``sys.path``. :file:`site.py` is automatically |
| imported when the Python interpreter is executed, unless the :option:`-S` switch |
| is supplied to suppress this behaviour. So you could simply edit |
| :file:`site.py` and add two lines to it:: |
| |
| import sys |
| However, if you reinstall the same major version of Python (perhaps when |
| upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by |
| the stock version. You'd have to remember that it was modified and save a copy |
| before doing the installation. |
| |
| There are two environment variables that can modify ``sys.path``. |
| :envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python |
| installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``, |
n | the search path will be set to ``['', '/www/python/lib/python|version|/', |
n | the search path will be set to ``['', '/www/python/lib/pythonX.Y/', |
| '/www/python/lib/python|version|/plat-linux2', ...]``. |
| '/www/python/lib/pythonX.Y/plat-linux2', ...]``. |
| |
| The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be |
| added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is |
| set to ``/www/python:/opt/py``, the search path will begin with |
| ``['/www/python', '/opt/py']``. (Note that directories must exist in order to |
| be added to ``sys.path``; the :mod:`site` module removes paths that don't |
| exist.) |
| |
| Finally, ``sys.path`` is just a regular Python list, so any Python application |
| can modify it by adding or removing entries. |
| |
| |
n | .. _config-files: |
n | .. _inst-config-files: |
| |
| Distutils Configuration Files |
| ============================= |
| |
| As mentioned above, you can use Distutils configuration files to record personal |
| or site preferences for any Distutils options. That is, any option to any |
| command can be stored in one of two or three (depending on your platform) |
| configuration files, which will be consulted before the command-line is parsed. |
| This means that configuration files will override default values, and the |
| command-line will in turn override configuration files. Furthermore, if |
| multiple configuration files apply, values from "earlier" files are overridden |
| by "later" files. |
| |
| |
n | .. _config-filenames: |
n | .. _inst-config-filenames: |
| |
| Location and names of config files |
| ---------------------------------- |
| |
| The names and locations of the configuration files vary slightly across |
| platforms. On Unix and Mac OS X, the three configuration files (in the order |
| they are processed) are: |
| |
| and you can find out the complete list of global options by using |
| :option:`--help` without a command:: |
| |
| python setup.py --help |
| |
| See also the "Reference" section of the "Distributing Python Modules" manual. |
| |
| |
n | .. _building-ext: |
n | .. _inst-building-ext: |
| |
| Building Extensions: Tips and Tricks |
| ==================================== |
| |
| Whenever possible, the Distutils try to use the configuration information made |
| available by the Python interpreter used to run the :file:`setup.py` script. |
| For example, the same compiler and linker flags used to compile Python will also |
| be used for compiling extensions. Usually this will work well, but in |
| complicated situations this might be inappropriate. This section discusses how |
| to override the usual Distutils behaviour. |
| |
| |
n | .. _tweak-flags: |
n | .. _inst-tweak-flags: |
| |
| Tweaking compiler/linker flags |
| ------------------------------ |
| |
| Compiling a Python extension written in C or C++ will sometimes require |
| specifying custom flags for the compiler and linker in order to use a particular |
| library or produce a special kind of object code. This is especially true if the |
n | extension hasn't been tested on your platform, or if you're trying to cross- |
n | extension hasn't been tested on your platform, or if you're trying to |
| compile Python. |
| cross-compile Python. |
| |
| In the most general case, the extension author might have foreseen that |
| compiling the extensions would be complicated, and provided a :file:`Setup` file |
| for you to edit. This will likely only be done if the module distribution |
| contains many separate extension modules, or if they often require elaborate |
| sets of compiler flags in order to work. |
| |
| A :file:`Setup` file, if present, is parsed in order to get a list of extensions |
| supply multiple :option:`-Xcompiler` options; for example, to pass ``-x c++`` |
| the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``. |
| |
| Compiler flags can also be supplied through setting the :envvar:`CFLAGS` |
| environment variable. If set, the contents of :envvar:`CFLAGS` will be added to |
| the compiler flags specified in the :file:`Setup` file. |
| |
| |
n | .. _non-ms-compilers: |
n | .. _inst-non-ms-compilers: |
| |
| Using non-Microsoft compilers on Windows |
| ---------------------------------------- |
| |
| .. sectionauthor:: Rene Liebscher <R.Liebscher@gmx.de> |
| |
| |
| |
n | Borland C++ |
n | Borland/CodeGear C++ |
| ^^^^^^^^^^^ |
| ^^^^^^^^^^^^^^^^^^^^ |
| |
n | This subsection describes the necessary steps to use Distutils with the Borland |
n | This subsection describes the necessary steps to use Distutils with the Borland |
| C++ compiler version 5.5. First you have to know that Borland's object file |
| format (OMF) is different from the format used by the Python version you can |
| download from the Python or ActiveState Web site. (Python is built with |
| Microsoft Visual C++, which uses COFF as the object file format.) For this |
| reason you have to convert Python's library :file:`python25.lib` into the |
| Borland format. You can do this as follows: |
| |
n | .. % Should we mention that users have to create cfg-files for the compiler? |
n | .. Should we mention that users have to create cfg-files for the compiler? |
| .. % see also http://community.borland.com/article/0,1410,21205,00.html |
| .. see also http://community.borland.com/article/0,1410,21205,00.html |
| |
| :: |
| |
| coff2omf python25.lib python25_bcpp.lib |
| |
| The :file:`coff2omf` program comes with the Borland compiler. The file |
| :file:`python25.lib` is in the :file:`Libs` directory of your Python |
n | installation. If your extension uses other libraries (zlib,...) you have to |
n | installation. If your extension uses other libraries (zlib, ...) you have to |
| convert them too. |
| |
| The converted files have to reside in the same directories as the normal |
| libraries. |
| |
| How does Distutils manage to use these libraries with their changed names? If |
| the extension needs a library (eg. :file:`foo`) Distutils checks first if it |
| finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then |
| This section describes the necessary steps to use Distutils with the GNU C/C++ |
| compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter |
| that was built with Cygwin, everything should work without any of these |
| following steps. |
| |
| These compilers require some special libraries. This task is more complex than |
| for Borland's C++, because there is no program to convert the library. First |
| you have to create a list of symbols which the Python DLL exports. (You can find |
n | a good program for this task at |
n | a good program for this task at http://www.emmestech.com/software/cygwin/pexports-0.43/download_pexports.html) |
| `<http://starship.python.net/crew/kernr/mingw32/Notes.html>`_, see at PExports |
| 0.42h there.) |
| |
n | .. % I don't understand what the next line means. --amk |
n | .. I don't understand what the next line means. --amk |
| .. % (inclusive the references on data structures.) |
| .. (inclusive the references on data structures.) |
| |
| :: |
| |
| pexports python25.dll >python25.def |
| |
| The location of an installed :file:`python25.dll` will depend on the |
| installation options and the version and language of Windows. In a "just for |
| me" installation, it will appear in the root of the installation directory. In |