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