rest25/install/index.rst => rest262/install/index.rst
n1+.. highlightlang:: none
2+ 
1.. _install-index:
2
n3-.. highlightlang:: none
4- 
5*****************************
n6-  Installing Python Modules  
n6+  Installing Python Modules
7*****************************
8
9:Author: Greg Ward
n10+:Release: |version|
11+:Date: |today|
10
n11-.. % TODO:
12-.. % Fill in XXX comments
13+.. TODO: Fill in XXX comments
13
n14-.. % The audience for this document includes people who don't know anything
n15+.. The audience for this document includes people who don't know anything
15-.. % about Python and aren't about to learn the language just in order to
16+   about Python and aren't about to learn the language just in order to
16-.. % install and maintain it for their users, i.e. system administrators.
17+   install and maintain it for their users, i.e. system administrators.
17-.. % Thus, I have to be sure to explain the basics at some point:
18+   Thus, I have to be sure to explain the basics at some point:
18-.. % sys.path and PYTHONPATH at least.  Should probably give pointers to
19+   sys.path and PYTHONPATH at least.  Should probably give pointers to
19-.. % other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
20+   other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
20-.. % 
21+ 
21-.. % Finally, it might be useful to include all the material from my "Care
22+   Finally, it might be useful to include all the material from my "Care
22-.. % and Feeding of a Python Installation" talk in here somewhere.  Yow!
23+   and Feeding of a Python Installation" talk in here somewhere.  Yow!
23- 
24-XXX: input{boilerplate} :XXX
25
26.. topic:: Abstract
27
28   This document describes the Python Distribution Utilities ("Distutils") from the
29   end-user's point-of-view, describing how to extend the capabilities of a
30   standard Python installation by building and installing third-party Python
31   modules and extensions.
32
n33-.. % \begin{abstract}
34-.. % \noindent
35-.. % Abstract this!
36-.. % \end{abstract}
37
n38-.. % The ugly "%begin{latexonly}" pseudo-environment suppresses the table
39-.. % of contents for HTML generation.
40-.. % 
41-.. % begin{latexonly}
42-.. % end{latexonly}
43- 
44- 
45-.. _intro:
33+.. _inst-intro:
46
47Introduction
48============
49
50Although Python's extensive standard library covers many programming needs,
51there often comes a time when you need to add some new functionality to your
52Python installation in the form of third-party modules.  This might be necessary
53to support your own programming, or to support an application that you want to
59
60This document is aimed primarily at the people who need to install third-party
61Python modules: end-users and system administrators who just need to get some
62Python application running, and existing Python programmers who want to add some
63new goodies to their toolbox.  You don't need to know Python to read this
64document; there will be some brief forays into using Python's interactive mode
65to explore your installation, but that's it.  If you're looking for information
66on how to distribute your own Python modules so that others may use them, see
n67-the Distributing Python Modules (XXX reference: ../dist/dist.html) manual.
n55+the :ref:`distutils-index` manual.
68
69
n70-.. _trivial-install:
n58+.. _inst-trivial-install:
71
72Best case: trivial installation
73-------------------------------
74
75In the best case, someone will have prepared a special version of the module
76distribution you want to install that is targeted specifically at your platform
77and is installed just like any other software on your platform.  For example,
78the module developer might make an executable installer available for Windows
90module distribution that doesn't have an easy-to-use installer for your
91platform.  In that case, you'll have to start with the source distribution
92released by the module's author/maintainer.  Installing from a source
93distribution is not too hard, as long as the modules are packaged in the
94standard way.  The bulk of this document is about building and installing
95modules from standard source distributions.
96
97
n98-.. _new-standard:
n86+.. _inst-new-standard:
99
100The new standard: Distutils
101---------------------------
102
103If you download a module source distribution, you can tell pretty quickly if it
104was packaged and distributed in the standard way, i.e. using the Distutils.
105First, the distribution's name and version number will be featured prominently
106in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or
114
115If all these things are true, then you already know how to build and install the
116modules you've just downloaded:  Run the command above. Unless you need to
117install things in a non-standard way or customize the build process, you don't
118really need this manual.  Or rather, the above command is everything you need to
119get out of this manual.
120
121
n122-.. _standard-install:
n110+.. _inst-standard-install:
123
124Standard Build and Install
125==========================
126
n127-As described in section :ref:`new-standard`, building and installing a module
n115+As described in section :ref:`inst-new-standard`, building and installing a module
128distribution using the Distutils is usually one simple command::
129
130   python setup.py install
131
132On Unix, you'd run this command from a shell prompt; on Windows, you have to
133open a command prompt window ("DOS box") and do it there; on Mac OS X, you open
134a :command:`Terminal` window to get a shell prompt.
135
136
n137-.. _platform-variations:
n125+.. _inst-platform-variations:
138
139Platform variations
140-------------------
141
142You should always run the setup command from the distribution root directory,
143i.e. the top-level subdirectory that the module source distribution unpacks
144into.  For example, if you've just downloaded a module source distribution
145:file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is::
154graphical user interface (such as WinZip) or a command-line tool (such as
155:program:`unzip` or :program:`pkunzip`) to unpack the archive.  Then, open a
156command prompt window ("DOS box"), and run::
157
158   cd c:\Temp\foo-1.0
159   python setup.py install
160
161
n162-.. _splitting-up:
n150+.. _inst-splitting-up:
163
164Splitting the job up
165--------------------
166
167Running ``setup.py install`` builds and installs all modules in one run.  If you
168prefer to work incrementally---especially useful if you want to customize the
169build process, or if things are going wrong---you can use the setup script to do
170one thing at a time.  This is particularly helpful when the build and install
184up-to-date.
185
186You may not need this ability to break things down often if all you do is
187install modules downloaded off the 'net, but it's very handy for more advanced
188tasks.  If you get into distributing your own Python modules and extensions,
189you'll run lots of individual Distutils commands on their own.
190
191
n192-.. _how-build-works:
n180+.. _inst-how-build-works:
193
194How building works
195------------------
196
197As implied above, the :command:`build` command is responsible for putting the
198files to install into a *build directory*.  By default, this is :file:`build`
199under the distribution root; if you're excessively concerned with speed, or want
200to keep the source tree pristine, you can change the build directory with the
201:option:`--build-base` option. For example::
202
203   python setup.py build --build-base=/tmp/pybuild/foo-1.0
204
205(Or you could do this permanently with a directive in your system or personal
n206-Distutils configuration file; see section :ref:`config-files`.)  Normally, this
n194+Distutils configuration file; see section :ref:`inst-config-files`.)  Normally, this
207isn't necessary.
208
209The default layout for the build tree is as follows::
210
211   --- build/ --- lib/
212   or
213   --- build/ --- lib.<plat>/
214                  temp.<plat>/
223installed.  In either case, the :file:`lib` (or :file:`lib.{plat}`) directory
224contains all Python modules (pure Python and extensions) that will be installed.
225
226In the future, more directories will be added to handle Python scripts,
227documentation, binary executables, and whatever else is needed to handle the job
228of installing Python modules and applications.
229
230
n231-.. _how-install-works:
n219+.. _inst-how-install-works:
232
233How installation works
234----------------------
235
236After the :command:`build` command runs (whether you run it explicitly, or the
237:command:`install` command does it for you), the work of the :command:`install`
238command is relatively simple: all it has to do is copy everything under
239:file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation
241
242If you don't choose an installation directory---i.e., if you just run ``setup.py
243install``\ ---then the :command:`install` command installs to the standard
244location for third-party Python modules.  This location varies by platform and
245by how you built/installed Python itself.  On Unix (and Mac OS X, which is also
246Unix-based), it also depends on whether the module distribution being installed
247is pure Python or contains extensions ("non-pure"):
248
n249-+-----------------+------------------------------------+--------------------------------------+-------+
n237++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
250-| Platform        | Standard installation              | Default value                        | Notes |
238+| Platform        | Standard installation location                      | Default value                                    | Notes |
251-|                 | location                           |                                      |       |
252-+=================+====================================+======================================+=======+
239++=================+=====================================================+==================================================+=======+
253-| Unix (pure)     | :file:`{prefix}/lib/python|version | :file:`/usr/local/lib/python|version | \(1)  |
240+| Unix (pure)     | :file:`{prefix}/lib/python{X.Y}/site-packages`      | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1)  |
254-|                 | |/site-packages`                   | |/site-packages`                     |       |
255-+-----------------+------------------------------------+--------------------------------------+-------+
241++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
256-| Unix (non-pure) | :file:`{exec-                      | :file:`/usr/local/lib/python|version | \(1)  |
242+| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1)  |
257-|                 | prefix}/lib/python|version         | |/site-packages`                     |       |
258-|                 | |/site-packages`                   |                                      |       |
259-+-----------------+------------------------------------+--------------------------------------+-------+
243++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
260-| Windows         | :file:`{prefix}`                   | :file:`C:\\Python`                   | \(2)  |
244+| Windows         | :file:`{prefix}`                                    | :file:`C:\\Python`                               | \(2)  |
261-+-----------------+------------------------------------+--------------------------------------+-------+
245++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
262
263Notes:
264
265(1)
266   Most Linux distributions include Python as a standard part of the system, so
267   :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on
268   Linux.  If you build Python yourself on Linux (or any Unix-like system), the
269   default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`.
270
271(2)
272   The default installation directory on Windows was :file:`C:\\Program
273   Files\\Python` under Python 1.6a1, 1.5.2, and earlier.
274
275:file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python
276is installed to, and where it finds its libraries at run-time.  They are always
n277-the same under Windows, and very often the same under Unixand Mac OS X.  You can
n261+the same under Windows, and very often the same under Unix and Mac OS X.  You
278-find out what your Python installation uses for :file:`{prefix}` and
262+can find out what your Python installation uses for :file:`{prefix}` and
279:file:`{exec-prefix}` by running Python in interactive mode and typing a few
280simple commands. Under Unix, just type ``python`` at the shell prompt.  Under
n281-Windows, choose :menuselection:`Start --> Programs --> Python |version|-->
n265+Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
282Python (command line)`.   Once the interpreter is started, you type Python code
283at the prompt.  For example, on my Linux system, I type the three Python
284statements shown below, and get the output as shown, to find out my
285:file:`{prefix}` and :file:`{exec-prefix}`::
286
n287-   Python 2.4 (#26, Aug  7 2004, 17:19:02) 
n271+   Python 2.4 (#26, Aug  7 2004, 17:19:02)
288   Type "help", "copyright", "credits" or "license" for more information.
289   >>> import sys
290   >>> sys.prefix
291   '/usr'
292   >>> sys.exec_prefix
293   '/usr'
294
295If you don't want to install modules to the standard location, or if you don't
296have permission to write there, then you need to read about alternate
n297-installations in section :ref:`alt-install`.  If you want to customize your
n281+installations in section :ref:`inst-alt-install`.  If you want to customize your
298-installation directories more heavily, see section :ref:`custom-install` on
282+installation directories more heavily, see section :ref:`inst-custom-install` on
299custom installations.
300
301
n302-.. _alt-install:
n286+.. _inst-alt-install:
303
304Alternate Installation
305======================
306
307Often, it is necessary or desirable to install modules to a location other than
308the standard location for third-party Python modules.  For example, on a Unix
309system you might not have permission to write to the standard third-party module
310directory.  Or you might wish to try out a module before making it a standard
316distributions to an alternate location simple and painless.  The basic idea is
317that you supply a base directory for the installation, and the
318:command:`install` command picks a set of directories (called an *installation
319scheme*) under this base directory in which to install files.  The details
320differ across platforms, so read whichever of the following sections applies to
321you.
322
323
n324-.. _alt-install-prefix:
n308+.. _inst-alt-install-prefix:
325
326Alternate installation: the home scheme
327---------------------------------------
328
329The idea behind the "home scheme" is that you build and maintain a personal
330stash of Python modules.  This scheme's name is derived from the idea of a
331"home" directory on Unix, since it's not unusual for a Unix user to make their
332home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`.
341Unix, lazy typists can just type a tilde (``~``); the :command:`install` command
342will expand this to your home directory::
343
344   python setup.py install --home=~
345
346The :option:`--home` option defines the installation base directory.  Files are
347installed to the following directories under the installation base as follows:
348
n349-+------------------------------+-----------------------------------+-----------------------------+
n333++------------------------------+---------------------------+-----------------------------+
350-| Type of file                 | Installation Directory            | Override option             |
334+| Type of file                 | Installation Directory    | Override option             |
351-+==============================+===================================+=============================+
335++==============================+===========================+=============================+
352-| pure module distribution     | :file:`{home}`:file:`/lib/python` | :option:`--install-purelib` |
336+| pure module distribution     | :file:`{home}/lib/python` | :option:`--install-purelib` |
353-+------------------------------+-----------------------------------+-----------------------------+
337++------------------------------+---------------------------+-----------------------------+
354-| non-pure module distribution | :file:`{home}`:file:`/lib/python` | :option:`--install-platlib` |
338+| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` |
355-+------------------------------+-----------------------------------+-----------------------------+
339++------------------------------+---------------------------+-----------------------------+
356-| scripts                      | :file:`{home}`:file:`/bin`        | :option:`--install-scripts` |
340+| scripts                      | :file:`{home}/bin`        | :option:`--install-scripts` |
357-+------------------------------+-----------------------------------+-----------------------------+
341++------------------------------+---------------------------+-----------------------------+
358-| data                         | :file:`{home}`:file:`/share`      | :option:`--install-data`    |
342+| data                         | :file:`{home}/share`      | :option:`--install-data`    |
359-+------------------------------+-----------------------------------+-----------------------------+
343++------------------------------+---------------------------+-----------------------------+
360
361.. versionchanged:: 2.4
362   The :option:`--home` option used to be supported only on Unix.
363
364
n365-.. _alt-install-home:
n349+.. _inst-alt-install-home:
366
367Alternate installation: Unix (the prefix scheme)
368------------------------------------------------
369
370The "prefix scheme" is useful when you wish to use one Python installation to
371perform the build/install (i.e., to run the setup script), but install modules
372into the third-party module directory of a different Python installation (or
373something that looks like a different Python installation).  If this sounds a
394
395In either case, the :option:`--prefix` option defines the installation base, and
396the :option:`--exec-prefix` option defines the platform-specific installation
397base, which is used for platform-specific files.  (Currently, this just means
398non-pure module distributions, but could be expanded to C libraries, binary
399executables, etc.)  If :option:`--exec-prefix` is not supplied, it defaults to
400:option:`--prefix`.  Files are installed as follows:
401
n402-+------------------------------+----------------------------------------+-----------------------------+
n386++------------------------------+-----------------------------------------------------+-----------------------------+
403-| Type of file                 | Installation Directory                 | Override option             |
387+| Type of file                 | Installation Directory                              | Override option             |
404-+==============================+========================================+=============================+
388++==============================+=====================================================+=============================+
405-| pure module distribution     | :file:`{prefix}`:file:`/lib/python2.{X | :option:`--install-purelib` |
389+| pure module distribution     | :file:`{prefix}/lib/python{X.Y}/site-packages`      | :option:`--install-purelib` |
406-|                              | }/site-packages`                       |                             |
407-+------------------------------+----------------------------------------+-----------------------------+
390++------------------------------+-----------------------------------------------------+-----------------------------+
408-| non-pure module distribution | :file:`{exec-                          | :option:`--install-platlib` |
391+| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` |
409-|                              | prefix}`:file:`/lib/python2.{X         |                             |
410-|                              | }/site-packages`                       |                             |
411-+------------------------------+----------------------------------------+-----------------------------+
392++------------------------------+-----------------------------------------------------+-----------------------------+
412-| scripts                      | :file:`{prefix}`:file:`/bin`           | :option:`--install-scripts` |
393+| scripts                      | :file:`{prefix}/bin`                                | :option:`--install-scripts` |
413-+------------------------------+----------------------------------------+-----------------------------+
394++------------------------------+-----------------------------------------------------+-----------------------------+
414-| data                         | :file:`{prefix}`:file:`/share`         | :option:`--install-data`    |
395+| data                         | :file:`{prefix}/share`                              | :option:`--install-data`    |
415-+------------------------------+----------------------------------------+-----------------------------+
396++------------------------------+-----------------------------------------------------+-----------------------------+
416
417There is no requirement that :option:`--prefix` or :option:`--exec-prefix`
418actually point to an alternate Python installation; if the directories listed
419above do not already exist, they are created at installation time.
420
421Incidentally, the real reason the prefix scheme is important is simply that a
422standard Unix installation uses the prefix scheme, but with :option:`--prefix`
423and :option:`--exec-prefix` supplied by Python itself as ``sys.prefix`` and
432responsibility to ensure that the interpreter used to run extensions installed
433in this way is compatible with the interpreter used to build them.  The best way
434to do this is to ensure that the two interpreters are the same version of Python
435(possibly different builds, or possibly copies of the same build).  (Of course,
436if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an
437alternate Python installation, this is immaterial.)
438
439
n440-.. _alt-install-windows:
n421+.. _inst-alt-install-windows:
441
442Alternate installation: Windows (the prefix scheme)
443---------------------------------------------------
444
445Windows has no concept of a user's home directory, and since the standard Python
446installation under Windows is simpler than under Unix, the :option:`--prefix`
447option has traditionally been used to install additional packages in separate
448locations on Windows. ::
450   python setup.py install --prefix="\Temp\Python"
451
452to install modules to the :file:`\\Temp\\Python` directory on the current drive.
453
454The installation base is defined by the :option:`--prefix` option; the
455:option:`--exec-prefix` option is not supported under Windows. Files are
456installed as follows:
457
n458-+------------------------------+-----------------------------------+-----------------------------+
n439++------------------------------+---------------------------+-----------------------------+
459-| Type of file                 | Installation Directory            | Override option             |
440+| Type of file                 | Installation Directory    | Override option             |
460-+==============================+===================================+=============================+
441++==============================+===========================+=============================+
461-| pure module distribution     | :file:`{prefix}`:file:``          | :option:`--install-purelib` |
442+| pure module distribution     | :file:`{prefix}`          | :option:`--install-purelib` |
462-+------------------------------+-----------------------------------+-----------------------------+
443++------------------------------+---------------------------+-----------------------------+
463-| non-pure module distribution | :file:`{prefix}`:file:``          | :option:`--install-platlib` |
444+| non-pure module distribution | :file:`{prefix}`          | :option:`--install-platlib` |
464-+------------------------------+-----------------------------------+-----------------------------+
445++------------------------------+---------------------------+-----------------------------+
465-| scripts                      | :file:`{prefix}`:file:`\\Scripts` | :option:`--install-scripts` |
446+| scripts                      | :file:`{prefix}\\Scripts` | :option:`--install-scripts` |
466-+------------------------------+-----------------------------------+-----------------------------+
447++------------------------------+---------------------------+-----------------------------+
467-| data                         | :file:`{prefix}`:file:`\\Data`    | :option:`--install-data`    |
448+| data                         | :file:`{prefix}\\Data`    | :option:`--install-data`    |
468-+------------------------------+-----------------------------------+-----------------------------+
449++------------------------------+---------------------------+-----------------------------+
469
470
n471-.. _custom-install:
n452+.. _inst-custom-install:
472
473Custom Installation
474===================
475
476Sometimes, the alternate installation schemes described in section
n477-:ref:`alt-install` just don't do what you want.  You might want to tweak just
n458+:ref:`inst-alt-install` just don't do what you want.  You might want to tweak just
478one or two directories while keeping everything under the same base directory,
479or you might want to completely redefine the installation scheme.  In either
480case, you're creating a *custom installation scheme*.
481
482You probably noticed the column of "override options" in the tables describing
483the alternate installation schemes above.  Those options are how you define a
484custom installation scheme.  These override options can be relative, absolute,
485or explicitly defined in terms of one of the installation base directories.
515pure modules and non-pure modules (i.e., modules from a non-pure distribution).
516For example::
517
518   python setup.py install --install-purelib=Site --install-platlib=Site
519
520The specified installation directories are relative to :file:`{prefix}`.  Of
521course, you also have to ensure that these directories are in Python's module
522search path, such as by putting a :file:`.pth` file in :file:`{prefix}`.  See
n523-section :ref:`search-path` to find out how to modify Python's search path.
n504+section :ref:`inst-search-path` to find out how to modify Python's search path.
524
525If you want to define an entire installation scheme, you just have to supply all
526of the installation directory options.  The recommended way to do this is to
n527-supply relative paths; for example, if you want to maintain all Python module-
n508+supply relative paths; for example, if you want to maintain all Python
528-related files under :file:`python` in your home directory, and you want a
509+module-related files under :file:`python` in your home directory, and you want a
529separate directory for each platform that you use your home directory from, you
530might define the following installation scheme::
531
532   python setup.py install --home=~ \
533                           --install-purelib=python/lib \
534                           --install-platlib=python/lib.$PLAT \
535                           --install-scripts=python/scripts
536                           --install-data=python/data
537
n538-or, equivalently,
n519+or, equivalently, ::
539- 
540-.. % $ % -- bow to font-lock
541- 
542-::
543
544   python setup.py install --home=~/python \
545                           --install-purelib=lib \
546                           --install-platlib='lib.$PLAT' \
547                           --install-scripts=scripts
548                           --install-data=data
549
550``$PLAT`` is not (necessarily) an environment variable---it will be expanded by
551the Distutils as it parses your command line options, just as it does when
552parsing your configuration file(s).
553
n554-.. % $ % -- bow to font-lock
555- 
556Obviously, specifying the entire installation scheme every time you install a
557new module distribution would be very tedious.  Thus, you can put these options
n558-into your Distutils config file (see section :ref:`config-files`)::
n533+into your Distutils config file (see section :ref:`inst-config-files`)::
559
560   [install]
561   install-base=$HOME
562   install-purelib=python/lib
563   install-platlib=python/lib.$PLAT
564   install-scripts=python/scripts
565   install-data=python/data
566
571   install-purelib=lib
572   install-platlib=lib.$PLAT
573   install-scripts=scripts
574   install-data=data
575
576Note that these two are *not* equivalent if you supply a different installation
577base directory when you run the setup script.  For example, ::
578
n579-   python setup.py --install-base=/tmp
n554+   python setup.py install --install-base=/tmp
580
581would install pure modules to :file:`{/tmp/python/lib}` in the first case, and
582to :file:`{/tmp/lib}` in the second case.  (For the second case, you probably
583want to supply an installation base of :file:`/tmp/python`.)
584
585You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample
586configuration file input.  These are Distutils configuration variables, which
587bear a strong resemblance to environment variables. In fact, you can use
588environment variables in config files on platforms that have such a notion but
589the Distutils additionally define a few extra variables that may not be in your
590environment, such as ``$PLAT``.  (And of course, on systems that don't have
591environment variables, such as Mac OS 9, the configuration variables supplied by
n592-the Distutils are the only ones you can use.) See section :ref:`config-files`
n567+the Distutils are the only ones you can use.) See section :ref:`inst-config-files`
593for details.
594
n595-.. % XXX need some Windows examples---when would custom
n570+.. XXX need some Windows examples---when would custom installation schemes be
596-.. % installation schemes be needed on those platforms?
571+   needed on those platforms?
597
n573+ 
598-.. % XXX I'm not sure where this section should go.
574+.. XXX I'm not sure where this section should go.
599
n600- 
601-.. _search-path:
576+.. _inst-search-path:
602
603Modifying Python's Search Path
604------------------------------
605
606When the Python interpreter executes an :keyword:`import` statement, it searches
607for both Python code and extension modules along a search path.  A default value
608for the path is configured into the Python binary when the interpreter is built.
609You can determine the path by importing the :mod:`sys` module and printing the
610value of ``sys.path``.   ::
611
612   $ python
613   Python 2.2 (#11, Oct  3 2002, 13:31:27)
614   [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
n615-   Type ``help''``copyright''``credits'' or ``license'' for more information.
n590+   Type "help""copyright""credits" or "license" for more information.
616   >>> import sys
617   >>> sys.path
n618-   ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2', 
n593+   ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
619-    '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload', 
594+    '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
620    '/usr/local/lib/python2.3/site-packages']
621   >>>
622
623The null string in ``sys.path`` represents the current working directory.
624
n625-.. % $ <-- bow to font-lock
626- 
627The expected convention for locally installed packages is to put them in the
n628-:file:`.../site-packages/` directory, but you may want to install Python modules
n601+:file:`{...}/site-packages/` directory, but you may want to install Python
629-into some arbitrary directory.  For example, your site may have a convention of
602+modules into some arbitrary directory.  For example, your site may have a
630-keeping all software related to the web server under :file:`/www`.  Add-on
603+convention of keeping all software related to the web server under :file:`/www`.
631-Python modules might then belong in :file:`/www/python`, and in order to import
604+Add-on Python modules might then belong in :file:`/www/python`, and in order to
632-them, this directory must be added to ``sys.path``.  There are several different
605+import them, this directory must be added to ``sys.path``.  There are several
633-ways to add the directory.
606+different ways to add the directory.
634
635The most convenient way is to add a path configuration file to a directory
636that's already on Python's path, usually to the :file:`.../site-packages/`
637directory.  Path configuration files have an extension of :file:`.pth`, and each
638line must contain a single path that will be appended to ``sys.path``.  (Because
639the new paths are appended to ``sys.path``, modules in the added directories
640will not override standard modules.  This means you can't use this mechanism for
641installing fixed versions of standard modules.)
642
643Paths can be absolute or relative, in which case they're relative to the
n644-directory containing the :file:`.pth` file.  Any directories added to the search
n617+directory containing the :file:`.pth` file.  See the documentation of
645-path will be scanned in turn for :file:`.pth` files.  See `site module
618+the :mod:`site` module for more information.
646-documentation <http://www.python.org/dev/doc/devel/lib/module-site.html>`_ for
647-more information.
648
649A slightly less convenient way is to edit the :file:`site.py` file in Python's
650standard library, and modify ``sys.path``.  :file:`site.py` is automatically
651imported when the Python interpreter is executed, unless the :option:`-S` switch
652is supplied to suppress this behaviour.  So you could simply edit
653:file:`site.py` and add two lines to it::
654
655   import sys
658However, if you reinstall the same major version of Python (perhaps when
659upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by
660the stock version.  You'd have to remember that it was modified and save a copy
661before doing the installation.
662
663There are two environment variables that can modify ``sys.path``.
664:envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python
665installation.  For example, if :envvar:`PYTHONHOME` is set to ``/www/python``,
n666-the search path will be set to ``['', '/www/python/lib/python|version|/',
n637+the search path will be set to ``['', '/www/python/lib/pythonX.Y/',
667-'/www/python/lib/python|version|/plat-linux2', ...]``.
638+'/www/python/lib/pythonX.Y/plat-linux2', ...]``.
668
669The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be
670added to the beginning of ``sys.path``.  For example, if :envvar:`PYTHONPATH` is
671set to ``/www/python:/opt/py``, the search path will begin with
672``['/www/python', '/opt/py']``.  (Note that directories must exist in order to
673be added to ``sys.path``; the :mod:`site` module removes paths that don't
674exist.)
675
676Finally, ``sys.path`` is just a regular Python list, so any Python application
677can modify it by adding or removing entries.
678
679
n680-.. _config-files:
n651+.. _inst-config-files:
681
682Distutils Configuration Files
683=============================
684
685As mentioned above, you can use Distutils configuration files to record personal
686or site preferences for any Distutils options.  That is, any option to any
687command can be stored in one of two or three (depending on your platform)
688configuration files, which will be consulted before the command-line is parsed.
689This means that configuration files will override default values, and the
690command-line will in turn override configuration files.  Furthermore, if
691multiple configuration files apply, values from "earlier" files are overridden
692by "later" files.
693
694
n695-.. _config-filenames:
n666+.. _inst-config-filenames:
696
697Location and names of config files
698----------------------------------
699
700The names and locations of the configuration files vary slightly across
701platforms.  On Unix and Mac OS X, the three configuration files (in the order
702they are processed) are:
703
730   where the Distutils are installed; under Python 1.6 and later on Unix, this is
731   as shown. For Python 1.5.2, the Distutils will normally be installed to
732   :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system
733   configuration file should be put there under Python 1.5.2.
734
735(2)
736   On Unix, if the :envvar:`HOME` environment variable is not defined, the user's
737   home directory will be determined with the :func:`getpwuid` function from the
n738-   standard :mod:`pwd` (XXX reference: ../lib/module-pwd.html) module.
n709+   standard :mod:`pwd` module.
739
740(3)
741   I.e., in the current directory (usually the location of the setup script).
742
743(4)
744   (See also note (1).)  Under Python 1.6 and later, Python's default "installation
745   prefix" is :file:`C:\\Python`, so the system configuration file is normally
746   :file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the
750   1.5.2 installation under Windows.
751
752(5)
753   On Windows, if the :envvar:`HOME` environment variable is not defined, no
754   personal configuration file will be found or used.  (In other words, the
755   Distutils make no attempt to guess your home directory on Windows.)
756
757
n758-.. _config-syntax:
n729+.. _inst-config-syntax:
759
760Syntax of config files
761----------------------
762
763The Distutils configuration files all have the same syntax.  The config files
764are grouped into sections.  There is one section for each Distutils command,
765plus a ``global`` section for global options that affect every command.  Each
766section consists of one option per line, specified as ``option=value``.
804and you can find out the complete list of global options by using
805:option:`--help` without a command::
806
807   python setup.py --help
808
809See also the "Reference" section of the "Distributing Python Modules" manual.
810
811
n812-.. _building-ext:
n783+.. _inst-building-ext:
813
814Building Extensions: Tips and Tricks
815====================================
816
817Whenever possible, the Distutils try to use the configuration information made
818available by the Python interpreter used to run the :file:`setup.py` script.
819For example, the same compiler and linker flags used to compile Python will also
820be used for compiling extensions.  Usually this will work well, but in
821complicated situations this might be inappropriate.  This section discusses how
822to override the usual Distutils behaviour.
823
824
n825-.. _tweak-flags:
n796+.. _inst-tweak-flags:
826
827Tweaking compiler/linker flags
828------------------------------
829
830Compiling a Python extension written in C or C++ will sometimes require
831specifying custom flags for the compiler and linker in order to use a particular
832library or produce a special kind of object code. This is especially true if the
n833-extension hasn't been tested on your  platform, or if you're trying to cross-
n804+extension hasn't been tested on your platform, or if you're trying to
834-compile Python.
805+cross-compile Python.
835
836In the most general case, the extension author might have foreseen that
837compiling the extensions would be complicated, and provided a :file:`Setup` file
838for you to edit.  This will likely only be done if the module distribution
839contains many separate extension modules, or if they often require elaborate
840sets of compiler flags in order to work.
841
842A :file:`Setup` file, if present, is parsed in order to get a list of extensions
887supply multiple :option:`-Xcompiler` options; for example, to pass ``-x c++``
888the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``.
889
890Compiler flags can also be supplied through setting the :envvar:`CFLAGS`
891environment variable.  If set, the contents of :envvar:`CFLAGS` will be added to
892the compiler flags specified in the  :file:`Setup` file.
893
894
n895-.. _non-ms-compilers:
n866+.. _inst-non-ms-compilers:
896
897Using non-Microsoft compilers on Windows
898----------------------------------------
899
900.. sectionauthor:: Rene Liebscher <R.Liebscher@gmx.de>
901
902
903
n904-Borland C++
n875+Borland/CodeGear C++
905-^^^^^^^^^^^
876+^^^^^^^^^^^^^^^^^^^^
906
n907-This subsection describes the necessary steps to use Distutils with the  Borland
n878+This subsection describes the necessary steps to use Distutils with the Borland
908C++ compiler version 5.5.  First you have to know that Borland's object file
909format (OMF) is different from the format used by the Python version you can
910download from the Python or ActiveState Web site.  (Python is built with
911Microsoft Visual C++, which uses COFF as the object file format.) For this
912reason you have to convert Python's library :file:`python25.lib` into the
913Borland format.  You can do this as follows:
914
n915-.. % Should we mention that users have to create cfg-files for the compiler?
n886+.. Should we mention that users have to create cfg-files for the compiler?
916-.. % see also http://community.borland.com/article/0,1410,21205,00.html
887+.. see also http://community.borland.com/article/0,1410,21205,00.html
917
918::
919
920   coff2omf python25.lib python25_bcpp.lib
921
922The :file:`coff2omf` program comes with the Borland compiler.  The file
923:file:`python25.lib` is in the :file:`Libs` directory of your Python
n924-installation.  If your extension uses other libraries (zlib,...) you have to
n895+installation.  If your extension uses other libraries (zlib, ...) you have to
925convert them too.
926
927The converted files have to reside in the same directories as the normal
928libraries.
929
930How does Distutils manage to use these libraries with their changed names?  If
931the extension needs a library (eg. :file:`foo`) Distutils checks first if it
932finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then
934the default name (:file:`foo.lib`.) [#]_
935
936To let Distutils compile your extension with Borland C++ you now have to type::
937
938   python setup.py build --compiler=bcpp
939
940If you want to use the Borland C++ compiler as the default, you could specify
941this in your personal or system-wide configuration file for Distutils (see
n942-section :ref:`config-files`.)
n913+section :ref:`inst-config-files`.)
943
944
945.. seealso::
946
n947-   `C++Builder Compiler <http://www.borland.com/bcppbuilder/freecompiler/>`_
n918+   `C++Builder Compiler <http://www.codegear.com/downloads/free/cppbuilder>`_
948      Information about the free C++ compiler from Borland, including links to the
949      download pages.
950
951   `Creating Python Extensions Using Borland's Free Compiler <http://www.cyberus.ca/~g_will/pyExtenDL.shtml>`_
952      Document describing how to use Borland's free command-line C++ compiler to build
953      Python.
954
955
962This section describes the necessary steps to use Distutils with the GNU C/C++
963compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter
964that was built with Cygwin, everything should work without any of these
965following steps.
966
967These compilers require some special libraries. This task is more complex than
968for Borland's C++, because there is no program to convert the library.  First
969you have to create a list of symbols which the Python DLL exports. (You can find
n970-a good program for this task at
n941+a good program for this task at http://www.emmestech.com/software/cygwin/pexports-0.43/download_pexports.html)
971-`<http://starship.python.net/crew/kernr/mingw32/Notes.html>`_, see at  PExports
972-0.42h there.)
973
n974-.. I don't understand what the next line means. --amk
n943+.. I don't understand what the next line means. --amk
975-.. % (inclusive the references on data structures.)
944+.. (inclusive the references on data structures.)
976
977::
978
979   pexports python25.dll >python25.def
980
981The location of an installed :file:`python25.dll` will depend on the
982installation options and the version and language of Windows.  In a "just for
983me" installation, it will appear in the root of the installation directory.  In
1000   python setup.py build --compiler=cygwin
1001
1002and for Cygwin in no-cygwin mode [#]_ or for MinGW type::
1003
1004   python setup.py build --compiler=mingw32
1005
1006If you want to use any of these options/compilers as default, you should
1007consider to write it in your personal or system-wide configuration file for
n1008-Distutils (see section :ref:`config-files`.)
n977+Distutils (see section :ref:`inst-config-files`.)
1009
1010
1011.. seealso::
1012
1013   `Building Python modules on MS Windows platform with MinGW <http://www.zope.org/Members/als/tips/win32_mingw_modules>`_
1014      Information about building the required libraries for the MinGW environment.
1015
n1016-   http://pyopengl.sourceforge.net/ftp/win32-stuff/
1017-      Converted import libraries in Cygwin/MinGW and Borland format, and a script to
1018-      create the registry entries needed for Distutils to locate the built Python.
1019
1020.. rubric:: Footnotes
1021
1022.. [#] This also means you could replace all existing COFF-libraries with OMF-libraries
1023   of the same name.
1024
n1025-.. [#] Check `<http://sources.redhat.com/cygwin/>`_ and `<http://www.mingw.org/>`_ for
n991+.. [#] Check http://sources.redhat.com/cygwin/ and http://www.mingw.org/ for more
1026-   more information
992+   information
1027
1028.. [#] Then you have no POSIX emulation available, but you also don't need
1029   :file:`cygwin1.dll`.
t1030- 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op