linuxport: Merging in the fruits of my labors (Python VFS)
[xbmc:xbmc-antiquated.git] / xbmc / lib / libPython / Python / Doc / inst / inst.tex
1 \documentclass{howto}
2 \usepackage{distutils}
3
4 % TODO:
5 %   Fill in XXX comments
6
7 \title{Installing Python Modules}
8
9 % The audience for this document includes people who don't know anything 
10 % about Python and aren't about to learn the language just in order to
11 % install and maintain it for their users, i.e. system administrators.
12 % Thus, I have to be sure to explain the basics at some point:
13 % sys.path and PYTHONPATH at least.  Should probably give pointers to
14 % other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
15
16 % Finally, it might be useful to include all the material from my "Care
17 % and Feeding of a Python Installation" talk in here somewhere.  Yow!
18
19 \input{boilerplate}
20
21 \author{Greg Ward}
22 \authoraddress{
23         \strong{Python Software Foundation}\\
24         Email: \email{distutils-sig@python.org}
25 }
26
27 \makeindex
28
29 \begin{document}
30
31 \maketitle
32
33 \begin{abstract}
34   \noindent
35   This document describes the Python Distribution Utilities
36   (``Distutils'') from the end-user's point-of-view, describing how to
37   extend the capabilities of a standard Python installation by building
38   and installing third-party Python modules and extensions.
39 \end{abstract}
40
41 %\begin{abstract}
42 %\noindent
43 %Abstract this!
44 %\end{abstract}
45
46
47 % The ugly "%begin{latexonly}" pseudo-environment suppresses the table
48 % of contents for HTML generation.
49 %
50 %begin{latexonly}
51 \tableofcontents
52 %end{latexonly}
53
54
55 \section{Introduction}
56 \label{intro}
57
58 Although Python's extensive standard library covers many programming
59 needs, there often comes a time when you need to add some new
60 functionality to your Python installation in the form of third-party
61 modules.  This might be necessary to support your own programming, or to
62 support an application that you want to use and that happens to be
63 written in Python.
64
65 In the past, there has been little support for adding third-party
66 modules to an existing Python installation.  With the introduction of
67 the Python Distribution Utilities (Distutils for short) in Python 2.0,
68 this changed.
69
70 This document is aimed primarily at the people who need to install
71 third-party Python modules: end-users and system administrators who just
72 need to get some Python application running, and existing Python
73 programmers who want to add some new goodies to their toolbox.  You
74 don't need to know Python to read this document; there will be some
75 brief forays into using Python's interactive mode to explore your
76 installation, but that's it.  If you're looking for information on how
77 to distribute your own Python modules so that others may use them, see
78 the \citetitle[../dist/dist.html]{Distributing Python Modules} manual.
79
80
81 \subsection{Best case: trivial installation}
82 \label{trivial-install}
83
84 In the best case, someone will have prepared a special version of the
85 module distribution you want to install that is targeted specifically at
86 your platform and is installed just like any other software on your
87 platform.  For example, the module developer might make an executable
88 installer available for Windows users, an RPM package for users of
89 RPM-based Linux systems (Red Hat, SuSE, Mandrake, and many others), a
90 Debian package for users of Debian-based Linux systems, and so forth.
91
92 In that case, you would download the installer appropriate to your
93 platform and do the obvious thing with it: run it if it's an executable
94 installer, \code{rpm --install} it if it's an RPM, etc.  You don't need
95 to run Python or a setup script, you don't need to compile
96 anything---you might not even need to read any instructions (although
97 it's always a good idea to do so anyways).
98
99 Of course, things will not always be that easy.  You might be interested
100 in a module distribution that doesn't have an easy-to-use installer for
101 your platform.  In that case, you'll have to start with the source
102 distribution released by the module's author/maintainer.  Installing
103 from a source distribution is not too hard, as long as the modules are
104 packaged in the standard way.  The bulk of this document is about
105 building and installing modules from standard source distributions.
106
107
108 \subsection{The new standard: Distutils}
109 \label{new-standard}
110
111 If you download a module source distribution, you can tell pretty
112 quickly if it was packaged and distributed in the standard way, i.e.
113 using the Distutils.  First, the distribution's name and version number
114 will be featured prominently in the name of the downloaded archive, e.g.
115 \file{foo-1.0.tar.gz} or \file{widget-0.9.7.zip}.  Next, the archive
116 will unpack into a similarly-named directory: \file{foo-1.0} or
117 \file{widget-0.9.7}.  Additionally, the distribution will contain a
118 setup script \file{setup.py}, and a file named \file{README.txt} or possibly
119 just \file{README}, which should explain that building and installing the
120 module distribution is a simple matter of running
121
122 \begin{verbatim}
123 python setup.py install
124 \end{verbatim}
125
126 If all these things are true, then you already know how to build and
127 install the modules you've just downloaded:  Run the command above.
128 Unless you need to install things in a non-standard way or customize the
129 build process, you don't really need this manual.  Or rather, the above
130 command is everything you need to get out of this manual.
131
132
133 \section{Standard Build and Install}
134 \label{standard-install}
135
136 As described in section~\ref{new-standard}, building and installing
137 a module distribution using the Distutils is usually one simple command:
138
139 \begin{verbatim}
140 python setup.py install
141 \end{verbatim}
142
143 On \UNIX, you'd run this command from a shell prompt; on Windows, you
144 have to open a command prompt window (``DOS box'') and do it there; on
145 Mac OS X, you open a \command{Terminal} window to get a shell prompt.
146
147
148 \subsection{Platform variations}
149 \label{platform-variations}
150
151 You should always run the setup command from the distribution root
152 directory, i.e. the top-level subdirectory that the module source
153 distribution unpacks into.  For example, if you've just downloaded a
154 module source distribution \file{foo-1.0.tar.gz} onto a
155 \UNIX{} system, the normal thing to do is:
156
157 \begin{verbatim}
158 gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
159 cd foo-1.0
160 python setup.py install
161 \end{verbatim}
162
163 On Windows, you'd probably download \file{foo-1.0.zip}.  If you
164 downloaded the archive file to \file{C:\textbackslash{}Temp}, then it
165 would unpack into \file{C:\textbackslash{}Temp\textbackslash{}foo-1.0};
166 you can use either a archive manipulator with a graphical user interface
167 (such as WinZip) or a command-line tool (such as \program{unzip} or
168 \program{pkunzip}) to unpack the archive.  Then, open a command prompt
169 window (``DOS box''), and run:
170
171 \begin{verbatim}
172 cd c:\Temp\foo-1.0
173 python setup.py install
174 \end{verbatim}
175
176 \subsection{Splitting the job up}
177 \label{splitting-up}
178
179 Running \code{setup.py install} builds and installs all modules in one
180 run.  If you prefer to work incrementally---especially useful if you
181 want to customize the build process, or if things are going wrong---you
182 can use the setup script to do one thing at a time.  This is
183 particularly helpful when the build and install will be done by
184 different users---for example, you might want to build a module distribution
185 and hand it off to a system administrator for installation (or do it
186 yourself, with super-user privileges).
187
188 For example, you can build everything in one step, and then install
189 everything in a second step, by invoking the setup script twice:
190
191 \begin{verbatim}
192 python setup.py build
193 python setup.py install
194 \end{verbatim}
195
196 If you do this, you will notice that running the \command{install}
197 command first runs the \command{build} command, which---in this
198 case---quickly notices that it has nothing to do, since everything in
199 the \file{build} directory is up-to-date.
200
201 You may not need this ability to break things down often if all you do
202 is install modules downloaded off the 'net, but it's very handy for more
203 advanced tasks.  If you get into distributing your own Python modules
204 and extensions, you'll run lots of individual Distutils commands on
205 their own.
206
207
208 \subsection{How building works}
209 \label{how-build-works}
210
211 As implied above, the \command{build} command is responsible for putting
212 the files to install into a \emph{build directory}.  By default, this is
213 \file{build} under the distribution root; if you're excessively
214 concerned with speed, or want to keep the source tree pristine, you can
215 change the build directory with the \longprogramopt{build-base} option.
216 For example:
217
218 \begin{verbatim}
219 python setup.py build --build-base=/tmp/pybuild/foo-1.0
220 \end{verbatim}
221
222 (Or you could do this permanently with a directive in your system or
223 personal Distutils configuration file; see
224 section~\ref{config-files}.)  Normally, this isn't necessary.
225
226 The default layout for the build tree is as follows:
227
228 \begin{verbatim}
229 --- build/ --- lib/
230 or
231 --- build/ --- lib.<plat>/
232                temp.<plat>/
233 \end{verbatim}
234
235 where \code{<plat>} expands to a brief description of the current
236 OS/hardware platform and Python version.  The first form, with just a
237 \file{lib} directory, is used for ``pure module distributions''---that
238 is, module distributions that include only pure Python modules.  If a
239 module distribution contains any extensions (modules written in C/\Cpp),
240 then the second form, with two \code{<plat>} directories, is used.  In
241 that case, the \file{temp.\filevar{plat}} directory holds temporary
242 files generated by the compile/link process that don't actually get
243 installed.  In either case, the \file{lib} (or
244 \file{lib.\filevar{plat}}) directory contains all Python modules (pure
245 Python and extensions) that will be installed.
246
247 In the future, more directories will be added to handle Python scripts,
248 documentation, binary executables, and whatever else is needed to handle
249 the job of installing Python modules and applications.
250
251
252 \subsection{How installation works}
253 \label{how-install-works}
254
255 After the \command{build} command runs (whether you run it explicitly,
256 or the \command{install} command does it for you), the work of the
257 \command{install} command is relatively simple: all it has to do is copy
258 everything under \file{build/lib} (or \file{build/lib.\filevar{plat}})
259 to your chosen installation directory.
260
261 If you don't choose an installation directory---i.e., if you just run
262 \code{setup.py install}---then the \command{install} command installs to
263 the standard location for third-party Python modules.  This location
264 varies by platform and by how you built/installed Python itself.  On
265 \UNIX{} (and Mac OS X, which is also Unix-based),
266 it also depends on whether the module distribution
267 being installed is pure Python or contains extensions (``non-pure''):
268 \begin{tableiv}{l|l|l|c}{textrm}%
269   {Platform}{Standard installation location}{Default value}{Notes}
270   \lineiv{\UNIX{} (pure)}
271           {\filenq{\filevar{prefix}/lib/python\shortversion/site-packages}}
272           {\filenq{/usr/local/lib/python\shortversion/site-packages}}
273           {(1)}
274   \lineiv{\UNIX{} (non-pure)}
275           {\filenq{\filevar{exec-prefix}/lib/python\shortversion/site-packages}}
276           {\filenq{/usr/local/lib/python\shortversion/site-packages}}
277           {(1)}
278   \lineiv{Windows}
279           {\filenq{\filevar{prefix}}}
280           {\filenq{C:\textbackslash{}Python}}
281           {(2)}
282 \end{tableiv}
283
284 \noindent Notes:
285 \begin{description}
286 \item[(1)] Most Linux distributions include Python as a standard part of
287   the system, so \filevar{prefix} and \filevar{exec-prefix} are usually
288   both \file{/usr} on Linux.  If you build Python yourself on Linux (or
289   any \UNIX-like system), the default \filevar{prefix} and
290   \filevar{exec-prefix} are \file{/usr/local}.
291 \item[(2)] The default installation directory on Windows was
292   \file{C:\textbackslash{}Program Files\textbackslash{}Python} under
293   Python 1.6a1, 1.5.2, and earlier.
294 \end{description}
295
296 \filevar{prefix} and \filevar{exec-prefix} stand for the directories
297 that Python is installed to, and where it finds its libraries at
298 run-time.  They are always the same under Windows, and very
299 often the same under \UNIX and Mac OS X.  You can find out what your Python
300 installation uses for \filevar{prefix} and \filevar{exec-prefix} by
301 running Python in interactive mode and typing a few simple commands.
302 Under \UNIX, just type \code{python} at the shell prompt.  Under
303 Windows, choose \menuselection{Start \sub Programs \sub Python
304 \shortversion \sub Python (command line)}.  
305 Once the interpreter is started, you type Python code at the
306 prompt.  For example, on my Linux system, I type the three Python
307 statements shown below, and get the output as shown, to find out my
308 \filevar{prefix} and \filevar{exec-prefix}:
309
310 \begin{verbatim}
311 Python 2.4 (#26, Aug  7 2004, 17:19:02) 
312 Type "help", "copyright", "credits" or "license" for more information.
313 >>> import sys
314 >>> sys.prefix
315 '/usr'
316 >>> sys.exec_prefix
317 '/usr'
318 \end{verbatim}
319
320 If you don't want to install modules to the standard location, or if you
321 don't have permission to write there, then you need to read about
322 alternate installations in section~\ref{alt-install}.  If you want to
323 customize your installation directories more heavily, see
324 section~\ref{custom-install} on custom installations.
325
326
327 % This rather nasty macro is used to generate the tables that describe
328 % each installation scheme.  It's nasty because it takes two arguments
329 % for each "slot" in an installation scheme, there will soon be more
330 % than five of these slots, and TeX has a limit of 10 arguments to a
331 % macro.  Uh-oh.
332
333 \newcommand{\installscheme}[8]
334   {\begin{tableiii}{l|l|l}{textrm}
335           {Type of file}
336           {Installation Directory}
337           {Override option}
338      \lineiii{pure module distribution}
339              {\filevar{#1}\filenq{#2}}
340              {\longprogramopt{install-purelib}}
341      \lineiii{non-pure module distribution}
342              {\filevar{#3}\filenq{#4}}
343              {\longprogramopt{install-platlib}}
344      \lineiii{scripts}
345              {\filevar{#5}\filenq{#6}}
346              {\longprogramopt{install-scripts}}
347      \lineiii{data}
348              {\filevar{#7}\filenq{#8}}
349              {\longprogramopt{install-data}}
350    \end{tableiii}}
351
352
353 \section{Alternate Installation}
354 \label{alt-install}
355
356 Often, it is necessary or desirable to install modules to a location
357 other than the standard location for third-party Python modules.  For
358 example, on a \UNIX{} system you might not have permission to write to the
359 standard third-party module directory.  Or you might wish to try out a
360 module before making it a standard part of your local Python
361 installation.  This is especially true when upgrading a distribution
362 already present: you want to make sure your existing base of scripts
363 still works with the new version before actually upgrading.
364
365 The Distutils \command{install} command is designed to make installing
366 module distributions to an alternate location simple and painless.  The
367 basic idea is that you supply a base directory for the installation, and
368 the \command{install} command picks a set of directories (called an
369 \emph{installation scheme}) under this base directory in which to
370 install files.  The details differ across platforms, so read whichever
371 of the following sections applies to you.
372
373
374 \subsection{Alternate installation: the home scheme}
375 \label{alt-install-prefix}
376
377 The idea behind the ``home scheme'' is that you build and maintain a
378 personal stash of Python modules.  This scheme's name is derived from
379 the idea of a ``home'' directory on \UNIX, since it's not unusual for
380 a \UNIX{} user to make their home directory have a layout similar to
381 \file{/usr/} or \file{/usr/local/}.  This scheme can be used by
382 anyone, regardless of the operating system their installing for.
383
384 Installing a new module distribution is as simple as
385
386 \begin{verbatim}
387 python setup.py install --home=<dir>
388 \end{verbatim}
389
390 where you can supply any directory you like for the
391 \longprogramopt{home} option.  On \UNIX, lazy typists can just type a
392 tilde (\code{\textasciitilde}); the \command{install} command will
393 expand this to your home directory:
394
395 \begin{verbatim}
396 python setup.py install --home=~
397 \end{verbatim}
398
399 The \longprogramopt{home} option defines the installation base
400 directory.  Files are installed to the following directories under the
401 installation base as follows:
402 \installscheme{home}{/lib/python}
403               {home}{/lib/python}
404               {home}{/bin}
405               {home}{/share}
406
407
408 \versionchanged[The \longprogramopt{home} option used to be supported
409                 only on \UNIX]{2.4}
410
411
412 \subsection{Alternate installation: \UNIX{} (the prefix scheme)}
413 \label{alt-install-home}
414
415 The ``prefix scheme'' is useful when you wish to use one Python
416 installation to perform the build/install (i.e., to run the setup
417 script), but install modules into the third-party module directory of a
418 different Python installation (or something that looks like a different
419 Python installation).  If this sounds a trifle unusual, it is---that's
420 why the ``home scheme'' comes first.  However, there are at least two
421 known cases where the prefix scheme will be useful.
422
423 First, consider that many Linux distributions put Python in \file{/usr},
424 rather than the more traditional \file{/usr/local}.  This is entirely
425 appropriate, since in those cases Python is part of ``the system''
426 rather than a local add-on.  However, if you are installing Python
427 modules from source, you probably want them to go in
428 \file{/usr/local/lib/python2.\filevar{X}} rather than
429 \file{/usr/lib/python2.\filevar{X}}.  This can be done with
430
431 \begin{verbatim}
432 /usr/bin/python setup.py install --prefix=/usr/local
433 \end{verbatim}
434
435 Another possibility is a network filesystem where the name used to write
436 to a remote directory is different from the name used to read it: for
437 example, the Python interpreter accessed as \file{/usr/local/bin/python}
438 might search for modules in \file{/usr/local/lib/python2.\filevar{X}},
439 but those modules would have to be installed to, say,
440 \file{/mnt/\filevar{@server}/export/lib/python2.\filevar{X}}.  This
441 could be done with
442
443 \begin{verbatim}
444 /usr/local/bin/python setup.py install --prefix=/mnt/@server/export
445 \end{verbatim}
446
447 In either case, the \longprogramopt{prefix} option defines the
448 installation base, and the \longprogramopt{exec-prefix} option defines
449 the platform-specific installation base, which is used for
450 platform-specific files.  (Currently, this just means non-pure module
451 distributions, but could be expanded to C libraries, binary executables,
452 etc.)  If \longprogramopt{exec-prefix} is not supplied, it defaults to
453 \longprogramopt{prefix}.  Files are installed as follows:
454
455 \installscheme{prefix}{/lib/python2.\filevar{X}/site-packages}
456               {exec-prefix}{/lib/python2.\filevar{X}/site-packages}
457               {prefix}{/bin}
458               {prefix}{/share}
459
460 There is no requirement that \longprogramopt{prefix} or
461 \longprogramopt{exec-prefix} actually point to an alternate Python
462 installation; if the directories listed above do not already exist, they
463 are created at installation time.
464
465 Incidentally, the real reason the prefix scheme is important is simply
466 that a standard \UNIX{} installation uses the prefix scheme, but with
467 \longprogramopt{prefix} and \longprogramopt{exec-prefix} supplied by
468 Python itself as \code{sys.prefix} and \code{sys.exec\_prefix}.  Thus,
469 you might think you'll never use the prefix scheme, but every time you
470 run \code{python setup.py install} without any other options, you're
471 using it.
472
473 Note that installing extensions to an alternate Python installation has
474 no effect on how those extensions are built: in particular, the Python
475 header files (\file{Python.h} and friends) installed with the Python
476 interpreter used to run the setup script will be used in compiling
477 extensions.  It is your responsibility to ensure that the interpreter
478 used to run extensions installed in this way is compatible with the
479 interpreter used to build them.  The best way to do this is to ensure
480 that the two interpreters are the same version of Python (possibly
481 different builds, or possibly copies of the same build).  (Of course, if
482 your \longprogramopt{prefix} and \longprogramopt{exec-prefix} don't even
483 point to an alternate Python installation, this is immaterial.)
484
485
486 \subsection{Alternate installation: Windows (the prefix scheme)}
487 \label{alt-install-windows}
488
489 Windows has no concept of a user's home directory, and since the
490 standard Python installation under Windows is simpler than under
491 \UNIX, the \longprogramopt{prefix} option has traditionally been used
492 to install additional packages in separate locations on Windows.
493
494 \begin{verbatim}
495 python setup.py install --prefix="\Temp\Python"
496 \end{verbatim}
497
498 to install modules to the
499 \file{\textbackslash{}Temp\textbackslash{}Python} directory on the
500 current drive.
501
502 The installation base is defined by the \longprogramopt{prefix} option;
503 the \longprogramopt{exec-prefix} option is not supported under Windows.
504 Files are installed as follows:
505 \installscheme{prefix}{}
506               {prefix}{}
507               {prefix}{\textbackslash{}Scripts}
508               {prefix}{\textbackslash{}Data}
509
510
511
512 \section{Custom Installation}
513 \label{custom-install}
514
515 Sometimes, the alternate installation schemes described in
516 section~\ref{alt-install} just don't do what you want.  You might
517 want to tweak just one or two directories while keeping everything under
518 the same base directory, or you might want to completely redefine the
519 installation scheme.  In either case, you're creating a \emph{custom
520 installation scheme}.
521
522 You probably noticed the column of ``override options'' in the tables
523 describing the alternate installation schemes above.  Those options are
524 how you define a custom installation scheme.  These override options can
525 be relative, absolute, or explicitly defined in terms of one of the
526 installation base directories.  (There are two installation base
527 directories, and they are normally the same---they only differ when you
528 use the \UNIX{} ``prefix scheme'' and supply different
529 \longprogramopt{prefix} and \longprogramopt{exec-prefix} options.)
530
531 For example, say you're installing a module distribution to your home
532 directory under \UNIX---but you want scripts to go in
533 \file{\textasciitilde/scripts} rather than \file{\textasciitilde/bin}.
534 As you might expect, you can override this directory with the
535 \longprogramopt{install-scripts} option; in this case, it makes most
536 sense to supply a relative path, which will be interpreted relative to
537 the installation base directory (your home directory, in this case):
538
539 \begin{verbatim}
540 python setup.py install --home=~ --install-scripts=scripts
541 \end{verbatim}
542
543 Another \UNIX{} example: suppose your Python installation was built and
544 installed with a prefix of \file{/usr/local/python}, so under a standard 
545 installation scripts will wind up in \file{/usr/local/python/bin}.  If
546 you want them in \file{/usr/local/bin} instead, you would supply this
547 absolute directory for the \longprogramopt{install-scripts} option:
548
549 \begin{verbatim}
550 python setup.py install --install-scripts=/usr/local/bin
551 \end{verbatim}
552
553 (This performs an installation using the ``prefix scheme,'' where the
554 prefix is whatever your Python interpreter was installed with---
555 \file{/usr/local/python} in this case.)
556
557 If you maintain Python on Windows, you might want third-party modules to
558 live in a subdirectory of \filevar{prefix}, rather than right in
559 \filevar{prefix} itself.  This is almost as easy as customizing the
560 script installation directory---you just have to remember that there are
561 two types of modules to worry about, pure modules and non-pure modules
562 (i.e., modules from a non-pure distribution).  For example:
563
564 \begin{verbatim}
565 python setup.py install --install-purelib=Site --install-platlib=Site
566 \end{verbatim}
567
568 The specified installation directories are relative to
569 \filevar{prefix}.  Of course, you also have to ensure that these
570 directories are in Python's module search path, such as by putting a
571 \file{.pth} file in \filevar{prefix}.  See section~\ref{search-path}
572 to find out how to modify Python's search path.
573
574 If you want to define an entire installation scheme, you just have to
575 supply all of the installation directory options.  The recommended way
576 to do this is to supply relative paths; for example, if you want to
577 maintain all Python module-related files under \file{python} in your
578 home directory, and you want a separate directory for each platform that
579 you use your home directory from, you might define the following
580 installation scheme:
581
582 \begin{verbatim}
583 python setup.py install --home=~ \
584                         --install-purelib=python/lib \
585                         --install-platlib=python/lib.$PLAT \
586                         --install-scripts=python/scripts
587                         --install-data=python/data
588 \end{verbatim}
589 % $ % -- bow to font-lock
590
591 or, equivalently,
592
593 \begin{verbatim}
594 python setup.py install --home=~/python \
595                         --install-purelib=lib \
596                         --install-platlib='lib.$PLAT' \
597                         --install-scripts=scripts
598                         --install-data=data
599 \end{verbatim}
600 % $ % -- bow to font-lock
601
602 \code{\$PLAT} is not (necessarily) an environment variable---it will be
603 expanded by the Distutils as it parses your command line options, just
604 as it does when parsing your configuration file(s).
605
606 Obviously, specifying the entire installation scheme every time you
607 install a new module distribution would be very tedious.  Thus, you can
608 put these options into your Distutils config file (see
609 section~\ref{config-files}):
610
611 \begin{verbatim}
612 [install]
613 install-base=$HOME
614 install-purelib=python/lib
615 install-platlib=python/lib.$PLAT
616 install-scripts=python/scripts
617 install-data=python/data
618 \end{verbatim}
619
620 or, equivalently,
621
622 \begin{verbatim}
623 [install]
624 install-base=$HOME/python
625 install-purelib=lib
626 install-platlib=lib.$PLAT
627 install-scripts=scripts
628 install-data=data
629 \end{verbatim}
630
631 Note that these two are \emph{not} equivalent if you supply a different
632 installation base directory when you run the setup script.  For example,
633
634 \begin{verbatim}
635 python setup.py --install-base=/tmp
636 \end{verbatim}
637
638 would install pure modules to \filevar{/tmp/python/lib} in the first
639 case, and to \filevar{/tmp/lib} in the second case.  (For the second
640 case, you probably want to supply an installation base of
641 \file{/tmp/python}.)
642
643 You probably noticed the use of \code{\$HOME} and \code{\$PLAT} in the
644 sample configuration file input.  These are Distutils configuration
645 variables, which bear a strong resemblance to environment variables.
646 In fact, you can use environment variables in config files on
647 platforms that have such a notion but the Distutils additionally
648 define a few extra variables that may not be in your environment, such
649 as \code{\$PLAT}.  (And of course, on systems that don't have
650 environment variables, such as Mac OS 9, the configuration
651 variables supplied by the Distutils are the only ones you can use.)
652 See section~\ref{config-files} for details.
653
654 % XXX need some Windows examples---when would custom
655 % installation schemes be needed on those platforms?
656
657
658 % XXX I'm not sure where this section should go.
659 \subsection{Modifying Python's Search Path}
660 \label{search-path}
661
662 When the Python interpreter executes an \keyword{import} statement, it
663 searches for both Python code and extension modules along a search
664 path.  A default value for the path is configured into the Python
665 binary when the interpreter is built.  You can determine the path by
666 importing the \module{sys} module and printing the value of
667 \code{sys.path}.  
668
669 \begin{verbatim}
670 $ python
671 Python 2.2 (#11, Oct  3 2002, 13:31:27)
672 [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
673 Type ``help'', ``copyright'', ``credits'' or ``license'' for more information.
674 >>> import sys
675 >>> sys.path
676 ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2', 
677  '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload', 
678  '/usr/local/lib/python2.3/site-packages']
679 >>>
680 \end{verbatim} % $ <-- bow to font-lock
681
682 The null string in \code{sys.path} represents the current working
683 directory.   
684
685 The expected convention for locally installed packages is to put them
686 in the \file{.../site-packages/} directory, but you may want to
687 install Python modules into some arbitrary directory.  For example,
688 your site may have a convention of keeping all software related to the
689 web server under \file{/www}.  Add-on Python modules might then belong
690 in \file{/www/python}, and in order to import them, this directory
691 must be added to \code{sys.path}.  There are several different ways to
692 add the directory.
693
694 The most convenient way is to add a path configuration file to a
695 directory that's already on Python's path, usually to the
696 \file{.../site-packages/} directory.  Path configuration files have an
697 extension of \file{.pth}, and each line must contain a single path
698 that will be appended to \code{sys.path}.  (Because the new paths are
699 appended to \code{sys.path}, modules in the added directories will not
700 override standard modules.  This means you can't use this mechanism
701 for installing fixed versions of standard modules.)
702
703 Paths can be absolute or relative, in which case they're relative to
704 the directory containing the \file{.pth} file.  Any directories added
705 to the search path will be scanned in turn for \file{.pth} files.  See
706 \citetitle[http://www.python.org/dev/doc/devel/lib/module-site.html]
707 {site module documentation} for more information.
708
709 A slightly less convenient way is to edit the \file{site.py} file in
710 Python's standard library, and modify \code{sys.path}.  \file{site.py}
711 is automatically imported when the Python interpreter is executed,
712 unless the \programopt{-S} switch is supplied to suppress this
713 behaviour.  So you could simply edit \file{site.py} and add two lines to it:
714
715 \begin{verbatim}
716 import sys
717 sys.path.append('/www/python/')
718 \end{verbatim}
719
720 However, if you reinstall the same major version of Python (perhaps
721 when upgrading from 2.2 to 2.2.2, for example) \file{site.py} will be
722 overwritten by the stock version.  You'd have to remember that it was
723 modified and save a copy before doing the installation.
724
725 There are two environment variables that can modify \code{sys.path}.
726 \envvar{PYTHONHOME} sets an alternate value for the prefix of the
727 Python installation.  For example, if \envvar{PYTHONHOME} is set to
728 \samp{/www/python}, the search path will be set to \code{['',
729 '/www/python/lib/python2.2/', '/www/python/lib/python2.3/plat-linux2',
730 ...]}.  
731
732 The \envvar{PYTHONPATH} variable can be set to a list of paths that
733 will be added to the beginning of \code{sys.path}.  For example, if
734 \envvar{PYTHONPATH} is set to \samp{/www/python:/opt/py}, the search
735 path will begin with \code{['/www/python', '/opt/py']}.  (Note that
736 directories must exist in order to be added to \code{sys.path}; the
737 \module{site} module removes paths that don't exist.)
738
739 Finally, \code{sys.path} is just a regular Python list, so any Python
740 application can modify it by adding or removing entries.
741
742
743 \section{Distutils Configuration Files}
744 \label{config-files}
745
746 As mentioned above, you can use Distutils configuration files to record
747 personal or site preferences for any Distutils options.  That is, any
748 option to any command can be stored in one of two or three (depending on
749 your platform) configuration files, which will be consulted before the
750 command-line is parsed.  This means that configuration files will
751 override default values, and the command-line will in turn override
752 configuration files.  Furthermore, if multiple configuration files
753 apply, values from ``earlier'' files are overridden by ``later'' files.
754
755
756 \subsection{Location and names of config files}
757 \label{config-filenames}
758
759 The names and locations of the configuration files vary slightly across
760 platforms.  On \UNIX and Mac OS X, the three configuration files (in the order they
761 are processed) are:
762 \begin{tableiii}{l|l|c}{textrm}
763   {Type of file}{Location and filename}{Notes}
764   \lineiii{system}{\filenq{\filevar{prefix}/lib/python\filevar{ver}/distutils/distutils.cfg}}{(1)}
765   \lineiii{personal}{\filenq{\$HOME/.pydistutils.cfg}}{(2)}
766   \lineiii{local}{\filenq{setup.cfg}}{(3)}
767 \end{tableiii}
768
769 And on Windows, the configuration files are:
770 \begin{tableiii}{l|l|c}{textrm}
771   {Type of file}{Location and filename}{Notes}
772   \lineiii{system}{\filenq{\filevar{prefix}\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}distutils.cfg}}{(4)}
773   \lineiii{personal}{\filenq{\%HOME\%\textbackslash{}pydistutils.cfg}}{(5)}
774   \lineiii{local}{\filenq{setup.cfg}}{(3)}
775 \end{tableiii}
776
777 \noindent Notes:
778 \begin{description}
779 \item[(1)] Strictly speaking, the system-wide configuration file lives
780   in the directory where the Distutils are installed; under Python 1.6
781   and later on \UNIX, this is as shown. For Python 1.5.2, the Distutils
782   will normally be installed to
783   \file{\filevar{prefix}/lib/python1.5/site-packages/distutils},
784   so the system configuration file should be put there under Python
785   1.5.2.
786 \item[(2)] On \UNIX, if the \envvar{HOME} environment variable is not
787   defined, the user's home directory will be determined with the
788   \function{getpwuid()} function from the standard
789   \ulink{\module{pwd}}{../lib/module-pwd.html} module.
790 \item[(3)] I.e., in the current directory (usually the location of the
791   setup script).
792 \item[(4)] (See also note (1).)  Under Python 1.6 and later, Python's
793   default ``installation prefix'' is \file{C:\textbackslash{}Python}, so
794   the system configuration file is normally
795   \file{C:\textbackslash{}Python\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}distutils.cfg}.
796   Under Python 1.5.2, the default prefix was
797   \file{C:\textbackslash{}Program~Files\textbackslash{}Python}, and the
798   Distutils were not part of the standard library---so the system
799   configuration file would be
800   \file{C:\textbackslash{}Program~Files\textbackslash{}Python\textbackslash{}distutils\textbackslash{}distutils.cfg}
801   in a standard Python 1.5.2 installation under Windows.
802 \item[(5)] On Windows, if the \envvar{HOME} environment variable is not
803   defined, no personal configuration file will be found or used.  (In
804   other words, the Distutils make no attempt to guess your home
805   directory on Windows.)
806 \end{description}
807
808
809 \subsection{Syntax of config files}
810 \label{config-syntax}
811
812 The Distutils configuration files all have the same syntax.  The config
813 files are grouped into sections.  There is one section for each Distutils
814 command, plus a \code{global} section for global options that affect
815 every command.  Each section consists of one option per line, specified
816 as \code{option=value}.
817
818 For example, the following is a complete config file that just forces
819 all commands to run quietly by default:
820
821 \begin{verbatim}
822 [global]
823 verbose=0
824 \end{verbatim}
825
826 If this is installed as the system config file, it will affect all
827 processing of any Python module distribution by any user on the current
828 system.  If it is installed as your personal config file (on systems
829 that support them), it will affect only module distributions processed
830 by you.  And if it is used as the \file{setup.cfg} for a particular
831 module distribution, it affects only that distribution.
832
833 You could override the default ``build base'' directory and make the
834 \command{build*} commands always forcibly rebuild all files with the
835 following:
836
837 \begin{verbatim}
838 [build]
839 build-base=blib
840 force=1
841 \end{verbatim}
842
843 which corresponds to the command-line arguments
844
845 \begin{verbatim}
846 python setup.py build --build-base=blib --force
847 \end{verbatim}
848
849 except that including the \command{build} command on the command-line
850 means that command will be run.  Including a particular command in
851 config files has no such implication; it only means that if the command
852 is run, the options in the config file will apply.  (Or if other
853 commands that derive values from it are run, they will use the values in
854 the config file.)
855
856 You can find out the complete list of options for any command using the
857 \longprogramopt{help} option, e.g.:
858
859 \begin{verbatim}
860 python setup.py build --help
861 \end{verbatim}
862
863 and you can find out the complete list of global options by using
864 \longprogramopt{help} without a command:
865
866 \begin{verbatim}
867 python setup.py --help
868 \end{verbatim}
869
870 See also the ``Reference'' section of the ``Distributing Python
871 Modules'' manual.
872
873 \section{Building Extensions: Tips and Tricks}
874 \label{building-ext}
875
876 Whenever possible, the Distutils try to use the configuration
877 information made available by the Python interpreter used to run the
878 \file{setup.py} script.  For example, the same compiler and linker
879 flags used to compile Python will also be used for compiling
880 extensions.  Usually this will work well, but in complicated
881 situations this might be inappropriate.  This section discusses how to
882 override the usual Distutils behaviour.
883
884 \subsection{Tweaking compiler/linker flags}
885 \label{tweak-flags}
886
887 Compiling a Python extension written in C or \Cpp{} will sometimes
888 require specifying custom flags for the compiler and linker in order
889 to use a particular library or produce a special kind of object code.
890 This is especially true if the extension hasn't been tested on your 
891 platform, or if you're trying to cross-compile Python.
892
893 In the most general case, the extension author might have foreseen
894 that compiling the extensions would be complicated, and provided a
895 \file{Setup} file for you to edit.  This will likely only be done if
896 the module distribution contains many separate extension modules, or
897 if they often require elaborate sets of compiler flags in order to work.
898
899 A \file{Setup} file, if present, is parsed in order to get a list of
900 extensions to build.  Each line in a \file{Setup} describes a single
901 module.  Lines have the following structure:
902
903 \begin{alltt}
904 \var{module} ... [\var{sourcefile} ...] [\var{cpparg} ...] [\var{library} ...]
905 \end{alltt}
906
907 Let's examine each of the fields in turn.
908
909 \begin{itemize}
910
911 \item \var{module} is the name of the extension module to be built,
912       and should be a valid Python identifier.  You can't just change
913       this in order to rename a module (edits to the source code would
914       also be needed), so this should be left alone.
915
916 \item \var{sourcefile} is anything that's likely to be a source code
917       file, at least judging by the filename.  Filenames ending in
918       \file{.c} are assumed to be written in C, filenames ending in
919       \file{.C}, \file{.cc}, and \file{.c++} are assumed to be
920       \Cpp, and filenames ending in \file{.m} or \file{.mm} are
921       assumed to be in Objective C.
922
923 \item \var{cpparg} is an argument for the C preprocessor, 
924       and is anything starting with \programopt{-I}, \programopt{-D},
925       \programopt{-U} or \programopt{-C}.
926
927 \item \var{library} is anything ending in \file{.a} or beginning with
928       \programopt{-l} or \programopt{-L}.
929 \end{itemize}
930
931 If a particular platform requires a special library on your platform,
932 you can add it by editing the \file{Setup} file and running
933 \code{python setup.py build}.  For example, if the module defined by the line
934
935 \begin{verbatim}
936 foo foomodule.c
937 \end{verbatim}
938
939 must be linked with the math library \file{libm.a} on your platform,
940 simply add \programopt{-lm} to the line:
941
942 \begin{verbatim}
943 foo foomodule.c -lm
944 \end{verbatim}
945
946 Arbitrary switches intended for the compiler or the linker can be
947 supplied with the \programopt{-Xcompiler} \var{arg} and
948 \programopt{-Xlinker} \var{arg} options:
949
950 \begin{verbatim}
951 foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
952 \end{verbatim}
953
954 The next option after \programopt{-Xcompiler} and
955 \programopt{-Xlinker} will be appended to the proper command line, so
956 in the above example the compiler will be passed the \programopt{-o32}
957 option, and the linker will be passed \programopt{-shared}.  If a
958 compiler option requires an argument, you'll have to supply multiple
959 \programopt{-Xcompiler} options; for example, to pass \code{-x c++} the
960 \file{Setup} file would have to contain
961 \code{-Xcompiler -x -Xcompiler c++}.
962
963 Compiler flags can also be supplied through setting the
964 \envvar{CFLAGS} environment variable.  If set, the contents of
965 \envvar{CFLAGS} will be added to the compiler flags specified in the 
966 \file{Setup} file.
967
968
969 \subsection{Using non-Microsoft compilers on Windows \label{non-ms-compilers}}
970 \sectionauthor{Rene Liebscher}{R.Liebscher@gmx.de}
971
972 \subsubsection{Borland \Cpp}
973
974 This subsection describes the necessary steps to use Distutils with the 
975 Borland \Cpp{} compiler version 5.5.
976 %Should we mention that users have to create cfg-files for the compiler?
977 %see also http://community.borland.com/article/0,1410,21205,00.html 
978
979 First you have to know that Borland's object file format (OMF) is
980 different from the format used by the Python version you can download
981 from the Python or ActiveState Web site.  (Python is built with
982 Microsoft Visual \Cpp, which uses COFF as the object file format.)
983 For this reason you have to convert Python's library
984 \file{python24.lib} into the Borland format.  You can do this as
985 follows:
986
987 \begin{verbatim}
988 coff2omf python24.lib python24_bcpp.lib
989 \end{verbatim}
990
991 The \file{coff2omf} program comes with the Borland compiler.  The file
992 \file{python24.lib} is in the \file{Libs} directory of your Python
993 installation.  If your extension uses other libraries (zlib,...) you
994 have to convert them too.
995
996 The converted files have to reside in the same directories as the
997 normal libraries.
998
999 How does Distutils manage to use these libraries with their changed
1000 names?  If the extension needs a library (eg. \file{foo}) Distutils
1001 checks first if it finds a library with suffix \file{_bcpp}
1002 (eg. \file{foo_bcpp.lib}) and then uses this library.  In the case it
1003 doesn't find such a special library it uses the default name
1004 (\file{foo.lib}.)\footnote{This also means you could replace all
1005 existing COFF-libraries with OMF-libraries of the same name.}
1006
1007 To let Distutils compile your extension with Borland \Cpp{} you now have
1008 to type:
1009
1010 \begin{verbatim}
1011 python setup.py build --compiler=bcpp
1012 \end{verbatim}
1013
1014 If you want to use the Borland \Cpp{} compiler as the default, you
1015 could specify this in your personal or system-wide configuration file
1016 for Distutils (see section~\ref{config-files}.)
1017  
1018 \begin{seealso}
1019   \seetitle[http://www.borland.com/bcppbuilder/freecompiler/]
1020     {\Cpp{}Builder Compiler}
1021     {Information about the free \Cpp{} compiler from Borland,
1022      including links to the download pages.}
1023
1024   \seetitle[http://www.cyberus.ca/\~{}g_will/pyExtenDL.shtml]
1025     {Creating Python Extensions Using Borland's Free Compiler}
1026     {Document describing how to use Borland's free command-line \Cpp
1027      compiler to build Python.}
1028 \end{seealso}
1029
1030
1031 \subsubsection{GNU C / Cygwin / MinGW}
1032
1033 This section describes the necessary steps to use Distutils with the
1034 GNU C/\Cpp{} compilers in their Cygwin and MinGW
1035 distributions.\footnote{Check
1036 \url{http://sources.redhat.com/cygwin/} and
1037 \url{http://www.mingw.org/} for more information}
1038 For a Python interpreter that was built with Cygwin, everything should
1039 work without any of these following steps.
1040
1041 These compilers require some special libraries.
1042 This task is more complex than for Borland's \Cpp, because there is no
1043 program to convert the library.
1044 % I don't understand what the next line means. --amk
1045 % (inclusive the references on data structures.)
1046  
1047 First you have to create a list of symbols which the Python DLL exports.
1048 (You can find a good program for this task at 
1049 \url{http://starship.python.net/crew/kernr/mingw32/Notes.html}, see at 
1050 PExports 0.42h there.)
1051
1052 \begin{verbatim}
1053 pexports python24.dll >python24.def
1054 \end{verbatim}
1055
1056 Then you can create from these information an import library for gcc.
1057  
1058 \begin{verbatim}
1059 dlltool --dllname python24.dll --def python24.def --output-lib libpython24.a
1060 \end{verbatim}
1061
1062 The resulting library has to be placed in the same directory as 
1063 \file{python24.lib}. (Should be the \file{libs} directory under your
1064 Python installation directory.)
1065
1066 If your extension uses other libraries (zlib,...) you might 
1067 have to convert them too.
1068 The converted files have to reside in the same directories as the normal
1069 libraries do.
1070
1071 To let Distutils compile your extension with Cygwin you now have to type
1072
1073 \begin{verbatim}
1074 python setup.py build --compiler=cygwin
1075 \end{verbatim}
1076
1077 and for Cygwin in no-cygwin mode\footnote{Then you have no
1078 \POSIX{} emulation available, but you also don't need
1079 \file{cygwin1.dll}.} or for MinGW type:
1080  
1081 \begin{verbatim}
1082 python setup.py build --compiler=mingw32
1083 \end{verbatim}
1084
1085 If you want to use any of these options/compilers as default, you should
1086 consider to write it in your personal or system-wide configuration file
1087 for Distutils (see section~\ref{config-files}.)
1088
1089 \begin{seealso}
1090   \seetitle[http://www.zope.org/Members/als/tips/win32_mingw_modules]
1091     {Building Python modules on MS Windows platform with MinGW}
1092     {Information about building the required libraries for the MinGW
1093      environment.}
1094
1095   \seeurl{http://pyopengl.sourceforge.net/ftp/win32-stuff/}
1096     {Converted import libraries in Cygwin/MinGW and Borland format,
1097      and a script to create the registry entries needed for Distutils
1098      to locate the built Python.}
1099 \end{seealso}
1100
1101
1102
1103 \end{document}