From 6002ffc38ca134a4e7446768523ce35cdd59ea59 Mon Sep 17 00:00:00 2001 From: Greg Ward Date: Sun, 9 Apr 2000 20:54:50 +0000 Subject: [PATCH] Wrote the introduction (including several subsections). Started writing the "Standard Build and Install" section. --- Doc/inst/inst.tex | 193 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 177 insertions(+), 16 deletions(-) diff --git a/Doc/inst/inst.tex b/Doc/inst/inst.tex index caff68641bc..79d716febe9 100644 --- a/Doc/inst/inst.tex +++ b/Doc/inst/inst.tex @@ -21,7 +21,6 @@ % Finally, it might be useful to include all the material from my "Care % and Feeding of a Python Installation" talk in here somewhere. Yow! -% Hey wow, Guido didn't write this one either! \author{Greg Ward} \authoraddress{E-mail: \email{gward@python.net}} @@ -40,24 +39,172 @@ \section{Introduction} \label{sec:intro} -\subsection{The new way: Distutils} -\label{sec:new-way} +Although Python's extensive standard library covers many programming +needs, there often comes a time when you need to add some new +functionality to your Python installation in the form of third-party +modules. This might be necessary to support your own programming, or to +support an application that you want to use and that happens to be +written in Python. + +In the past, there has been little support for adding third-party +modules to an existing Python installation. With the introduction of +the Python Distribution Utilities (Distutils for short) in Python 1.6, +this is starting to change. Not everything will change overnight, +though, so while this document concentrates on installing module +distributions that use the Distutils, we will also spend some time +dealing with the old ways. + +This document is aimed primarily at the people who need to install +third-party Python modules: end-users and system administrators who just +need to get some Python application running, and existing Python +programmers who want to add some new goodies to their toolbox. You +don't need to know Python to read this document; there will be some +brief forays into using Python's interactive mode to explore your +installation, but that's it. If you're looking for information on how +to distribute your own Python modules so that others may use them, see +the ``Distributing Python Modules'' manual. -\subsection{The old way (pure Python): whatever you feel like} -\label{sec:old-way-pure} +\subsection{Best case: trivial installation} +\label{sec:trivial-inst} + +In the best case, someone will have prepared a special version of the +module distribution you want to install that is targeted specifically at +your platform and is installed just like any other software on your +platform. For example, the module developer might make an executable +installer available for Windows users, an RPM package for users of +RPM-based Linux systems (Red Hat, SuSE, Mandrake, and many others), a +Debian package for users of Debian-based Linux systems (Debian proper, +Caldera, Corel, etc.), and so forth. + +In that case, you would download the installer appropriate to your +platform and do the usual thing with it: run it if it's an executable +installer, \code{rpm -I} it if it's an RPM, etc. You don't need to run +Python or a setup script, you don't need to compile anything---you might +not even need to read any instructions (although it's always a good idea +to do so anyways). + +Of course, things will not always be that easy. You might be interested +in a module distribution that nobody has created an easy-to-use +installer for use on your platform. In that case, you'll have to start +with the source distribution released by the module's +author/maintainer. Installing from a source distribution is not too +hard, as long as the modules are packaged in the standard way. The bulk +of this document is about building and installing modules that were +packaged in the standard way. -\subsection{The old way (extensions, \UNIX{} only): Makefile.pre.in} -\label{sec:old-way-ext} +\subsection{The new standard: Distutils} +\label{sec:new-standard} + +If you download a module source distribution, you can tell pretty +quickly if was packaged and distributed in the standard way, i.e. using +the Distutils. First, the distribution's name and version number will +be featured prominently in the name of the downloaded archive, e.g. +\file{foo-1.0.tar.gz} or \file{widget-0.9.7.zip}. Next, the archive +will unpack into a similarly-named directory: \file{foo-1.0} or +\file{widget-0.9.7}. Additionally, the distribution will contain a +setup script \file{setup.py}, and a \file{README.txt} (or possibly +\file{README}), which should explain that building and installing the +module distribution is a simple matter of running +\begin{verbatim} +python setup.py install +\end{verbatim} + +If all these things are true, then you already know how to build and +install the modules you've just downloaded: run the command above. +Unless you need to install things in a non-standard way or customize the +build process, you don't really need this manual. Or rather, the above +command is everything you need to get out of this manual. +\subsection{The old way: no standards} +\label{sec:old-way} +Before the Distutils, there was no infrastructure to support installing +third-party modules in a consistent, standardized way. Thus, it's not +really possible to write a general manual for installing Python modules +that don't use the Distutils; the only truly general statement that can +be made is, ``Read the module's own documentation on installation.'' + +However, such documentation is often woefully inadequate, assuming that +you are familiar with how the Python library is laid out and will +somehow just know where to copy various files in order for Python to +find them. Also, since there is only one way to lay out the Python +library on a given platform, this manual is a good place to learn that +layout. That way, if you do have to manually install an old, +pre-Distutils module distribution, you won't be completely on your own. + +Additionally, while there has not previously been a standard +installation mechanism, Python has had some standard machinery for +building extensions on Unix since Python \XXX{version?}. This machinery +(the \file{Makefile.pre.in} file) is superseded by the Distutils, but it +will no doubt live on in older module distributions for a while. This +\file{Makefile.pre.in} mechanism is documented in the ``Extending \& +Embedding Python'' manual, but that manual is aimed at module +developers---hence, we include documentation for builders/installers +here. + +All of the pre-Distutils material is tucked away in +section~\ref{sec:pre-distutils}. \section{Standard Build and Install} \label{sec:normal-install} +As described in section~\ref{sec:new-standard}, building and installing +a module distribution using the Distutils is usually one simple command: +\begin{verbatim} +python setup.py install +\end{verbatim} +On Unix, you'd run this command from a shell prompt; on Windows, you +have to open a command prompt window and do it there; on Mac OS ... +\XXX{what the heck do you do on Mac OS?}. + + +\subsection{Platform variations} + +You should always run the setup command from the distribution root +directory, i.e. the top-level subdirectory that the module source +distribution unpacks into. For example, if you've just downloaded a +module source distribution \file{foo-1.0.tar.gz} onto a Unix system, the +normal thing to do is: +\begin{verbatim} +gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0 +cd foo-1.0 +python setup.py install +\end{verbatim} + +On Windows, you'd probably unpack the archive before opening the command +prompt. If you downloaded the archive file to \file{C:\bslash{}Temp}, then +it probably unpacked (depending on your software) into +\file{C:\bslash{}Temp\bslash{}foo-1.0}; from the command prompt window, you would +then run +\begin{verbatim} +cd c:\temp\foo-1.0 +python setup.py install +\end{verbatim} + +On Mac OS, ... \XXX{again, how do you run Python scripts on Mac OS?} + + +\subsection{Splitting the job up} + +Running \code{setup.py install} builds and installs all modules in one +fell swoop. If you prefer to work incrementally---especially useful if +you want to customize the build process, or if things are going +wrong---you can use the setup script to do one thing at a time. + +For example, you can build everything in one step, and then install +everything in a second step, by invoking the setup script twice: +\begin{verbatim} +python setup.py build +python setup.py install +\end{verbatim} +(If you do this, you will notice that running the \command{install} +command first runs the \command{build} command, which will quickly +notice that it has nothing to do, since everything in the \file{build} +directory is up-to-date. % This will cover: % * setup.py install (the usual thing) @@ -254,14 +401,14 @@ users), and a fairly simple standard Python installation. Thus, only a \option{prefix} option is needed. It defines the installation base, and files are installed under it as follows: -XXX how do MacPython users run the interpreter with command-line args? +\XXX{how do MacPython users run the interpreter with command-line args?} \installscheme{prefix}{:Lib} {prefix}{:Mac:PlugIns} {prefix}{:Scripts} {prefix}{:Data} -XXX Corran Webster says: ``Modules are found in either \file{:Lib} or +\XXX{Corran Webster says: ``Modules are found in either \file{:Lib} or \file{:Mac:Lib}, while extensions usually go in \file{:Mac:PlugIns}''---does this mean that non-pure distributions should be divided between \file{:Mac:PlugIns} and \file{:Mac:Lib}? If so, that @@ -269,7 +416,7 @@ changes the granularity at which we care about modules: instead of ``modules from pure distributions'' and ``modules from non-pure distributions'', it becomes ``modules from pure distributions'', ``Python modules from non-pure distributions'', and ``extensions from -non-pure distributions''. Is this necessary?!? +non-pure distributions''. Is this necessary?!?} \section{Custom Installation} @@ -326,8 +473,8 @@ python setup.py install --install-purelib=Site --install-platlib=Site The specified installation directories are relative to \filevar{prefix}. Of course, you also have to ensure that these directories are in Python's module search path, e.g. by putting a \file{.pth} file in -\filevar{prefix} (XXX should have a section describing .pth files and -cross-ref it here). +\filevar{prefix} (\XXX{should have a section describing .pth files and + cross-ref it here}). If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way @@ -394,14 +541,28 @@ Distutils additionally define a few extra variables that may not be in your environment, such as \code{\$PATH}. See section~\ref{sec:config-files} for details. -XXX need some Windows and Mac OS examples---when would custom -installation schemes be needed on those platforms? +\XXX{need some Windows and Mac OS examples---when would custom + installation schemes be needed on those platforms?} - -\section{Configuration Files} +\section{Distutils Configuration Files} \label{sec:config-files} \comingsoon + + +\section{Pre-Distutils Conventions} +\label{sec:pre-distutils} + + +\subsection{The \protect\file{Makefile.pre.in} file} +\label{sec:makefile-pre-in} + + +\subsection{Installing modules manually} +\label{sec:manual-install} + + + \end{document}