Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 1 | \documentclass{howto} |
| 2 | \usepackage{ltxmarkup} |
| 3 | \usepackage{times} |
Greg Ward | 7593eb3 | 2000-04-09 03:59:15 +0000 | [diff] [blame] | 4 | \usepackage{distutils} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 5 | |
| 6 | \title{Installing Python Modules} |
| 7 | |
| 8 | % The audience for this document includes people who don't know anything |
| 9 | % about Python and aren't about to learn the language just in order to |
| 10 | % install and maintain it for their users, i.e. system administrators. |
| 11 | % Thus, I have to be sure to explain the basics at some point: |
| 12 | % sys.path and PYTHONPATH at least. Should probably give pointers to |
| 13 | % other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. |
| 14 | % |
| 15 | % Also, I need to take into account that most modules out there don't |
| 16 | % (yet) use Distutils: briefly explain the old Makefile.pre.in |
| 17 | % convention (maybe move material from the E&E manual to here?), and |
| 18 | % explain where to copy .py and .so files manually if the distribution |
| 19 | % doesn't provide a mechanism for doing so. |
| 20 | % |
| 21 | % Finally, it might be useful to include all the material from my "Care |
| 22 | % and Feeding of a Python Installation" talk in here somewhere. Yow! |
| 23 | |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 24 | \author{Greg Ward} |
| 25 | \authoraddress{E-mail: \email{gward@python.net}} |
| 26 | |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 27 | |
| 28 | \begin{document} |
| 29 | |
| 30 | \maketitle |
| 31 | |
| 32 | %\begin{abstract} |
| 33 | %\noindent |
| 34 | %Abstract this! |
| 35 | %\end{abstract} |
| 36 | |
| 37 | \tableofcontents |
| 38 | |
| 39 | \section{Introduction} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 40 | \label{intro} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 41 | |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 42 | Although Python's extensive standard library covers many programming |
| 43 | needs, there often comes a time when you need to add some new |
| 44 | functionality to your Python installation in the form of third-party |
| 45 | modules. This might be necessary to support your own programming, or to |
| 46 | support an application that you want to use and that happens to be |
| 47 | written in Python. |
| 48 | |
| 49 | In the past, there has been little support for adding third-party |
| 50 | modules to an existing Python installation. With the introduction of |
Fred Drake | 01df453 | 2000-06-30 03:36:41 +0000 | [diff] [blame] | 51 | the Python Distribution Utilities (Distutils for short) in Python 2.0, |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 52 | this is starting to change. Not everything will change overnight, |
| 53 | though, so while this document concentrates on installing module |
| 54 | distributions that use the Distutils, we will also spend some time |
| 55 | dealing with the old ways. |
| 56 | |
| 57 | This document is aimed primarily at the people who need to install |
| 58 | third-party Python modules: end-users and system administrators who just |
| 59 | need to get some Python application running, and existing Python |
| 60 | programmers who want to add some new goodies to their toolbox. You |
| 61 | don't need to know Python to read this document; there will be some |
| 62 | brief forays into using Python's interactive mode to explore your |
| 63 | installation, but that's it. If you're looking for information on how |
| 64 | to distribute your own Python modules so that others may use them, see |
Fred Drake | 01df453 | 2000-06-30 03:36:41 +0000 | [diff] [blame] | 65 | the \citetitle[../dist/dist.html]{Distributing Python Modules} manual. |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 66 | |
| 67 | |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 68 | \subsection{Best case: trivial installation} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 69 | \label{trivial-inst} |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 70 | |
| 71 | In the best case, someone will have prepared a special version of the |
| 72 | module distribution you want to install that is targeted specifically at |
| 73 | your platform and is installed just like any other software on your |
| 74 | platform. For example, the module developer might make an executable |
| 75 | installer available for Windows users, an RPM package for users of |
| 76 | RPM-based Linux systems (Red Hat, SuSE, Mandrake, and many others), a |
| 77 | Debian package for users of Debian-based Linux systems (Debian proper, |
| 78 | Caldera, Corel, etc.), and so forth. |
| 79 | |
| 80 | In that case, you would download the installer appropriate to your |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 81 | platform and do the obvious thing with it: run it if it's an executable |
| 82 | installer, \code{rpm --install} it if it's an RPM, etc. You don't need |
| 83 | to run Python or a setup script, you don't need to compile |
| 84 | anything---you might not even need to read any instructions (although |
| 85 | it's always a good idea to do so anyways). |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 86 | |
| 87 | Of course, things will not always be that easy. You might be interested |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 88 | in a module distribution that doesn't have an easy-to-use installer for |
| 89 | your platform. In that case, you'll have to start with the source |
| 90 | distribution released by the module's author/maintainer. Installing |
| 91 | from a source distribution is not too hard, as long as the modules are |
| 92 | packaged in the standard way. The bulk of this document is about |
| 93 | building and installing modules from standard source distributions. |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 94 | |
| 95 | |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 96 | \subsection{The new standard: Distutils} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 97 | \label{new-standard} |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 98 | |
| 99 | If you download a module source distribution, you can tell pretty |
Greg Ward | 19c67f8 | 2000-06-24 01:33:16 +0000 | [diff] [blame] | 100 | quickly if it was packaged and distributed in the standard way, i.e. |
| 101 | using the Distutils. First, the distribution's name and version number |
| 102 | will be featured prominently in the name of the downloaded archive, e.g. |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 103 | \file{foo-1.0.tar.gz} or \file{widget-0.9.7.zip}. Next, the archive |
| 104 | will unpack into a similarly-named directory: \file{foo-1.0} or |
| 105 | \file{widget-0.9.7}. Additionally, the distribution will contain a |
| 106 | setup script \file{setup.py}, and a \file{README.txt} (or possibly |
| 107 | \file{README}), which should explain that building and installing the |
| 108 | module distribution is a simple matter of running |
| 109 | \begin{verbatim} |
| 110 | python setup.py install |
| 111 | \end{verbatim} |
| 112 | |
| 113 | If all these things are true, then you already know how to build and |
| 114 | install the modules you've just downloaded: run the command above. |
| 115 | Unless you need to install things in a non-standard way or customize the |
| 116 | build process, you don't really need this manual. Or rather, the above |
| 117 | command is everything you need to get out of this manual. |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 118 | |
| 119 | |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 120 | \subsection{The old way: no standards} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 121 | \label{old-way} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 122 | |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 123 | Before the Distutils, there was no infrastructure to support installing |
| 124 | third-party modules in a consistent, standardized way. Thus, it's not |
| 125 | really possible to write a general manual for installing Python modules |
| 126 | that don't use the Distutils; the only truly general statement that can |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 127 | be made is, ``Read the module's own installation instructions.'' |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 128 | |
Greg Ward | 19c67f8 | 2000-06-24 01:33:16 +0000 | [diff] [blame] | 129 | However, if such instructions exist at all, they are often woefully |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 130 | inadequate and targeted at experienced Python developers. Such users |
| 131 | are already familiar with how the Python library is laid out on their |
| 132 | platform, and know where to copy various files in order for Python to |
| 133 | find them. This document makes no such assumptions, and explains how |
| 134 | the Python library is laid out on three major platforms (Unix, Windows, |
| 135 | and Mac~OS), so that you can understand what happens when the Distutils |
| 136 | do their job \emph{and} know how to install modules manually when the |
| 137 | module author fails to provide a setup script. |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 138 | |
| 139 | Additionally, while there has not previously been a standard |
| 140 | installation mechanism, Python has had some standard machinery for |
| 141 | building extensions on Unix since Python \XXX{version?}. This machinery |
| 142 | (the \file{Makefile.pre.in} file) is superseded by the Distutils, but it |
| 143 | will no doubt live on in older module distributions for a while. This |
| 144 | \file{Makefile.pre.in} mechanism is documented in the ``Extending \& |
| 145 | Embedding Python'' manual, but that manual is aimed at module |
| 146 | developers---hence, we include documentation for builders/installers |
| 147 | here. |
| 148 | |
| 149 | All of the pre-Distutils material is tucked away in |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 150 | section~\ref{pre-distutils}. |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 151 | |
| 152 | |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 153 | \section{Standard Build and Install} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 154 | \label{normal-install} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 155 | |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 156 | As described in section~\ref{new-standard}, building and installing |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 157 | a module distribution using the Distutils is usually one simple command: |
| 158 | \begin{verbatim} |
| 159 | python setup.py install |
| 160 | \end{verbatim} |
| 161 | On Unix, you'd run this command from a shell prompt; on Windows, you |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 162 | have to open a command prompt window and do it there; on Mac~OS ... |
| 163 | \XXX{what the heck do you do on Mac~OS?}. |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 164 | |
| 165 | |
| 166 | \subsection{Platform variations} |
| 167 | |
| 168 | You should always run the setup command from the distribution root |
| 169 | directory, i.e. the top-level subdirectory that the module source |
| 170 | distribution unpacks into. For example, if you've just downloaded a |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 171 | module source distribution \file{foo-1.0.tar.gz} onto a Unix system, the |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 172 | normal thing to do is: |
| 173 | \begin{verbatim} |
| 174 | gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0 |
| 175 | cd foo-1.0 |
| 176 | python setup.py install |
| 177 | \end{verbatim} |
| 178 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 179 | On Windows, you'd probably unpack the archive before opening the command |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 180 | prompt. If you downloaded the archive file to |
| 181 | \file{C:\textbackslash{}Temp}, then it probably unpacked (depending on |
| 182 | your software) into |
| 183 | \file{C:\textbackslash{}Temp\textbackslash{}foo-1.0}; from the command |
| 184 | prompt window, you would then run |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 185 | \begin{verbatim} |
| 186 | cd c:\temp\foo-1.0 |
| 187 | python setup.py install |
| 188 | \end{verbatim} |
| 189 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 190 | On Mac~OS, ... \XXX{again, how do you run Python scripts on Mac~OS?} |
| 191 | |
| 192 | \XXX{arg, my lovely ``bslash'' macro doesn't work in non-tt fonts! help |
| 193 | me \LaTeX, you're my only hope...} |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 194 | |
| 195 | |
| 196 | \subsection{Splitting the job up} |
| 197 | |
| 198 | Running \code{setup.py install} builds and installs all modules in one |
| 199 | fell swoop. If you prefer to work incrementally---especially useful if |
| 200 | you want to customize the build process, or if things are going |
Greg Ward | 3e7b133 | 2000-05-30 03:00:43 +0000 | [diff] [blame] | 201 | wrong---you can use the setup script to do one thing at a time. This is |
| 202 | particularly helpful when the build and install will be done by |
| 203 | different users---e.g., you might want to build a module distribution |
| 204 | and hand it off to a system administrator for installation (or do it |
| 205 | yourself, with super-user privileges). |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 206 | |
| 207 | For example, you can build everything in one step, and then install |
| 208 | everything in a second step, by invoking the setup script twice: |
| 209 | \begin{verbatim} |
| 210 | python setup.py build |
| 211 | python setup.py install |
| 212 | \end{verbatim} |
| 213 | (If you do this, you will notice that running the \command{install} |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 214 | command first runs the \command{build} command, which quickly notices |
| 215 | that it has nothing to do, since everything in the \file{build} |
| 216 | directory is up-to-date.) |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 217 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 218 | \XXX{concrete reason for splitting things up?} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 219 | |
| 220 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 221 | \subsection{How building works} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 222 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 223 | As implied above, the \command{build} command is responsible for putting |
| 224 | the files to install into a \emph{build directory}. By default, this is |
| 225 | \file{build} under the distribution root; if you're excessively |
| 226 | concerned with speed, or want to keep the source tree pristine, you can |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 227 | change the build directory with the \longprogramopt{build-base} option. |
| 228 | For example: |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 229 | \begin{verbatim} |
| 230 | python setup.py build --build-base=/tmp/pybuild/foo-1.0 |
| 231 | \end{verbatim} |
| 232 | (Or you could do this permanently with a directive in your system or |
| 233 | personal Distutils configuration file; see |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 234 | section~\ref{config-files}.) Normally, this isn't necessary. |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 235 | |
| 236 | The default layout for the build tree is as follows: |
| 237 | \begin{verbatim} |
| 238 | --- build/ --- lib/ |
| 239 | or |
| 240 | --- build/ --- lib.<plat>/ |
| 241 | temp.<plat>/ |
| 242 | \end{verbatim} |
| 243 | where \code{<plat>} expands to a brief description of the current |
| 244 | OS/hardware platform. The first form, with just a \file{lib} directory, |
| 245 | is used for ``pure module distributions''---that is, module |
| 246 | distributions that include only pure Python modules. If a module |
| 247 | distribution contains any extensions (modules written in C/C++, or Java |
| 248 | for JPython), then the second form, with two \code{<plat>} directories, |
| 249 | is used. In that case, the \file{temp.\filevar{plat}} directory holds |
| 250 | temporary files generated by the compile/link process that don't |
| 251 | actually get installed. In either case, the \file{lib} (or |
| 252 | \file{lib.\filevar{plat}}) directory contains all Python modules (pure |
| 253 | Python and extensions) that will be installed. |
| 254 | |
| 255 | In the future, more directories will be added to handle Python scripts, |
| 256 | documentation, binary executables, and whatever else is needed to handle |
Greg Ward | d5faa7e | 2000-04-12 01:42:19 +0000 | [diff] [blame] | 257 | the job of installing Python modules and applications. |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 258 | |
| 259 | |
| 260 | \subsection{How installation works} |
| 261 | |
| 262 | After the \command{build} command runs (whether you run it explicitly, |
| 263 | or the \command{install} command does it for you), the work of the |
| 264 | \command{install} command is relatively simple: all it has to do is copy |
| 265 | everything under \file{build/lib} (or \file{build/lib.\filevar{plat}}) |
| 266 | to your chosen installation directory. |
| 267 | |
| 268 | If you don't choose an installation directory---i.e., if you just run |
| 269 | \code{setup.py install}---then the \command{install} command installs to |
| 270 | the standard location for third-party Python modules. This location |
| 271 | varies by platform and by how you built/installed Python itself. On |
| 272 | Unix and Mac OS, it also depends on whether the module distribution |
| 273 | being installed is pure Python or contains extensions (``non-pure''): |
Greg Ward | d5faa7e | 2000-04-12 01:42:19 +0000 | [diff] [blame] | 274 | \begin{tableiv}{l|l|l|c}{textrm}% |
| 275 | {Platform}{Standard installation location}{Default value}{Notes} |
| 276 | \lineiv{Unix (pure)} |
Fred Drake | 01df453 | 2000-06-30 03:36:41 +0000 | [diff] [blame] | 277 | {\filenq{\filevar{prefix}/lib/python2.0/site-packages}} |
| 278 | {\filenq{/usr/local/lib/python2.0/site-packages}} |
Greg Ward | 502d2b4 | 2000-04-12 14:20:15 +0000 | [diff] [blame] | 279 | {(1)} |
Greg Ward | d5faa7e | 2000-04-12 01:42:19 +0000 | [diff] [blame] | 280 | \lineiv{Unix (non-pure)} |
Fred Drake | 01df453 | 2000-06-30 03:36:41 +0000 | [diff] [blame] | 281 | {\filenq{\filevar{exec-prefix}/lib/python2.0/site-packages}} |
| 282 | {\filenq{/usr/local/lib/python2.0/site-packages}} |
Greg Ward | 502d2b4 | 2000-04-12 14:20:15 +0000 | [diff] [blame] | 283 | {(1)} |
Greg Ward | d5faa7e | 2000-04-12 01:42:19 +0000 | [diff] [blame] | 284 | \lineiv{Windows} |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 285 | {\filenq{\filevar{prefix}}} |
Greg Ward | 4756e5f | 2000-04-19 22:40:12 +0000 | [diff] [blame] | 286 | {\filenq{C:\textbackslash{}Python}} |
Greg Ward | 502d2b4 | 2000-04-12 14:20:15 +0000 | [diff] [blame] | 287 | {(2)} |
Greg Ward | d5faa7e | 2000-04-12 01:42:19 +0000 | [diff] [blame] | 288 | \lineiv{Mac~OS (pure)} |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 289 | {\filenq{\filevar{prefix}:Lib}} |
Greg Ward | d5faa7e | 2000-04-12 01:42:19 +0000 | [diff] [blame] | 290 | {\filenq{Python:Lib} \XXX{???}} |
| 291 | {} |
| 292 | \lineiv{Mac~OS (non-pure)} |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 293 | {\filevar{prefix}:Mac:PlugIns} |
Greg Ward | d5faa7e | 2000-04-12 01:42:19 +0000 | [diff] [blame] | 294 | {\filenq{Python:Mac:PlugIns}\XXX{???}} |
| 295 | {} |
| 296 | \end{tableiv} |
| 297 | |
| 298 | \noindent Notes: |
| 299 | \begin{description} |
Greg Ward | 502d2b4 | 2000-04-12 14:20:15 +0000 | [diff] [blame] | 300 | \item[(1)] Most Linux distributions include Python as a standard part of |
| 301 | the system, so \filevar{prefix} and \filevar{exec-prefix} are usually |
| 302 | both \file{/usr} on Linux. If you build Python yourself on Linux (or |
| 303 | any Unix-like system), the default \filevar{prefix} and |
| 304 | \filevar{exec-prefix} are \file{/usr/local}. |
| 305 | \item[(2)] The default installation directory on Windows was |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 306 | \file{C:\textbackslash{}Program Files\textbackslash{}Python} under |
| 307 | Python 1.6a1, 1.5.2, and earlier. |
Greg Ward | d5faa7e | 2000-04-12 01:42:19 +0000 | [diff] [blame] | 308 | \end{description} |
| 309 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 310 | \filevar{prefix} and \filevar{exec-prefix} stand for the directories |
| 311 | that Python is installed to, and where it finds its libraries at |
| 312 | run-time. They are always the same under Windows and Mac~OS, and very |
| 313 | often the same under Unix. You can find out what your Python |
| 314 | installation uses for \filevar{prefix} and \filevar{exec-prefix} by |
| 315 | running Python in interactive mode and typing a few simple commands. |
| 316 | Under Unix, just type \code{python} at the shell prompt; under Windows, |
Fred Drake | 01df453 | 2000-06-30 03:36:41 +0000 | [diff] [blame] | 317 | run ``Python 2.0 (interpreter)'' \XXX{right?}; under Mac~OS, \XXX{???}. |
| 318 | Once the interpreter is started, you type Python code at the |
| 319 | \samp{>>> } prompt. For example, on my Linux system, I type the three |
| 320 | Python statements shown below, and get the output as shown, to find |
| 321 | out my \filevar{prefix} and \filevar{exec-prefix}: |
| 322 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 323 | \begin{verbatim} |
| 324 | Python 1.5.2 (#1, Apr 18 1999, 16:03:16) [GCC pgcc-2.91.60 19981201 (egcs-1.1.1 on linux2 |
| 325 | Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam |
| 326 | >>> import sys |
| 327 | >>> sys.prefix |
| 328 | '/usr' |
| 329 | >>> sys.exec_prefix |
| 330 | '/usr' |
| 331 | \end{verbatim} |
| 332 | |
| 333 | If you don't want to install to the standard location, or if you don't |
| 334 | have permission to write there, then you need to read about alternate |
| 335 | installations in the next section. |
| 336 | |
| 337 | |
| 338 | % This rather nasty macro is used to generate the tables that describe |
| 339 | % each installation scheme. It's nasty because it takes two arguments |
| 340 | % for each "slot" in an installation scheme, there will soon be more |
| 341 | % than five of these slots, and TeX has a limit of 10 arguments to a |
| 342 | % macro. Uh-oh. |
| 343 | |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 344 | \newcommand{\installscheme}[8] |
| 345 | {\begin{tableiii}{lll}{textrm} |
| 346 | {Type of file} |
| 347 | {Installation Directory} |
| 348 | {Override option} |
| 349 | \lineiii{pure module distribution} |
| 350 | {\filevar{#1}\filenq{#2}} |
Greg Ward | a021aca | 2000-04-19 22:34:11 +0000 | [diff] [blame] | 351 | {\longprogramopt{install-purelib}} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 352 | \lineiii{non-pure module distribution} |
| 353 | {\filevar{#3}\filenq{#4}} |
Greg Ward | a021aca | 2000-04-19 22:34:11 +0000 | [diff] [blame] | 354 | {\longprogramopt{install-platlib}} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 355 | \lineiii{scripts} |
| 356 | {\filevar{#5}\filenq{#6}} |
Greg Ward | a021aca | 2000-04-19 22:34:11 +0000 | [diff] [blame] | 357 | {\longprogramopt{install-scripts}} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 358 | \lineiii{data} |
| 359 | {\filevar{#7}\filenq{#8}} |
Greg Ward | a021aca | 2000-04-19 22:34:11 +0000 | [diff] [blame] | 360 | {\longprogramopt{install-data}} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 361 | \end{tableiii}} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 362 | |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 363 | \section{Alternate Installation} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 364 | \label{alt-install} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 365 | |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 366 | Often, it is necessary or desirable to install modules to a location |
| 367 | other than the standard location for third-party Python modules. For |
| 368 | example, on a Unix system you might not have permission to write to the |
| 369 | standard third-party module directory. Or you might wish to try out a |
| 370 | module before making it a standard part of your local Python |
| 371 | installation; this is especially true when upgrading a distribution |
| 372 | already present: you want to make sure your existing base of scripts |
| 373 | still works with the new version before actually upgrading. |
| 374 | |
| 375 | The Distutils \command{install} command is designed to make installing |
| 376 | module distributions to an alternate location simple and painless. The |
| 377 | basic idea is that you supply a base directory for the installation, and |
| 378 | the \command{install} command picks a set of directories (called an |
| 379 | \emph{installation scheme}) under this base directory in which to |
| 380 | install files. The details differ across platforms, so read whichever |
| 381 | of the following section applies to you. |
| 382 | |
| 383 | |
| 384 | \subsection{Alternate installation: Unix (the home scheme)} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 385 | \label{alt-unix-prefix} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 386 | |
| 387 | Under Unix, there are two ways to perform an alternate installation. |
| 388 | The ``prefix scheme'' is similar to how alternate installation works |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 389 | under Windows and Mac~OS, but is not necessarily the most useful way to |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 390 | maintain a personal Python library. Hence, we document the more |
| 391 | convenient and commonly useful ``home scheme'' first. |
| 392 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 393 | The idea behind the ``home scheme'' is that you build and maintain a |
| 394 | personal stash of Python modules, probably under your home directory. |
| 395 | Installing a new module distribution is as simple as |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 396 | \begin{verbatim} |
| 397 | python setup.py install --home=<dir> |
| 398 | \end{verbatim} |
Greg Ward | a021aca | 2000-04-19 22:34:11 +0000 | [diff] [blame] | 399 | where you can supply any directory you like for the \longprogramopt{home} |
Greg Ward | 4756e5f | 2000-04-19 22:40:12 +0000 | [diff] [blame] | 400 | option. Lazy typists can just type a tilde (\code{\textasciitilde}); the |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 401 | \command{install} command will expand this to your home directory: |
| 402 | \begin{verbatim} |
| 403 | python setup.py install --home=~ |
| 404 | \end{verbatim} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 405 | |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 406 | The \longprogramopt{home} option defines the installation base |
| 407 | directory. Files are installed to the following directories under the |
| 408 | installation base as follows: |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 409 | \installscheme{home}{/lib/python} |
| 410 | {home}{/lib/python} |
| 411 | {home}{/bin} |
| 412 | {home}{/share} |
| 413 | |
| 414 | \subsection{Alternate installation: Unix (the prefix scheme)} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 415 | \label{alt-unix-home} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 416 | |
| 417 | The ``prefix scheme'' is useful when you wish to use one Python |
| 418 | installation to perform the build/install (i.e., to run the setup |
| 419 | script), but install modules into the third-party module directory of a |
| 420 | different Python installation (or something that looks like a different |
| 421 | Python installation). If this sounds a trifle unusual, it is---that's |
| 422 | why the ``home scheme'' comes first. However, there are at least two |
| 423 | known cases where the prefix scheme will be useful. |
| 424 | |
Greg Ward | 19c67f8 | 2000-06-24 01:33:16 +0000 | [diff] [blame] | 425 | First, consider that many Linux distributions put Python in \file{/usr}, |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 426 | rather than the more traditional \file{/usr/local}. This is entirely |
| 427 | appropriate, since in those cases Python is part of ``the system'' |
| 428 | rather than a local add-on. However, if you are installing Python |
| 429 | modules from source, you probably want them to go in |
| 430 | \file{/usr/local/lib/python1.\filevar{X}} rather than |
| 431 | \file{/usr/lib/python1.\filevar{X}}. This can be done with |
| 432 | \begin{verbatim} |
| 433 | /usr/bin/python setup.py install --prefix=/usr/local |
| 434 | \end{verbatim} |
| 435 | |
| 436 | Another possibility is a network filesystem where the name used to write |
| 437 | to a remote directory is different from the name used to read it: for |
| 438 | example, the Python interpreter accessed as \file{/usr/local/bin/python} |
| 439 | might search for modules in \file{/usr/local/lib/python1.\filevar{X}}, |
| 440 | but those modules would have to be installed to, say, |
| 441 | \file{/mnt/\filevar{@server}/export/lib/python1.\filevar{X}}. This |
| 442 | could be done with |
| 443 | \begin{verbatim} |
| 444 | /usr/local/bin/python setup.py install --prefix=/mnt/@server/export |
| 445 | \end{verbatim} |
| 446 | |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 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: |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 454 | |
| 455 | \installscheme{prefix}{/lib/python1.\filevar{X}/site-packages} |
| 456 | {exec-prefix}{/lib/python1.\filevar{X}/site-packages} |
| 457 | {prefix}{/bin} |
| 458 | {prefix}{/share} |
| 459 | |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 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. |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 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 |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 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. |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 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 compatibile with the |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 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 |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 482 | your \longprogramopt{prefix} and \longprogramopt{exec-prefix} don't even |
| 483 | point to an alternate Python installation, this is immaterial.) |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 484 | |
| 485 | |
| 486 | \subsection{Alternate installation: Windows} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 487 | \label{alt-windows} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 488 | |
| 489 | Since Windows has no conception of a user's home directory, and since |
| 490 | the standard Python installation under Windows is simpler than that |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 491 | under Unix, there's no point in having separate \longprogramopt{prefix} |
| 492 | and \longprogramopt{home} options. Just use the \longprogramopt{prefix} |
| 493 | option to specify a base directory, e.g. |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 494 | \begin{verbatim} |
Greg Ward | 8e14f05 | 2000-03-22 01:00:23 +0000 | [diff] [blame] | 495 | python setup.py install --prefix="\Temp\Python" |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 496 | \end{verbatim} |
Greg Ward | 4756e5f | 2000-04-19 22:40:12 +0000 | [diff] [blame] | 497 | to install modules to the \file{\textbackslash{}Temp} directory on the current |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 498 | drive. |
| 499 | |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 500 | The installation base is defined by the \longprogramopt{prefix} option; |
| 501 | the \longprogramopt{exec-prefix} option is not supported under Windows. |
| 502 | Files are installed as follows: |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 503 | \installscheme{prefix}{} |
| 504 | {prefix}{} |
Greg Ward | 4756e5f | 2000-04-19 22:40:12 +0000 | [diff] [blame] | 505 | {prefix}{\textbackslash{}Scripts} |
| 506 | {prefix}{\textbackslash{}Data} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 507 | |
| 508 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 509 | \subsection{Alternate installation: Mac~OS} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 510 | \label{alt-macos} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 511 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 512 | Like Windows, Mac~OS has no notion of home directories (or even of |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 513 | users), and a fairly simple standard Python installation. Thus, only a |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 514 | \longprogramopt{prefix} option is needed. It defines the installation |
| 515 | base, and files are installed under it as follows: |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 516 | |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 517 | \XXX{how do MacPython users run the interpreter with command-line args?} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 518 | |
| 519 | \installscheme{prefix}{:Lib} |
| 520 | {prefix}{:Mac:PlugIns} |
Greg Ward | 8e14f05 | 2000-03-22 01:00:23 +0000 | [diff] [blame] | 521 | {prefix}{:Scripts} |
| 522 | {prefix}{:Data} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 523 | |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 524 | \XXX{Corran Webster says: ``Modules are found in either \file{:Lib} or |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 525 | \file{:Mac:Lib}, while extensions usually go in |
| 526 | \file{:Mac:PlugIns}''---does this mean that non-pure distributions should |
| 527 | be divided between \file{:Mac:PlugIns} and \file{:Mac:Lib}? If so, that |
| 528 | changes the granularity at which we care about modules: instead of |
| 529 | ``modules from pure distributions'' and ``modules from non-pure |
| 530 | distributions'', it becomes ``modules from pure distributions'', |
| 531 | ``Python modules from non-pure distributions'', and ``extensions from |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 532 | non-pure distributions''. Is this necessary?!?} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 533 | |
| 534 | |
| 535 | \section{Custom Installation} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 536 | \label{custom-install} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 537 | |
| 538 | Sometimes, the alternate installation schemes described in |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 539 | section~\ref{alt-install} just don't do what you want. You might |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 540 | want to tweak just one or two directories while keeping everything under |
| 541 | the same base directory, or you might want to completely redefine the |
| 542 | installation scheme. In either case, you're creating a \emph{custom |
| 543 | installation scheme}. |
| 544 | |
| 545 | You probably noticed the column of ``override options'' in the tables |
| 546 | describing the alternate installation schemes above. Those options are |
| 547 | how you define a custom installation scheme. These override options can |
| 548 | be relative, absolute, or explicitly defined in terms of one of the |
| 549 | installation base directories. (There are two installation base |
| 550 | directories, and they are normally the same---they only differ when you |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 551 | use the Unix ``prefix scheme'' and supply different |
| 552 | \longprogramopt{prefix} and \longprogramopt{exec-prefix} options.) |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 553 | |
| 554 | For example, say you're installing a module distribution to your home |
| 555 | directory under Unix---but you want scripts to go in |
Greg Ward | 4eaa3bf | 2000-04-19 22:44:25 +0000 | [diff] [blame] | 556 | \file{\textasciitilde/scripts} rather than \file{\textasciitilde/bin}. |
| 557 | As you might expect, you can override this directory with the |
| 558 | \longprogramopt{install-scripts} option; in this case, it makes most |
| 559 | sense to supply a relative path, which will be interpreted relative to |
| 560 | the installation base directory (your home directory, in this case): |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 561 | \begin{verbatim} |
Greg Ward | 19c67f8 | 2000-06-24 01:33:16 +0000 | [diff] [blame] | 562 | python setup.py install --home=~ --install-scripts=scripts |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 563 | \end{verbatim} |
| 564 | |
| 565 | Another Unix example: suppose your Python installation was built and |
| 566 | installed with a prefix of \file{/usr/local/python}, so under a standard |
| 567 | installation scripts will wind up in \file{/usr/local/python/bin}. If |
| 568 | you want them in \file{/usr/local/bin} instead, you would supply this |
Greg Ward | a021aca | 2000-04-19 22:34:11 +0000 | [diff] [blame] | 569 | absolute directory for the \longprogramopt{install-scripts} option: |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 570 | \begin{verbatim} |
| 571 | python setup.py install --install-scripts=/usr/local/bin |
| 572 | \end{verbatim} |
| 573 | (This performs an installation using the ``prefix scheme,'' where the |
| 574 | prefix is whatever your Python interpreter was installed with--- |
| 575 | \file{/usr/local/python} in this case.) |
| 576 | |
| 577 | If you maintain Python on Windows, you might want third-party modules to |
| 578 | live in a subdirectory of \filevar{prefix}, rather than right in |
| 579 | \filevar{prefix} itself. This is almost as easy as customizing the |
| 580 | script installation directory---you just have to remember that there are |
| 581 | two types of modules to worry about, pure modules and non-pure modules |
| 582 | (i.e., modules from a non-pure distribution). For example: |
| 583 | \begin{verbatim} |
| 584 | python setup.py install --install-purelib=Site --install-platlib=Site |
| 585 | \end{verbatim} |
| 586 | The specified installation directories are relative to \filevar{prefix}. |
| 587 | Of course, you also have to ensure that these directories are in |
| 588 | Python's module search path, e.g. by putting a \file{.pth} file in |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 589 | \filevar{prefix} (\XXX{should have a section describing .pth files and |
| 590 | cross-ref it here}). |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 591 | |
| 592 | If you want to define an entire installation scheme, you just have to |
| 593 | supply all of the installation directory options. The recommended way |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 594 | to do this is to supply relative paths; for example, if you want to |
| 595 | maintain all Python module-related files under \file{python} in your |
| 596 | home directory, and you want a separate directory for each platform that |
| 597 | you use your home directory from, you might define the following |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 598 | installation scheme: |
| 599 | \begin{verbatim} |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 600 | python setup.py install --home=~ \ |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 601 | --install-purelib=python/lib \ |
| 602 | --install-platlib=python/lib.$PLAT \ |
| 603 | --install-scripts=python/scripts |
| 604 | --install-data=python/data |
| 605 | \end{verbatim} |
| 606 | or, equivalently, |
| 607 | \begin{verbatim} |
| 608 | python setup.py install --home=~/python \ |
| 609 | --install-purelib=lib \ |
Greg Ward | 19c67f8 | 2000-06-24 01:33:16 +0000 | [diff] [blame] | 610 | --install-platlib='lib.$PLAT' \ |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 611 | --install-scripts=scripts |
| 612 | --install-data=data |
| 613 | \end{verbatim} |
| 614 | \code{\$PLAT} is not (necessarily) an environment variable---it will be |
| 615 | expanded by the Distutils as it parses your command line options (just |
| 616 | as it does when parsing your configuration file(s)). |
| 617 | |
| 618 | Obviously, specifying the entire installation scheme every time you |
| 619 | install a new module distribution would be very tedious. Thus, you can |
| 620 | put these options into your Distutils config file (see |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 621 | section~\ref{config-files}): |
Greg Ward | 169f91b | 2000-03-10 01:57:51 +0000 | [diff] [blame] | 622 | \begin{verbatim} |
| 623 | [install] |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 624 | install-base=$HOME |
| 625 | install-purelib=python/lib |
| 626 | install-platlib=python/lib.$PLAT |
| 627 | install-scripts=python/scripts |
| 628 | install-data=python/data |
Greg Ward | 169f91b | 2000-03-10 01:57:51 +0000 | [diff] [blame] | 629 | \end{verbatim} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 630 | or, equivalently, |
Greg Ward | 169f91b | 2000-03-10 01:57:51 +0000 | [diff] [blame] | 631 | \begin{verbatim} |
| 632 | [install] |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 633 | install-base=$HOME/python |
| 634 | install-purelib=lib |
| 635 | install-platlib=lib.$PLAT |
| 636 | install-scripts=scripts |
| 637 | install-data=data |
Greg Ward | 169f91b | 2000-03-10 01:57:51 +0000 | [diff] [blame] | 638 | \end{verbatim} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 639 | Note that these two are \emph{not} equivalent if you supply a different |
| 640 | installation base directory when you run the setup script. For example, |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 641 | \begin{verbatim} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 642 | python setup.py --install-base=/tmp |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 643 | \end{verbatim} |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 644 | would install pure modules to \filevar{/tmp/python/lib} in the first |
| 645 | case, and to \filevar{/tmp/lib} in the second case. (For the second |
| 646 | case, you probably want to supply an installation base of |
| 647 | \file{/tmp/python}.) |
Greg Ward | 169f91b | 2000-03-10 01:57:51 +0000 | [diff] [blame] | 648 | |
Greg Ward | 2957656 | 2000-03-18 15:11:50 +0000 | [diff] [blame] | 649 | You probably noticed the use of \code{\$HOME} and \code{\$PLAT} in the |
| 650 | sample configuration file input. These are Distutils configuration |
| 651 | variables, which bear a strong resemblance to environment variables. In |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 652 | fact, you can use environment variables in config files---on platforms |
| 653 | that have such a notion---but the Distutils additionally define a few |
| 654 | extra variables that may not be in your environment, such as |
| 655 | \code{\$PLAT}. (And of course, you can only use the configuration |
| 656 | variables supplied by the Distutils on systems that don't have |
| 657 | environment variables, such as Mac~OS (\XXX{true?}).) See |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 658 | section~\ref{config-files} for details. |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 659 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 660 | \XXX{need some Windows and Mac~OS examples---when would custom |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 661 | installation schemes be needed on those platforms?} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 662 | |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 663 | |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 664 | \section{Distutils Configuration Files} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 665 | \label{config-files} |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 666 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 667 | \XXX{not even implemented yet, much less documented!} |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 668 | |
| 669 | |
| 670 | \section{Pre-Distutils Conventions} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 671 | \label{pre-distutils} |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 672 | |
| 673 | |
Greg Ward | c392caa | 2000-04-11 02:00:26 +0000 | [diff] [blame] | 674 | \subsection{The Makefile.pre.in file} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 675 | \label{makefile-pre-in} |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 676 | |
| 677 | |
| 678 | \subsection{Installing modules manually} |
Greg Ward | e78298a | 2000-04-28 17:12:24 +0000 | [diff] [blame] | 679 | \label{manual-install} |
Greg Ward | 6002ffc | 2000-04-09 20:54:50 +0000 | [diff] [blame] | 680 | |
| 681 | |
| 682 | |
Greg Ward | 7c1e5f6 | 2000-03-10 01:56:58 +0000 | [diff] [blame] | 683 | \end{document} |