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