blob: f86fed3304067a6e0cec9de037a63ded8739baee [file] [log] [blame]
Greg Ward7c1e5f62000-03-10 01:56:58 +00001\documentclass{howto}
Greg Ward7593eb32000-04-09 03:59:15 +00002\usepackage{distutils}
Greg Ward7c1e5f62000-03-10 01:56:58 +00003
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +00004% TODO:
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +00005% Fill in XXX comments
6
Greg Ward7c1e5f62000-03-10 01:56:58 +00007\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%
Greg Ward7c1e5f62000-03-10 01:56:58 +000016% 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
Greg Ward7c1e5f62000-03-10 01:56:58 +000019\author{Greg Ward}
Fred Drake17f690f2001-07-14 02:14:42 +000020\authoraddress{Email: \email{gward@python.net}}
Greg Ward7c1e5f62000-03-10 01:56:58 +000021
Greg Warde3cca262000-08-31 16:36:31 +000022\makeindex
Greg Ward7c1e5f62000-03-10 01:56:58 +000023
24\begin{document}
25
26\maketitle
27
Greg Warde3cca262000-08-31 16:36:31 +000028\begin{abstract}
29 \noindent
30 This document describes the Python Distribution Utilities
31 (``Distutils'') from the end-user's point-of-view, describing how to
32 extend the capabilities of a standard Python installation by building
33 and installing third-party Python modules and extensions.
34\end{abstract}
35
Greg Ward7c1e5f62000-03-10 01:56:58 +000036%\begin{abstract}
37%\noindent
38%Abstract this!
39%\end{abstract}
40
Fred Drakea9a83e92001-03-01 18:37:52 +000041
42% The ugly "%begin{latexonly}" pseudo-environment supresses the table
43% of contents for HTML generation.
44%
45%begin{latexonly}
Greg Ward7c1e5f62000-03-10 01:56:58 +000046\tableofcontents
Fred Drakea9a83e92001-03-01 18:37:52 +000047%end{latexonly}
48
Greg Ward7c1e5f62000-03-10 01:56:58 +000049
50\section{Introduction}
Greg Warde78298a2000-04-28 17:12:24 +000051\label{intro}
Greg Ward7c1e5f62000-03-10 01:56:58 +000052
Greg Ward6002ffc2000-04-09 20:54:50 +000053Although Python's extensive standard library covers many programming
54needs, there often comes a time when you need to add some new
55functionality to your Python installation in the form of third-party
56modules. This might be necessary to support your own programming, or to
57support an application that you want to use and that happens to be
58written in Python.
59
60In the past, there has been little support for adding third-party
61modules to an existing Python installation. With the introduction of
Fred Drake01df4532000-06-30 03:36:41 +000062the Python Distribution Utilities (Distutils for short) in Python 2.0,
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +000063this changed.
Greg Ward6002ffc2000-04-09 20:54:50 +000064
65This document is aimed primarily at the people who need to install
66third-party Python modules: end-users and system administrators who just
67need to get some Python application running, and existing Python
68programmers who want to add some new goodies to their toolbox. You
69don't need to know Python to read this document; there will be some
70brief forays into using Python's interactive mode to explore your
71installation, but that's it. If you're looking for information on how
72to distribute your own Python modules so that others may use them, see
Fred Drake01df4532000-06-30 03:36:41 +000073the \citetitle[../dist/dist.html]{Distributing Python Modules} manual.
Greg Ward7c1e5f62000-03-10 01:56:58 +000074
75
Greg Ward6002ffc2000-04-09 20:54:50 +000076\subsection{Best case: trivial installation}
Greg Ward1ed49ee2000-09-13 00:00:58 +000077\label{trivial-install}
Greg Ward6002ffc2000-04-09 20:54:50 +000078
79In the best case, someone will have prepared a special version of the
80module distribution you want to install that is targeted specifically at
81your platform and is installed just like any other software on your
82platform. For example, the module developer might make an executable
83installer available for Windows users, an RPM package for users of
84RPM-based Linux systems (Red Hat, SuSE, Mandrake, and many others), a
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +000085Debian package for users of Debian-based Linux systems, and so forth.
Greg Ward6002ffc2000-04-09 20:54:50 +000086
87In that case, you would download the installer appropriate to your
Greg Wardc392caa2000-04-11 02:00:26 +000088platform and do the obvious thing with it: run it if it's an executable
89installer, \code{rpm --install} it if it's an RPM, etc. You don't need
90to run Python or a setup script, you don't need to compile
91anything---you might not even need to read any instructions (although
92it's always a good idea to do so anyways).
Greg Ward6002ffc2000-04-09 20:54:50 +000093
94Of course, things will not always be that easy. You might be interested
Greg Wardc392caa2000-04-11 02:00:26 +000095in a module distribution that doesn't have an easy-to-use installer for
96your platform. In that case, you'll have to start with the source
97distribution released by the module's author/maintainer. Installing
98from a source distribution is not too hard, as long as the modules are
99packaged in the standard way. The bulk of this document is about
100building and installing modules from standard source distributions.
Greg Ward7c1e5f62000-03-10 01:56:58 +0000101
102
Greg Ward6002ffc2000-04-09 20:54:50 +0000103\subsection{The new standard: Distutils}
Greg Warde78298a2000-04-28 17:12:24 +0000104\label{new-standard}
Greg Ward6002ffc2000-04-09 20:54:50 +0000105
106If you download a module source distribution, you can tell pretty
Greg Ward19c67f82000-06-24 01:33:16 +0000107quickly if it was packaged and distributed in the standard way, i.e.
108using the Distutils. First, the distribution's name and version number
109will be featured prominently in the name of the downloaded archive, e.g.
Greg Ward6002ffc2000-04-09 20:54:50 +0000110\file{foo-1.0.tar.gz} or \file{widget-0.9.7.zip}. Next, the archive
111will unpack into a similarly-named directory: \file{foo-1.0} or
112\file{widget-0.9.7}. Additionally, the distribution will contain a
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000113setup script \file{setup.py}, and a file named \file{README.txt} or possibly
114just \file{README}, which should explain that building and installing the
Greg Ward6002ffc2000-04-09 20:54:50 +0000115module distribution is a simple matter of running
Fred Drakea9a83e92001-03-01 18:37:52 +0000116
Greg Ward6002ffc2000-04-09 20:54:50 +0000117\begin{verbatim}
118python setup.py install
119\end{verbatim}
120
121If all these things are true, then you already know how to build and
Fred Drake8612a432002-10-31 20:46:20 +0000122install the modules you've just downloaded: Run the command above.
Greg Ward6002ffc2000-04-09 20:54:50 +0000123Unless you need to install things in a non-standard way or customize the
124build process, you don't really need this manual. Or rather, the above
125command is everything you need to get out of this manual.
Greg Ward7c1e5f62000-03-10 01:56:58 +0000126
127
Greg Ward29576562000-03-18 15:11:50 +0000128\section{Standard Build and Install}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000129\label{standard-install}
Greg Ward7c1e5f62000-03-10 01:56:58 +0000130
Greg Warde78298a2000-04-28 17:12:24 +0000131As described in section~\ref{new-standard}, building and installing
Greg Ward6002ffc2000-04-09 20:54:50 +0000132a module distribution using the Distutils is usually one simple command:
Fred Drakea9a83e92001-03-01 18:37:52 +0000133
Greg Ward6002ffc2000-04-09 20:54:50 +0000134\begin{verbatim}
135python setup.py install
136\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000137
Fred Drakeeff9a872000-10-26 16:41:03 +0000138On \UNIX, you'd run this command from a shell prompt; on Windows, you
Greg Warde24f05e2000-09-12 23:55:19 +0000139have to open a command prompt window (``DOS box'') and do it there; on
Fred Drake74f1a562001-09-25 15:12:41 +0000140Mac OS, things are a tad more complicated (see below).
Greg Ward6002ffc2000-04-09 20:54:50 +0000141
142
143\subsection{Platform variations}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000144\label{platform-variations}
Greg Ward6002ffc2000-04-09 20:54:50 +0000145
146You should always run the setup command from the distribution root
147directory, i.e. the top-level subdirectory that the module source
148distribution unpacks into. For example, if you've just downloaded a
Fred Drakeeff9a872000-10-26 16:41:03 +0000149module source distribution \file{foo-1.0.tar.gz} onto a
150\UNIX{} system, the normal thing to do is:
Fred Drakea9a83e92001-03-01 18:37:52 +0000151
Greg Ward6002ffc2000-04-09 20:54:50 +0000152\begin{verbatim}
153gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
154cd foo-1.0
155python setup.py install
156\end{verbatim}
157
Greg Warde24f05e2000-09-12 23:55:19 +0000158On Windows, you'd probably download \file{foo-1.0.zip}. If you
159downloaded the archive file to \file{C:\textbackslash{}Temp}, then it
160would unpack into \file{C:\textbackslash{}Temp\textbackslash{}foo-1.0};
Fred Drake17f690f2001-07-14 02:14:42 +0000161you can use either a archive manipulator with a grapical user interface
162(such as WinZip) or a command-line tool (such as \program{unzip} or
163\program{pkunzip}) to unpack the archive. Then, open a command prompt
164window (``DOS box''), and run:
Fred Drakea9a83e92001-03-01 18:37:52 +0000165
Greg Ward6002ffc2000-04-09 20:54:50 +0000166\begin{verbatim}
Greg Warde24f05e2000-09-12 23:55:19 +0000167cd c:\Temp\foo-1.0
Greg Ward6002ffc2000-04-09 20:54:50 +0000168python setup.py install
169\end{verbatim}
170
Fred Drake74f1a562001-09-25 15:12:41 +0000171On Mac OS, you have to go through a bit more effort to supply
Greg Warde24f05e2000-09-12 23:55:19 +0000172command-line arguments to the setup script:
173\begin{itemize}
174\item hit option-double-click on the script's icon (or option-drop it
175 onto the Python interpreter's icon)
176\item press the ``Set unix-style command line'' button
177\item set the ``Keep stdio window open on termination'' if you're
178 interested in seeing the output of the setup script (which is usually
179 voluminous and often useful)
Greg Ward15f5e2a2000-09-26 02:54:43 +0000180\item when the command-line dialog pops up, enter ``install'' (you
Greg Warde24f05e2000-09-12 23:55:19 +0000181 can, of course, enter any Distutils command-line as described in this
Fred Drakeeff9a872000-10-26 16:41:03 +0000182 document or in \citetitle[../dist/dist.html]{Distributing Python
183 Modules}: just leave off the initial \code{python setup.py} and
184 you'll be fine)
Greg Warde24f05e2000-09-12 23:55:19 +0000185\end{itemize}
Greg Wardc392caa2000-04-11 02:00:26 +0000186
Greg Ward6002ffc2000-04-09 20:54:50 +0000187
188\subsection{Splitting the job up}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000189\label{splitting-up}
Greg Ward6002ffc2000-04-09 20:54:50 +0000190
191Running \code{setup.py install} builds and installs all modules in one
Greg Ward14deaae2000-09-11 00:33:15 +0000192run. If you prefer to work incrementally---especially useful if you
193want to customize the build process, or if things are going wrong---you
194can use the setup script to do one thing at a time. This is
Greg Ward3e7b1332000-05-30 03:00:43 +0000195particularly helpful when the build and install will be done by
Fred Drake8612a432002-10-31 20:46:20 +0000196different users---for example, you might want to build a module distribution
Greg Ward3e7b1332000-05-30 03:00:43 +0000197and hand it off to a system administrator for installation (or do it
198yourself, with super-user privileges).
Greg Ward6002ffc2000-04-09 20:54:50 +0000199
200For example, you can build everything in one step, and then install
201everything in a second step, by invoking the setup script twice:
Fred Drakea9a83e92001-03-01 18:37:52 +0000202
Greg Ward6002ffc2000-04-09 20:54:50 +0000203\begin{verbatim}
204python setup.py build
205python setup.py install
206\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000207
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000208If you do this, you will notice that running the \command{install}
Greg Ward14deaae2000-09-11 00:33:15 +0000209command first runs the \command{build} command, which---in this
210case---quickly notices that it has nothing to do, since everything in
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000211the \file{build} directory is up-to-date.
Greg Ward29576562000-03-18 15:11:50 +0000212
Greg Ward14deaae2000-09-11 00:33:15 +0000213You may not need this ability to break things down often if all you do
214is install modules downloaded off the 'net, but it's very handy for more
215advanced tasks. If you get into distributing your own Python modules
216and extensions, you'll run lots of individual Distutils commands on
217their own.
Greg Ward7c1e5f62000-03-10 01:56:58 +0000218
219
Greg Wardc392caa2000-04-11 02:00:26 +0000220\subsection{How building works}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000221\label{how-build-works}
Greg Ward7c1e5f62000-03-10 01:56:58 +0000222
Greg Wardc392caa2000-04-11 02:00:26 +0000223As implied above, the \command{build} command is responsible for putting
224the files to install into a \emph{build directory}. By default, this is
225\file{build} under the distribution root; if you're excessively
226concerned with speed, or want to keep the source tree pristine, you can
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000227change the build directory with the \longprogramopt{build-base} option.
228For example:
Fred Drakea9a83e92001-03-01 18:37:52 +0000229
Greg Wardc392caa2000-04-11 02:00:26 +0000230\begin{verbatim}
231python setup.py build --build-base=/tmp/pybuild/foo-1.0
232\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000233
Greg Wardc392caa2000-04-11 02:00:26 +0000234(Or you could do this permanently with a directive in your system or
235personal Distutils configuration file; see
Greg Warde78298a2000-04-28 17:12:24 +0000236section~\ref{config-files}.) Normally, this isn't necessary.
Greg Wardc392caa2000-04-11 02:00:26 +0000237
238The default layout for the build tree is as follows:
Fred Drakea9a83e92001-03-01 18:37:52 +0000239
Greg Wardc392caa2000-04-11 02:00:26 +0000240\begin{verbatim}
241--- build/ --- lib/
242or
243--- build/ --- lib.<plat>/
244 temp.<plat>/
245\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000246
Greg Wardc392caa2000-04-11 02:00:26 +0000247where \code{<plat>} expands to a brief description of the current
Greg Ward7ef2ba72000-10-22 01:40:08 +0000248OS/hardware platform and Python version. The first form, with just a
249\file{lib} directory, is used for ``pure module distributions''---that
250is, module distributions that include only pure Python modules. If a
Fred Drake42119e42001-03-03 19:47:24 +0000251module distribution contains any extensions (modules written in C/\Cpp),
Greg Ward7ef2ba72000-10-22 01:40:08 +0000252then the second form, with two \code{<plat>} directories, is used. In
253that case, the \file{temp.\filevar{plat}} directory holds temporary
254files generated by the compile/link process that don't actually get
255installed. In either case, the \file{lib} (or
Greg Wardc392caa2000-04-11 02:00:26 +0000256\file{lib.\filevar{plat}}) directory contains all Python modules (pure
257Python and extensions) that will be installed.
258
259In the future, more directories will be added to handle Python scripts,
260documentation, binary executables, and whatever else is needed to handle
Greg Wardd5faa7e2000-04-12 01:42:19 +0000261the job of installing Python modules and applications.
Greg Wardc392caa2000-04-11 02:00:26 +0000262
263
264\subsection{How installation works}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000265\label{how-install-works}
Greg Wardc392caa2000-04-11 02:00:26 +0000266
267After the \command{build} command runs (whether you run it explicitly,
268or the \command{install} command does it for you), the work of the
269\command{install} command is relatively simple: all it has to do is copy
270everything under \file{build/lib} (or \file{build/lib.\filevar{plat}})
271to your chosen installation directory.
272
273If you don't choose an installation directory---i.e., if you just run
274\code{setup.py install}---then the \command{install} command installs to
275the standard location for third-party Python modules. This location
276varies by platform and by how you built/installed Python itself. On
Fred Drake74f1a562001-09-25 15:12:41 +0000277\UNIX{} and Mac OS, it also depends on whether the module distribution
Greg Wardc392caa2000-04-11 02:00:26 +0000278being installed is pure Python or contains extensions (``non-pure''):
Greg Wardd5faa7e2000-04-12 01:42:19 +0000279\begin{tableiv}{l|l|l|c}{textrm}%
280 {Platform}{Standard installation location}{Default value}{Notes}
Fred Drakeeff9a872000-10-26 16:41:03 +0000281 \lineiv{\UNIX{} (pure)}
Fred Drake01df4532000-06-30 03:36:41 +0000282 {\filenq{\filevar{prefix}/lib/python2.0/site-packages}}
283 {\filenq{/usr/local/lib/python2.0/site-packages}}
Greg Ward502d2b42000-04-12 14:20:15 +0000284 {(1)}
Fred Drakeeff9a872000-10-26 16:41:03 +0000285 \lineiv{\UNIX{} (non-pure)}
Fred Drake01df4532000-06-30 03:36:41 +0000286 {\filenq{\filevar{exec-prefix}/lib/python2.0/site-packages}}
287 {\filenq{/usr/local/lib/python2.0/site-packages}}
Greg Ward502d2b42000-04-12 14:20:15 +0000288 {(1)}
Greg Wardd5faa7e2000-04-12 01:42:19 +0000289 \lineiv{Windows}
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000290 {\filenq{\filevar{prefix}}}
Greg Ward4756e5f2000-04-19 22:40:12 +0000291 {\filenq{C:\textbackslash{}Python}}
Greg Ward502d2b42000-04-12 14:20:15 +0000292 {(2)}
Fred Drake74f1a562001-09-25 15:12:41 +0000293 \lineiv{Mac OS (pure)}
Greg Ward7ef2ba72000-10-22 01:40:08 +0000294 {\filenq{\filevar{prefix}:Lib:site-packages}}
295 {\filenq{Python:Lib:site-packages}}
Greg Wardd5faa7e2000-04-12 01:42:19 +0000296 {}
Fred Drake74f1a562001-09-25 15:12:41 +0000297 \lineiv{Mac OS (non-pure)}
Greg Ward7ef2ba72000-10-22 01:40:08 +0000298 {\filenq{\filevar{prefix}:Lib:site-packages}}
299 {\filenq{Python:Lib:site-packages}}
Greg Wardd5faa7e2000-04-12 01:42:19 +0000300 {}
301\end{tableiv}
302
303\noindent Notes:
304\begin{description}
Greg Ward502d2b42000-04-12 14:20:15 +0000305\item[(1)] Most Linux distributions include Python as a standard part of
306 the system, so \filevar{prefix} and \filevar{exec-prefix} are usually
307 both \file{/usr} on Linux. If you build Python yourself on Linux (or
Fred Drakeeff9a872000-10-26 16:41:03 +0000308 any \UNIX-like system), the default \filevar{prefix} and
Greg Ward502d2b42000-04-12 14:20:15 +0000309 \filevar{exec-prefix} are \file{/usr/local}.
310\item[(2)] The default installation directory on Windows was
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000311 \file{C:\textbackslash{}Program Files\textbackslash{}Python} under
312 Python 1.6a1, 1.5.2, and earlier.
Greg Wardd5faa7e2000-04-12 01:42:19 +0000313\end{description}
314
Greg Wardc392caa2000-04-11 02:00:26 +0000315\filevar{prefix} and \filevar{exec-prefix} stand for the directories
316that Python is installed to, and where it finds its libraries at
Fred Drake74f1a562001-09-25 15:12:41 +0000317run-time. They are always the same under Windows and Mac OS, and very
Fred Drakeeff9a872000-10-26 16:41:03 +0000318often the same under \UNIX. You can find out what your Python
Greg Wardc392caa2000-04-11 02:00:26 +0000319installation uses for \filevar{prefix} and \filevar{exec-prefix} by
320running Python in interactive mode and typing a few simple commands.
Fred Drakeb2d10062001-07-06 22:46:52 +0000321Under \UNIX, just type \code{python} at the shell prompt. Under
322Windows, choose \menuselection{Start \sub Programs \sub Python
Fred Drake74f1a562001-09-25 15:12:41 +00003232.1 \sub Python (command line)}. Under Mac OS, \XXX{???}.
Fred Drake01df4532000-06-30 03:36:41 +0000324Once the interpreter is started, you type Python code at the
Fred Drakeb2d10062001-07-06 22:46:52 +0000325prompt. For example, on my Linux system, I type the three Python
326statements shown below, and get the output as shown, to find out my
327\filevar{prefix} and \filevar{exec-prefix}:
Fred Drake01df4532000-06-30 03:36:41 +0000328
Greg Wardc392caa2000-04-11 02:00:26 +0000329\begin{verbatim}
330Python 1.5.2 (#1, Apr 18 1999, 16:03:16) [GCC pgcc-2.91.60 19981201 (egcs-1.1.1 on linux2
331Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
332>>> import sys
333>>> sys.prefix
334'/usr'
335>>> sys.exec_prefix
336'/usr'
337\end{verbatim}
338
Greg Ward7ef2ba72000-10-22 01:40:08 +0000339If you don't want to install modules to the standard location, or if you
340don't have permission to write there, then you need to read about
341alternate installations in section~\ref{alt-install}. If you want to
342customize your installation directories more heavily, see
343section~\ref{custom-install} on custom installations.
Greg Wardc392caa2000-04-11 02:00:26 +0000344
345
346% This rather nasty macro is used to generate the tables that describe
347% each installation scheme. It's nasty because it takes two arguments
348% for each "slot" in an installation scheme, there will soon be more
349% than five of these slots, and TeX has a limit of 10 arguments to a
350% macro. Uh-oh.
351
Greg Ward29576562000-03-18 15:11:50 +0000352\newcommand{\installscheme}[8]
353 {\begin{tableiii}{lll}{textrm}
354 {Type of file}
355 {Installation Directory}
356 {Override option}
357 \lineiii{pure module distribution}
358 {\filevar{#1}\filenq{#2}}
Greg Warda021aca2000-04-19 22:34:11 +0000359 {\longprogramopt{install-purelib}}
Greg Ward29576562000-03-18 15:11:50 +0000360 \lineiii{non-pure module distribution}
361 {\filevar{#3}\filenq{#4}}
Greg Warda021aca2000-04-19 22:34:11 +0000362 {\longprogramopt{install-platlib}}
Greg Ward29576562000-03-18 15:11:50 +0000363 \lineiii{scripts}
364 {\filevar{#5}\filenq{#6}}
Greg Warda021aca2000-04-19 22:34:11 +0000365 {\longprogramopt{install-scripts}}
Greg Ward29576562000-03-18 15:11:50 +0000366 \lineiii{data}
367 {\filevar{#7}\filenq{#8}}
Greg Warda021aca2000-04-19 22:34:11 +0000368 {\longprogramopt{install-data}}
Greg Ward29576562000-03-18 15:11:50 +0000369 \end{tableiii}}
Greg Ward7c1e5f62000-03-10 01:56:58 +0000370
Greg Ward0bc59532000-09-30 21:06:40 +0000371
Greg Ward29576562000-03-18 15:11:50 +0000372\section{Alternate Installation}
Greg Warde78298a2000-04-28 17:12:24 +0000373\label{alt-install}
Greg Ward7c1e5f62000-03-10 01:56:58 +0000374
Greg Ward29576562000-03-18 15:11:50 +0000375Often, it is necessary or desirable to install modules to a location
376other than the standard location for third-party Python modules. For
Fred Drakeeff9a872000-10-26 16:41:03 +0000377example, on a \UNIX{} system you might not have permission to write to the
Greg Ward29576562000-03-18 15:11:50 +0000378standard third-party module directory. Or you might wish to try out a
379module before making it a standard part of your local Python
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000380installation. This is especially true when upgrading a distribution
Greg Ward29576562000-03-18 15:11:50 +0000381already present: you want to make sure your existing base of scripts
382still works with the new version before actually upgrading.
383
384The Distutils \command{install} command is designed to make installing
385module distributions to an alternate location simple and painless. The
386basic idea is that you supply a base directory for the installation, and
387the \command{install} command picks a set of directories (called an
388\emph{installation scheme}) under this base directory in which to
389install files. The details differ across platforms, so read whichever
Andrew M. Kuchling30537da2001-02-17 00:42:56 +0000390of the following sections applies to you.
Greg Ward29576562000-03-18 15:11:50 +0000391
392
Fred Drakeeff9a872000-10-26 16:41:03 +0000393\subsection{Alternate installation: \UNIX{} (the home scheme)}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000394\label{alt-install-prefix}
Greg Ward29576562000-03-18 15:11:50 +0000395
Fred Drakeeff9a872000-10-26 16:41:03 +0000396Under \UNIX, there are two ways to perform an alternate installation.
Greg Ward29576562000-03-18 15:11:50 +0000397The ``prefix scheme'' is similar to how alternate installation works
Fred Drake74f1a562001-09-25 15:12:41 +0000398under Windows and Mac OS, but is not necessarily the most useful way to
Greg Ward29576562000-03-18 15:11:50 +0000399maintain a personal Python library. Hence, we document the more
400convenient and commonly useful ``home scheme'' first.
401
Greg Wardc392caa2000-04-11 02:00:26 +0000402The idea behind the ``home scheme'' is that you build and maintain a
403personal stash of Python modules, probably under your home directory.
404Installing a new module distribution is as simple as
Fred Drakea9a83e92001-03-01 18:37:52 +0000405
Greg Ward29576562000-03-18 15:11:50 +0000406\begin{verbatim}
407python setup.py install --home=<dir>
408\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000409
Greg Warda021aca2000-04-19 22:34:11 +0000410where you can supply any directory you like for the \longprogramopt{home}
Greg Ward4756e5f2000-04-19 22:40:12 +0000411option. Lazy typists can just type a tilde (\code{\textasciitilde}); the
Greg Wardc392caa2000-04-11 02:00:26 +0000412\command{install} command will expand this to your home directory:
Fred Drakea9a83e92001-03-01 18:37:52 +0000413
Greg Wardc392caa2000-04-11 02:00:26 +0000414\begin{verbatim}
415python setup.py install --home=~
416\end{verbatim}
Greg Ward29576562000-03-18 15:11:50 +0000417
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000418The \longprogramopt{home} option defines the installation base
419directory. Files are installed to the following directories under the
420installation base as follows:
Greg Ward29576562000-03-18 15:11:50 +0000421\installscheme{home}{/lib/python}
422 {home}{/lib/python}
423 {home}{/bin}
424 {home}{/share}
425
Fred Drakeeff9a872000-10-26 16:41:03 +0000426\subsection{Alternate installation: \UNIX{} (the prefix scheme)}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000427\label{alt-install-home}
Greg Ward29576562000-03-18 15:11:50 +0000428
429The ``prefix scheme'' is useful when you wish to use one Python
430installation to perform the build/install (i.e., to run the setup
431script), but install modules into the third-party module directory of a
432different Python installation (or something that looks like a different
433Python installation). If this sounds a trifle unusual, it is---that's
434why the ``home scheme'' comes first. However, there are at least two
435known cases where the prefix scheme will be useful.
436
Greg Ward19c67f82000-06-24 01:33:16 +0000437First, consider that many Linux distributions put Python in \file{/usr},
Greg Ward29576562000-03-18 15:11:50 +0000438rather than the more traditional \file{/usr/local}. This is entirely
439appropriate, since in those cases Python is part of ``the system''
440rather than a local add-on. However, if you are installing Python
441modules from source, you probably want them to go in
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000442\file{/usr/local/lib/python2.\filevar{X}} rather than
443\file{/usr/lib/python2.\filevar{X}}. This can be done with
Fred Drakea9a83e92001-03-01 18:37:52 +0000444
Greg Ward29576562000-03-18 15:11:50 +0000445\begin{verbatim}
446/usr/bin/python setup.py install --prefix=/usr/local
447\end{verbatim}
448
449Another possibility is a network filesystem where the name used to write
450to a remote directory is different from the name used to read it: for
451example, the Python interpreter accessed as \file{/usr/local/bin/python}
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000452might search for modules in \file{/usr/local/lib/python2.\filevar{X}},
Greg Ward29576562000-03-18 15:11:50 +0000453but those modules would have to be installed to, say,
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000454\file{/mnt/\filevar{@server}/export/lib/python2.\filevar{X}}. This
Greg Ward29576562000-03-18 15:11:50 +0000455could be done with
Fred Drakea9a83e92001-03-01 18:37:52 +0000456
Greg Ward29576562000-03-18 15:11:50 +0000457\begin{verbatim}
458/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
459\end{verbatim}
460
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000461In either case, the \longprogramopt{prefix} option defines the
462installation base, and the \longprogramopt{exec-prefix} option defines
463the platform-specific installation base, which is used for
464platform-specific files. (Currently, this just means non-pure module
465distributions, but could be expanded to C libraries, binary executables,
466etc.) If \longprogramopt{exec-prefix} is not supplied, it defaults to
467\longprogramopt{prefix}. Files are installed as follows:
Greg Ward29576562000-03-18 15:11:50 +0000468
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000469\installscheme{prefix}{/lib/python2.\filevar{X}/site-packages}
470 {exec-prefix}{/lib/python2.\filevar{X}/site-packages}
Greg Ward29576562000-03-18 15:11:50 +0000471 {prefix}{/bin}
472 {prefix}{/share}
473
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000474There is no requirement that \longprogramopt{prefix} or
475\longprogramopt{exec-prefix} actually point to an alternate Python
476installation; if the directories listed above do not already exist, they
477are created at installation time.
Greg Ward29576562000-03-18 15:11:50 +0000478
479Incidentally, the real reason the prefix scheme is important is simply
Fred Drakeeff9a872000-10-26 16:41:03 +0000480that a standard \UNIX{} installation uses the prefix scheme, but with
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000481\longprogramopt{prefix} and \longprogramopt{exec-prefix} supplied by
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000482Python itself as \code{sys.prefix} and \code{sys.exec\_prefix}. Thus,
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000483you might think you'll never use the prefix scheme, but every time you
484run \code{python setup.py install} without any other options, you're
485using it.
Greg Ward29576562000-03-18 15:11:50 +0000486
487Note that installing extensions to an alternate Python installation has
488no effect on how those extensions are built: in particular, the Python
489header files (\file{Python.h} and friends) installed with the Python
490interpreter used to run the setup script will be used in compiling
491extensions. It is your responsibility to ensure that the interpreter
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000492used to run extensions installed in this way is compatible with the
Greg Wardc392caa2000-04-11 02:00:26 +0000493interpreter used to build them. The best way to do this is to ensure
494that the two interpreters are the same version of Python (possibly
495different builds, or possibly copies of the same build). (Of course, if
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000496your \longprogramopt{prefix} and \longprogramopt{exec-prefix} don't even
497point to an alternate Python installation, this is immaterial.)
Greg Ward29576562000-03-18 15:11:50 +0000498
499
500\subsection{Alternate installation: Windows}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000501\label{alt-install-windows}
Greg Ward29576562000-03-18 15:11:50 +0000502
503Since Windows has no conception of a user's home directory, and since
504the standard Python installation under Windows is simpler than that
Fred Drakeeff9a872000-10-26 16:41:03 +0000505under \UNIX, there's no point in having separate \longprogramopt{prefix}
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000506and \longprogramopt{home} options. Just use the \longprogramopt{prefix}
507option to specify a base directory, e.g.
Fred Drakea9a83e92001-03-01 18:37:52 +0000508
Greg Ward29576562000-03-18 15:11:50 +0000509\begin{verbatim}
Greg Ward8e14f052000-03-22 01:00:23 +0000510python setup.py install --prefix="\Temp\Python"
Greg Ward29576562000-03-18 15:11:50 +0000511\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000512
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000513to install modules to the
514\file{\textbackslash{}Temp\textbackslash{}Python} directory on the
515current drive.
Greg Ward29576562000-03-18 15:11:50 +0000516
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000517The installation base is defined by the \longprogramopt{prefix} option;
518the \longprogramopt{exec-prefix} option is not supported under Windows.
519Files are installed as follows:
Greg Ward29576562000-03-18 15:11:50 +0000520\installscheme{prefix}{}
521 {prefix}{}
Greg Ward4756e5f2000-04-19 22:40:12 +0000522 {prefix}{\textbackslash{}Scripts}
523 {prefix}{\textbackslash{}Data}
Greg Ward29576562000-03-18 15:11:50 +0000524
525
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000526\subsection{Alternate installation: Mac OS 9}
Greg Ward1ed49ee2000-09-13 00:00:58 +0000527\label{alt-install-macos}
Greg Ward29576562000-03-18 15:11:50 +0000528
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000529% XXX Mac OS X?
530
Fred Drake74f1a562001-09-25 15:12:41 +0000531Like Windows, Mac OS has no notion of home directories (or even of
Greg Ward29576562000-03-18 15:11:50 +0000532users), and a fairly simple standard Python installation. Thus, only a
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000533\longprogramopt{prefix} option is needed. It defines the installation
534base, and files are installed under it as follows:
Greg Ward29576562000-03-18 15:11:50 +0000535
Greg Ward8c562592000-09-13 00:12:37 +0000536\installscheme{prefix}{:Lib:site-packages}
537 {prefix}{:Lib:site-packages}
Greg Ward8e14f052000-03-22 01:00:23 +0000538 {prefix}{:Scripts}
539 {prefix}{:Data}
Greg Ward29576562000-03-18 15:11:50 +0000540
Greg Ward8c562592000-09-13 00:12:37 +0000541See section~\ref{platform-variations} for information on supplying
542command-line arguments to the setup script with MacPython.
Greg Ward29576562000-03-18 15:11:50 +0000543
544
545\section{Custom Installation}
Greg Warde78298a2000-04-28 17:12:24 +0000546\label{custom-install}
Greg Ward29576562000-03-18 15:11:50 +0000547
548Sometimes, the alternate installation schemes described in
Greg Warde78298a2000-04-28 17:12:24 +0000549section~\ref{alt-install} just don't do what you want. You might
Greg Ward29576562000-03-18 15:11:50 +0000550want to tweak just one or two directories while keeping everything under
551the same base directory, or you might want to completely redefine the
552installation scheme. In either case, you're creating a \emph{custom
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000553installation scheme}.
Greg Ward29576562000-03-18 15:11:50 +0000554
555You probably noticed the column of ``override options'' in the tables
556describing the alternate installation schemes above. Those options are
557how you define a custom installation scheme. These override options can
558be relative, absolute, or explicitly defined in terms of one of the
559installation base directories. (There are two installation base
560directories, and they are normally the same---they only differ when you
Fred Drakeeff9a872000-10-26 16:41:03 +0000561use the \UNIX{} ``prefix scheme'' and supply different
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000562\longprogramopt{prefix} and \longprogramopt{exec-prefix} options.)
Greg Ward29576562000-03-18 15:11:50 +0000563
564For example, say you're installing a module distribution to your home
Fred Drakeeff9a872000-10-26 16:41:03 +0000565directory under \UNIX---but you want scripts to go in
Greg Ward4eaa3bf2000-04-19 22:44:25 +0000566\file{\textasciitilde/scripts} rather than \file{\textasciitilde/bin}.
567As you might expect, you can override this directory with the
568\longprogramopt{install-scripts} option; in this case, it makes most
569sense to supply a relative path, which will be interpreted relative to
570the installation base directory (your home directory, in this case):
Fred Drakea9a83e92001-03-01 18:37:52 +0000571
Greg Ward29576562000-03-18 15:11:50 +0000572\begin{verbatim}
Greg Ward19c67f82000-06-24 01:33:16 +0000573python setup.py install --home=~ --install-scripts=scripts
Greg Ward29576562000-03-18 15:11:50 +0000574\end{verbatim}
575
Fred Drakeeff9a872000-10-26 16:41:03 +0000576Another \UNIX{} example: suppose your Python installation was built and
Greg Ward29576562000-03-18 15:11:50 +0000577installed with a prefix of \file{/usr/local/python}, so under a standard
578installation scripts will wind up in \file{/usr/local/python/bin}. If
579you want them in \file{/usr/local/bin} instead, you would supply this
Greg Warda021aca2000-04-19 22:34:11 +0000580absolute directory for the \longprogramopt{install-scripts} option:
Fred Drakea9a83e92001-03-01 18:37:52 +0000581
Greg Ward29576562000-03-18 15:11:50 +0000582\begin{verbatim}
583python setup.py install --install-scripts=/usr/local/bin
584\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000585
Greg Ward29576562000-03-18 15:11:50 +0000586(This performs an installation using the ``prefix scheme,'' where the
587prefix is whatever your Python interpreter was installed with---
588\file{/usr/local/python} in this case.)
589
590If you maintain Python on Windows, you might want third-party modules to
591live in a subdirectory of \filevar{prefix}, rather than right in
592\filevar{prefix} itself. This is almost as easy as customizing the
593script installation directory---you just have to remember that there are
594two types of modules to worry about, pure modules and non-pure modules
595(i.e., modules from a non-pure distribution). For example:
Fred Drakea9a83e92001-03-01 18:37:52 +0000596
Greg Ward29576562000-03-18 15:11:50 +0000597\begin{verbatim}
598python setup.py install --install-purelib=Site --install-platlib=Site
599\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000600
Andrew M. Kuchling3a7f4052002-11-15 02:52:44 +0000601The specified installation directories are relative to
602\filevar{prefix}. Of course, you also have to ensure that these
603directories are in Python's module search path, such as by putting a
604\file{.pth} file in \filevar{prefix}. See section~\ref{search-path}
605to find out how to modify Python's search path.
Greg Ward29576562000-03-18 15:11:50 +0000606
607If you want to define an entire installation scheme, you just have to
608supply all of the installation directory options. The recommended way
Greg Wardc392caa2000-04-11 02:00:26 +0000609to do this is to supply relative paths; for example, if you want to
610maintain all Python module-related files under \file{python} in your
611home directory, and you want a separate directory for each platform that
612you use your home directory from, you might define the following
Greg Ward29576562000-03-18 15:11:50 +0000613installation scheme:
Fred Drakea9a83e92001-03-01 18:37:52 +0000614
Greg Ward29576562000-03-18 15:11:50 +0000615\begin{verbatim}
Greg Wardc392caa2000-04-11 02:00:26 +0000616python setup.py install --home=~ \
Greg Ward29576562000-03-18 15:11:50 +0000617 --install-purelib=python/lib \
618 --install-platlib=python/lib.$PLAT \
619 --install-scripts=python/scripts
620 --install-data=python/data
621\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000622% $ % -- bow to font-lock
623
Greg Ward29576562000-03-18 15:11:50 +0000624or, equivalently,
Fred Drakea9a83e92001-03-01 18:37:52 +0000625
Greg Ward29576562000-03-18 15:11:50 +0000626\begin{verbatim}
627python setup.py install --home=~/python \
628 --install-purelib=lib \
Greg Ward19c67f82000-06-24 01:33:16 +0000629 --install-platlib='lib.$PLAT' \
Greg Ward29576562000-03-18 15:11:50 +0000630 --install-scripts=scripts
631 --install-data=data
632\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000633% $ % -- bow to font-lock
634
Greg Ward29576562000-03-18 15:11:50 +0000635\code{\$PLAT} is not (necessarily) an environment variable---it will be
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000636expanded by the Distutils as it parses your command line options, just
637as it does when parsing your configuration file(s).
Greg Ward29576562000-03-18 15:11:50 +0000638
639Obviously, specifying the entire installation scheme every time you
640install a new module distribution would be very tedious. Thus, you can
641put these options into your Distutils config file (see
Greg Warde78298a2000-04-28 17:12:24 +0000642section~\ref{config-files}):
Fred Drakea9a83e92001-03-01 18:37:52 +0000643
Greg Ward169f91b2000-03-10 01:57:51 +0000644\begin{verbatim}
645[install]
Greg Ward29576562000-03-18 15:11:50 +0000646install-base=$HOME
647install-purelib=python/lib
648install-platlib=python/lib.$PLAT
649install-scripts=python/scripts
650install-data=python/data
Greg Ward169f91b2000-03-10 01:57:51 +0000651\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000652
Greg Ward29576562000-03-18 15:11:50 +0000653or, equivalently,
Fred Drakea9a83e92001-03-01 18:37:52 +0000654
Greg Ward169f91b2000-03-10 01:57:51 +0000655\begin{verbatim}
656[install]
Greg Ward29576562000-03-18 15:11:50 +0000657install-base=$HOME/python
658install-purelib=lib
659install-platlib=lib.$PLAT
660install-scripts=scripts
661install-data=data
Greg Ward169f91b2000-03-10 01:57:51 +0000662\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000663
Greg Ward29576562000-03-18 15:11:50 +0000664Note that these two are \emph{not} equivalent if you supply a different
665installation base directory when you run the setup script. For example,
Fred Drakea9a83e92001-03-01 18:37:52 +0000666
Greg Ward7c1e5f62000-03-10 01:56:58 +0000667\begin{verbatim}
Greg Ward29576562000-03-18 15:11:50 +0000668python setup.py --install-base=/tmp
Greg Ward7c1e5f62000-03-10 01:56:58 +0000669\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000670
Greg Ward29576562000-03-18 15:11:50 +0000671would install pure modules to \filevar{/tmp/python/lib} in the first
672case, and to \filevar{/tmp/lib} in the second case. (For the second
673case, you probably want to supply an installation base of
674\file{/tmp/python}.)
Greg Ward169f91b2000-03-10 01:57:51 +0000675
Greg Ward29576562000-03-18 15:11:50 +0000676You probably noticed the use of \code{\$HOME} and \code{\$PLAT} in the
677sample configuration file input. These are Distutils configuration
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000678variables, which bear a strong resemblance to environment variables.
679In fact, you can use environment variables in config files on
680platforms that have such a notion but the Distutils additionally
681define a few extra variables that may not be in your environment, such
682as \code{\$PLAT}. (And of course, on systems that don't have
683environment variables, such as Mac OS (\XXX{true?}), the configuration
684variables supplied by the Distutils are the only ones you can use.)
685See section~\ref{config-files} for details.
Greg Ward7c1e5f62000-03-10 01:56:58 +0000686
Andrew M. Kuchling0cc8c372002-05-24 17:06:17 +0000687% XXX need some Windows and Mac OS examples---when would custom
688% installation schemes be needed on those platforms?
Greg Ward7c1e5f62000-03-10 01:56:58 +0000689
Greg Ward7c1e5f62000-03-10 01:56:58 +0000690
Andrew M. Kuchling3a7f4052002-11-15 02:52:44 +0000691% XXX I'm not sure where this section should go.
692\subsection{Modifying Python's Search Path}
693\label{search-path}
694
695When the Python interpreter executes an \keyword{import} statement, it
696searches for both Python code and extension modules along a search
697path. A default value for the path is configured into the Python
698binary when the interpreter is built. You can determine the path by
699importing the \module{sys} module and printing the value of
700\code{sys.path}.
701
702\begin{verbatim}
703$ python
704Python 2.2 (#11, Oct 3 2002, 13:31:27)
705[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
706Type ``help'', ``copyright'', ``credits'' or ``license'' for more information.
707>>> import sys
708>>> sys.path
709['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
710 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
711 '/usr/local/lib/python2.3/site-packages']
712>>>
713\end{verbatim}
714
715The null string in \code{sys.path} represents the current working
716directory.
717
718The expected convention for locally installed packages is to put them
719in the \file{.../site-packages/} directory, but you may want to
720install Python modules into some arbitrary directory. For example,
721your site may have a convention of keeping all software related to the
722web server under \file{/www}. Add-on Python modules might then belong
723in \file{/www/python}, and in order to import them, this directory
724must be added to \code{sys.path}. There are several different ways to
725add the directory.
726
727The most convenient way is to add a path configuration file to a
728directory that's already on Python's path, usually to the
729\file{.../site-packages/} directory. Path configuration files have an
730extension of \file{.pth}, and each line must contain a single path
731that will be added to \code{sys.path}. Paths can be absolute or
732relative, in which case they're relative to the directory containing
733the \file{.pth} file. Any directories added to the search path will
734be scanned in turn for \file{.pth} files. See
735\citetitle[http://www.python.org/dev/doc/devel/lib/module-site.html]{the
736documentation for the \module{site} module} for more information.
737
738A slightly less convenient way is to edit the \file{site.py} file in
739Python's standard library, and modify \code{sys.path}. \file{site.py}
740is automatically imported when the Python interpreter is executed,
741unless the \programopt{-S} switch is supplied to suppress this
742behaviour. So you could simply edit \file{site.py} and add two lines to it:
743
744\begin{verbatim}
745import sys
746sys.path.append('/www/python/')
747\end{verbatim}
748
749However, if you reinstall the same major version of Python (perhaps
750when upgrading from 2.2 to 2.2.2, for example) \file{site.py} will be
751overwritten by the stock version. You'd have to remember that it was
752modified and save a copy before doing the installation.
753
754There are two environment variables that can modify \code{sys.path}.
755\envvar{PYTHONHOME} sets an alternate value for the prefix of the
756Python installation. For example, if \envvar{PYTHONHOME} is set to
757\samp{/www/python}, the search path will be set to \code{['',
758'/www/python/lib/python2.2/', '/www/python/lib/python2.3/plat-linux2',
759...]}.
760
761The \envvar{PYTHONPATH} variable can be set to a list of paths that
762will be added to the beginning of \code{sys.path}. For example, if
763\envvar{PYTHONPATH} is set to \samp{/www/python:/opt/py}, the search
764path will begin with \code{['/www/python', '/opt/py']}. (Note that
765directories must exist in order to be added to \code{sys.path}; the
766\module{site} module removes paths that don't exist.)
767
768Finally, \code{sys.path} is just a regular Python list, so any Python
769application can modify it by adding or removing entries.
770
771
Greg Ward6002ffc2000-04-09 20:54:50 +0000772\section{Distutils Configuration Files}
Greg Warde78298a2000-04-28 17:12:24 +0000773\label{config-files}
Greg Ward7c1e5f62000-03-10 01:56:58 +0000774
Greg Ward7ef2ba72000-10-22 01:40:08 +0000775As mentioned above, you can use Distutils configuration files to record
776personal or site preferences for any Distutils options. That is, any
777option to any command can be stored in one of two or three (depending on
778your platform) configuration files, which will be consulted before the
779command-line is parsed. This means that configuration files will
780override default values, and the command-line will in turn override
781configuration files. Furthermore, if multiple configuration files
782apply, values from ``earlier'' files are overridden by ``later'' files.
783
784
785\subsection{Location and names of config files}
Fred Drake0bbaa512001-01-24 16:39:35 +0000786\label{config-filenames}
Greg Ward7ef2ba72000-10-22 01:40:08 +0000787
788The names and locations of the configuration files vary slightly across
Fred Drakeeff9a872000-10-26 16:41:03 +0000789platforms. On \UNIX, the three configuration files (in the order they
Greg Ward7ef2ba72000-10-22 01:40:08 +0000790are processed) are:
791\begin{tableiii}{l|l|c}{textrm}
792 {Type of file}{Location and filename}{Notes}
Andrew M. Kuchling22d35a72001-12-06 16:34:53 +0000793 \lineiii{system}{\filenq{\filevar{prefix}/lib/python\filevar{ver}/distutils/distutils.cfg}}{(1)}
Greg Ward7ef2ba72000-10-22 01:40:08 +0000794 \lineiii{personal}{\filenq{\$HOME/.pydistutils.cfg}}{(2)}
795 \lineiii{local}{\filenq{setup.cfg}}{(3)}
796\end{tableiii}
797
798On Windows, the configuration files are:
799\begin{tableiii}{l|l|c}{textrm}
800 {Type of file}{Location and filename}{Notes}
Andrew M. Kuchling22d35a72001-12-06 16:34:53 +0000801 \lineiii{system}{\filenq{\filevar{prefix}\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}distutils.cfg}}{(4)}
Fred Drake8612a432002-10-31 20:46:20 +0000802 \lineiii{personal}{\filenq{\%HOME\%\textbackslash{}pydistutils.cfg}}{(5)}
Greg Ward7ef2ba72000-10-22 01:40:08 +0000803 \lineiii{local}{\filenq{setup.cfg}}{(3)}
804\end{tableiii}
805
Fred Drake74f1a562001-09-25 15:12:41 +0000806And on Mac OS, they are:
Greg Ward7ef2ba72000-10-22 01:40:08 +0000807\begin{tableiii}{l|l|c}{textrm}
808 {Type of file}{Location and filename}{Notes}
Andrew M. Kuchling22d35a72001-12-06 16:34:53 +0000809 \lineiii{system}{\filenq{\filevar{prefix}:Lib:distutils:distutils.cfg}}{(6)}
Greg Ward7ef2ba72000-10-22 01:40:08 +0000810 \lineiii{personal}{N/A}{}
811 \lineiii{local}{\filenq{setup.cfg}}{(3)}
812\end{tableiii}
813
814\noindent Notes:
815\begin{description}
816\item[(1)] Strictly speaking, the system-wide configuration file lives
817 in the directory where the Distutils are installed; under Python 1.6
Fred Drakeeff9a872000-10-26 16:41:03 +0000818 and later on \UNIX, this is as shown. For Python 1.5.2, the Distutils
Greg Ward7ef2ba72000-10-22 01:40:08 +0000819 will normally be installed to
820 \file{\filevar{prefix}/lib/site-packages/python1.5/distutils},
821 so the system configuration file should be put there under Python
822 1.5.2.
Fred Drakeeff9a872000-10-26 16:41:03 +0000823\item[(2)] On \UNIX, if the \envvar{HOME} environment variable is not
Greg Ward7ef2ba72000-10-22 01:40:08 +0000824 defined, the user's home directory will be determined with the
Fred Drake8612a432002-10-31 20:46:20 +0000825 \function{getpwuid()} function from the standard
826 \ulink{\module{pwd}}{../lib/module-pwd.html} module.
Greg Ward7ef2ba72000-10-22 01:40:08 +0000827\item[(3)] I.e., in the current directory (usually the location of the
828 setup script).
829\item[(4)] (See also note (1).) Under Python 1.6 and later, Python's
830 default ``installation prefix'' is \file{C:\textbackslash{}Python}, so
831 the system configuration file is normally
Andrew M. Kuchling22d35a72001-12-06 16:34:53 +0000832 \file{C:\textbackslash{}Python\textbackslash{}Lib\textbackslash{}distutils\textbackslash{}distutils.cfg}.
Greg Ward7ef2ba72000-10-22 01:40:08 +0000833 Under Python 1.5.2, the default prefix was
834 \file{C:\textbackslash{}Program~Files\textbackslash{}Python}, and the
835 Distutils were not part of the standard library---so the system
836 configuration file would be
Andrew M. Kuchling22d35a72001-12-06 16:34:53 +0000837 \file{C:\textbackslash{}Program~Files\textbackslash{}Python\textbackslash{}distutils\textbackslash{}distutils.cfg}
Greg Ward7ef2ba72000-10-22 01:40:08 +0000838 in a standard Python 1.5.2 installation under Windows.
839\item[(5)] On Windows, if the \envvar{HOME} environment variable is not
840 defined, no personal configuration file will be found or used. (In
841 other words, the Distutils make no attempt to guess your home
842 directory on Windows.)
843\item[(6)] (See also notes (1) and (4).) The default installation
844 prefix is just \file{Python:}, so under Python 1.6 and later this is
Andrew M. Kuchling0cc8c372002-05-24 17:06:17 +0000845 normally\file{Python:Lib:distutils:distutils.cfg}.
Greg Ward7ef2ba72000-10-22 01:40:08 +0000846\end{description}
847
848
849\subsection{Syntax of config files}
Fred Drake0bbaa512001-01-24 16:39:35 +0000850\label{config-syntax}
Greg Ward7ef2ba72000-10-22 01:40:08 +0000851
852The Distutils configuration files all have the same syntax. The config
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000853files are grouped into sections. There is one section for each Distutils
Greg Ward7ef2ba72000-10-22 01:40:08 +0000854command, plus a \code{global} section for global options that affect
855every command. Each section consists of one option per line, specified
Andrew M. Kuchling3b98dc12002-05-07 21:02:35 +0000856as \code{option=value}.
Greg Ward7ef2ba72000-10-22 01:40:08 +0000857
858For example, the following is a complete config file that just forces
859all commands to run quietly by default:
Fred Drakea9a83e92001-03-01 18:37:52 +0000860
Greg Ward7ef2ba72000-10-22 01:40:08 +0000861\begin{verbatim}
862[global]
863verbose=0
864\end{verbatim}
865
866If this is installed as the system config file, it will affect all
867processing of any Python module distribution by any user on the current
868system. If it is installed as your personal config file (on systems
869that support them), it will affect only module distributions processed
870by you. And if it is used as the \file{setup.cfg} for a particular
871module distribution, it affects only that distribution.
872
873You could override the default ``build base'' directory and make the
874\command{build*} commands always forcibly rebuild all files with the
875following:
Fred Drakea9a83e92001-03-01 18:37:52 +0000876
Greg Ward7ef2ba72000-10-22 01:40:08 +0000877\begin{verbatim}
878[build]
879build-base=blib
880force=1
881\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000882
Greg Ward7ef2ba72000-10-22 01:40:08 +0000883which corresponds to the command-line arguments
Fred Drakea9a83e92001-03-01 18:37:52 +0000884
Greg Ward7ef2ba72000-10-22 01:40:08 +0000885\begin{verbatim}
886python setup.py build --build-base=blib --force
887\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000888
Greg Ward7ef2ba72000-10-22 01:40:08 +0000889except that including the \command{build} command on the command-line
890means that command will be run. Including a particular command in
891config files has no such implication; it only means that if the command
892is run, the options in the config file will apply. (Or if other
893commands that derive values from it are run, they will use the values in
894the config file.)
895
896You can find out the complete list of options for any command using the
897\longprogramopt{help} option, e.g.:
Fred Drakea9a83e92001-03-01 18:37:52 +0000898
Greg Ward7ef2ba72000-10-22 01:40:08 +0000899\begin{verbatim}
900python setup.py build --help
901\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000902
Greg Ward7ef2ba72000-10-22 01:40:08 +0000903and you can find out the complete list of global options by using
904\longprogramopt{help} without a command:
Fred Drakea9a83e92001-03-01 18:37:52 +0000905
Greg Ward7ef2ba72000-10-22 01:40:08 +0000906\begin{verbatim}
907python setup.py --help
908\end{verbatim}
Fred Drakea9a83e92001-03-01 18:37:52 +0000909
Greg Ward7ef2ba72000-10-22 01:40:08 +0000910See also the ``Reference'' section of the ``Distributing Python
911Modules'' manual.
912
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +0000913\section{Building Extensions: Tips and Tricks}
914\label{building-ext}
915
916Whenever possible, the Distutils try to use the configuration
917information made available by the Python interpreter used to run the
918\file{setup.py} script. For example, the same compiler and linker
919flags used to compile Python will also be used for compiling
920extensions. Usually this will work well, but in complicated
921situations this might be inappropriate. This section discusses how to
922override the usual Distutils behaviour.
923
924\subsection{Tweaking compiler/linker flags}
925\label{tweak-flags}
926
927Compiling a Python extension written in C or \Cpp will sometimes
928require specifying custom flags for the compiler and linker in order
929to use a particular library or produce a special kind of object code.
930This is especially true if the extension hasn't been tested on your
931platform, or if you're trying to cross-compile Python.
932
933In the most general case, the extension author might have foreseen
934that compiling the extensions would be complicated, and provided a
935\file{Setup} file for you to edit. This will likely only be done if
936the module distribution contains many separate extension modules, or
937if they often require elaborate sets of compiler flags in order to work.
938
939A \file{Setup} file, if present, is parsed in order to get a list of
940extensions to build. Each line in a \file{Setup} describes a single
941module. Lines have the following structure:
942
Fred Drake8612a432002-10-31 20:46:20 +0000943\begin{alltt}
944\var{module} ... [\var{sourcefile} ...] [\var{cpparg} ...] [\var{library} ...]
945\end{alltt}
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +0000946
947Let's examine each of the fields in turn.
948
949\begin{itemize}
950
951\item \var{module} is the name of the extension module to be built,
Fred Drake8612a432002-10-31 20:46:20 +0000952 and should be a valid Python identifier. You can't just change
953 this in order to rename a module (edits to the source code would
954 also be needed), so this should be left alone.
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +0000955
956\item \var{sourcefile} is anything that's likely to be a source code
Fred Drake8612a432002-10-31 20:46:20 +0000957 file, at least judging by the filename. Filenames ending in
958 \file{.c} are assumed to be written in C, filenames ending in
959 \file{.C}, \file{.cc}, and \file{.c++} are assumed to be
960 \Cpp, and filenames ending in \file{.m} or \file{.mm} are
961 assumed to be in Objective C.
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +0000962
963\item \var{cpparg} is an argument for the C preprocessor,
Fred Drake8612a432002-10-31 20:46:20 +0000964 and is anything starting with \programopt{-I}, \programopt{-D},
965 \programopt{-U} or \programopt{-C}.
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +0000966
Fred Drake8612a432002-10-31 20:46:20 +0000967\item \var{library} is anything ending in \file{.a} or beginning with
968 \programopt{-l} or \programopt{-L}.
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +0000969\end{itemize}
970
971If a particular platform requires a special library on your platform,
972you can add it by editing the \file{Setup} file and running
973\code{python setup.py build}. For example, if the module defined by the line
974
975\begin{verbatim}
976foo foomodule.c
977\end{verbatim}
978
979must be linked with the math library \file{libm.a} on your platform,
Fred Drake8612a432002-10-31 20:46:20 +0000980simply add \programopt{-lm} to the line:
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +0000981
982\begin{verbatim}
983foo foomodule.c -lm
984\end{verbatim}
985
986Arbitrary switches intended for the compiler or the linker can be
Fred Drake8612a432002-10-31 20:46:20 +0000987supplied with the \programopt{-Xcompiler} \var{arg} and
988\programopt{-Xlinker} \var{arg} options:
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +0000989
990\begin{verbatim}
991foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
992\end{verbatim}
993
Fred Drake8612a432002-10-31 20:46:20 +0000994The next option after \programopt{-Xcompiler} and
995\programopt{-Xlinker} will be appended to the proper command line, so
996in the above example the compiler will be passed the \programopt{-o32}
997option, and the linker will be passed \programopt{-shared}. If a
998compiler option requires an argument, you'll have to supply multiple
999\programopt{-Xcompiler} options; for example, to pass \code{-x c++} the
1000\file{Setup} file would have to contain
1001\code{-Xcompiler -x -Xcompiler c++}.
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001002
1003Compiler flags can also be supplied through setting the
1004\envvar{CFLAGS} environment variable. If set, the contents of
1005\envvar{CFLAGS} will be added to the compiler flags specified in the
1006\file{Setup} file.
1007
1008
1009\subsection{Using non-Microsoft compilers on Windows \label{non-ms-compilers}}
1010\sectionauthor{Rene Liebscher}{R.Liebscher@gmx.de}
1011
1012\subsubsection{Borland C++}
1013
1014This subsection describes the necessary steps to use Distutils with the
1015Borland \Cpp{} compiler version 5.5.
1016%Should we mention that users have to create cfg-files for the compiler?
1017%see also http://community.borland.com/article/0,1410,21205,00.html
1018
1019First you have to know that Borland's object file format (OMF) is
1020different from the format used by the Python version you can download
1021from the Python or ActiveState Web site. (Python is built with
1022Microsoft Visual \Cpp, which uses COFF as the object file format.)
1023For this reason you have to convert Python's library
1024\file{python20.lib} into the Borland format. You can do this as
1025follows:
1026
1027\begin{verbatim}
1028coff2omf python20.lib python20_bcpp.lib
1029\end{verbatim}
1030
1031The \file{coff2omf} program comes with the Borland compiler. The file
1032\file{python20.lib} is in the \file{Libs} directory of your Python
1033installation. If your extension uses other libraries (zlib,...) you
1034have to convert them too.
1035
1036The converted files have to reside in the same directories as the
1037normal libraries.
1038
1039How does Distutils manage to use these libraries with their changed
1040names? If the extension needs a library (eg. \file{foo}) Distutils
1041checks first if it finds a library with suffix \file{_bcpp}
1042(eg. \file{foo_bcpp.lib}) and then uses this library. In the case it
1043doesn't find such a special library it uses the default name
1044(\file{foo.lib}.)\footnote{This also means you could replace all
1045existing COFF-libraries with OMF-libraries of the same name.}
1046
1047To let Distutils compile your extension with Borland \Cpp{} you now have
1048to type:
1049
1050\begin{verbatim}
1051python setup.py build --compiler=bcpp
1052\end{verbatim}
1053
1054If you want to use the Borland \Cpp{} compiler as the default, you
1055could specify this in your personal or system-wide configuration file
1056for Distutils (see section~\ref{config-files}.)
1057
1058\begin{seealso}
1059 \seetitle[http://www.borland.com/bcppbuilder/freecompiler/]
1060 {\Cpp{}Builder Compiler}
1061 {Information about the free \Cpp{} compiler from Borland,
1062 including links to the download pages.}
1063
Fred Drakeddc369a2002-10-18 16:33:30 +00001064 \seetitle[http://www.cyberus.ca/\~{}g_will/pyExtenDL.shtml]
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001065 {Creating Python Extensions Using Borland's Free Compiler}
1066 {Document describing how to use Borland's free command-line C++
1067 compiler to build Python.}
1068\end{seealso}
1069
1070
Andrew M. Kuchling572aae32002-11-06 14:34:50 +00001071\subsubsection{GNU C / Cygwin / MinGW}
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001072
1073This section describes the necessary steps to use Distutils with the
Andrew M. Kuchling572aae32002-11-06 14:34:50 +00001074GNU C/\Cpp{} compilers in their Cygwin and MinGW
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001075distributions.\footnote{Check
1076\url{http://sources.redhat.com/cygwin/} and
1077\url{http://www.mingw.org/} for more information}
Andrew M. Kuchling572aae32002-11-06 14:34:50 +00001078For a Python interpreter that was built with Cygwin, everything should
1079work without any of these following steps.
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001080
Andrew M. Kuchling572aae32002-11-06 14:34:50 +00001081These compilers require some special libraries.
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001082This task is more complex than for Borland's \Cpp, because there is no
1083program to convert the library.
1084% I don't understand what the next line means. --amk
1085% (inclusive the references on data structures.)
1086
1087First you have to create a list of symbols which the Python DLL exports.
1088(You can find a good program for this task at
1089\url{http://starship.python.net/crew/kernr/mingw32/Notes.html}, see at
1090PExports 0.42h there.)
1091
1092\begin{verbatim}
1093pexports python20.dll >python20.def
1094\end{verbatim}
1095
1096Then you can create from these information an import library for gcc.
1097
1098\begin{verbatim}
1099dlltool --dllname python20.dll --def python20.def --output-lib libpython20.a
1100\end{verbatim}
1101
1102The resulting library has to be placed in the same directory as
1103\file{python20.lib}. (Should be the \file{libs} directory under your
1104Python installation directory.)
1105
1106If your extension uses other libraries (zlib,...) you might
1107have to convert them too.
1108The converted files have to reside in the same directories as the normal
1109libraries do.
1110
1111To let Distutils compile your extension with Cygwin you now have to type
1112
1113\begin{verbatim}
1114python setup.py build --compiler=cygwin
1115\end{verbatim}
1116
1117and for Cygwin in no-cygwin mode\footnote{Then you have no
1118\POSIX{} emulation available, but you also don't need
Andrew M. Kuchling572aae32002-11-06 14:34:50 +00001119\file{cygwin1.dll}.} or for MinGW type:
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001120
1121\begin{verbatim}
1122python setup.py build --compiler=mingw32
1123\end{verbatim}
1124
1125If you want to use any of these options/compilers as default, you should
1126consider to write it in your personal or system-wide configuration file
1127for Distutils (see section~\ref{config-files}.)
1128
1129\begin{seealso}
1130 \seetitle[http://www.zope.org/Members/als/tips/win32_mingw_modules]
Andrew M. Kuchling572aae32002-11-06 14:34:50 +00001131 {Building Python modules on MS Windows platform with MinGW}
1132 {Information about building the required libraries for the MinGW
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001133 environment.}
1134
1135 \seeurl{http://pyopengl.sourceforge.net/ftp/win32-stuff/}
Andrew M. Kuchling572aae32002-11-06 14:34:50 +00001136 {Converted import libraries in Cygwin/MinGW and Borland format,
Andrew M. Kuchling1624bc02002-05-07 21:03:45 +00001137 and a script to create the registry entries needed for Distutils
1138 to locate the built Python.}
1139\end{seealso}
1140
1141
1142
Greg Ward7c1e5f62000-03-10 01:56:58 +00001143\end{document}