diff options
Diffstat (limited to 'Doc/install')
| -rw-r--r-- | Doc/install/index.rst | 149 |
1 files changed, 90 insertions, 59 deletions
diff --git a/Doc/install/index.rst b/Doc/install/index.rst index a91606c..d391fce 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -1,4 +1,4 @@ -.. highlight:: none +.. highlightlang:: none .. _install-index: @@ -13,17 +13,30 @@ .. seealso:: :ref:`installing-index` - The up to date module installation documentation. For regular Python - usage, you almost certainly want that document rather than this one. + The up to date module installation documentations + +.. The audience for this document includes people who don't know anything + about Python and aren't about to learn the language just in order to + install and maintain it for their users, i.e. system administrators. + Thus, I have to be sure to explain the basics at some point: + sys.path and PYTHONPATH at least. Should probably give pointers to + other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. + + Finally, it might be useful to include all the material from my "Care + and Feeding of a Python Installation" talk in here somewhere. Yow! + +This document describes the Python Distribution Utilities ("Distutils") from the +end-user's point-of-view, describing how to extend the capabilities of a +standard Python installation by building and installing third-party Python +modules and extensions. -.. include:: ../distutils/_setuptools_disclaimer.rst .. note:: This guide only covers the basic tools for building and distributing extensions that are provided as part of this version of Python. Third party tools offer easier to use and more secure alternatives. Refer to the `quick - recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__ + recommendations section <https://packaging.python.org/en/latest/current/>`__ in the Python Packaging User Guide for more information. @@ -33,26 +46,60 @@ Introduction ============ -In Python 2.0, the ``distutils`` API was first added to the standard library. -This provided Linux distro maintainers with a standard way of converting -Python projects into Linux distro packages, and system administrators with a -standard way of installing them directly onto target systems. +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 2.0, this changed. + +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 :ref:`distutils-index` manual. :ref:`debug-setup-script` may also be of +interest. + + + +.. _inst-trivial-install: + +Best case: trivial installation +------------------------------- + +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, and so forth. -In the many years since Python 2.0 was released, tightly coupling the build -system and package installer to the language runtime release cycle has turned -out to be problematic, and it is now recommended that projects use the -``pip`` package installer and the ``setuptools`` build system, rather than -using ``distutils`` directly. +In that case, you would download the installer appropriate to your platform and +do the obvious thing with it: run it if it's an executable installer, ``rpm +--install`` 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 anyway). -See :ref:`installing-index` and :ref:`distributing-index` for more details. +Of course, things will not always be that easy. You might be interested in a +module distribution that doesn't have an easy-to-use installer for 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 from standard source distributions. -This legacy documentation is being retained only until we're confident that the -``setuptools`` documentation covers everything needed. .. _inst-new-standard: -Distutils based source distributions ------------------------------------- +The new standard: Distutils +--------------------------- If you download a module source distribution, you can tell pretty quickly if it was packaged and distributed in the standard way, i.e. using the Distutils. @@ -237,9 +284,7 @@ Windows, choose :menuselection:`Start --> Programs --> Python X.Y --> Python (command line)`. Once the interpreter is started, you type Python code at the prompt. For example, on my Linux system, I type the three Python statements shown below, and get the output as shown, to find out my -:file:`{prefix}` and :file:`{exec-prefix}`: - -.. code-block:: pycon +:file:`{prefix}` and :file:`{exec-prefix}`:: Python 2.4 (#26, Aug 7 2004, 17:19:02) Type "help", "copyright", "credits" or "license" for more information. @@ -250,12 +295,10 @@ statements shown below, and get the output as shown, to find out my '/usr' A few other placeholders are used in this document: :file:`{X.Y}` stands for the -version of Python, for example ``3.2``; :file:`{abiflags}` will be replaced by -the value of :data:`sys.abiflags` or the empty string for platforms which don't -define ABI flags; :file:`{distname}` will be replaced by the name of the module -distribution being installed. Dots and capitalization are important in the -paths; for example, a value that uses ``python3.2`` on UNIX will typically use -``Python32`` on Windows. +version of Python, for example ``2.7``; :file:`{distname}` will be replaced by +the name of the module distribution being installed. Dots and capitalization +are important in the paths; for example, a value that uses ``python2.7`` on UNIX +will typically use ``Python27`` on Windows. If you don't want to install modules to the standard location, or if you don't have permission to write there, then you need to read about alternate @@ -313,7 +356,7 @@ Type of file Installation directory modules :file:`{userbase}/lib/python{X.Y}/site-packages` scripts :file:`{userbase}/bin` data :file:`{userbase}` -C headers :file:`{userbase}/include/python{X.Y}{abiflags}/{distname}` +C headers :file:`{userbase}/include/python{X.Y}/{distname}` =============== =========================================================== And here are the values used on Windows: @@ -322,7 +365,7 @@ And here are the values used on Windows: Type of file Installation directory =============== =========================================================== modules :file:`{userbase}\\Python{XY}\\site-packages` -scripts :file:`{userbase}\\Python{XY}\\Scripts` +scripts :file:`{userbase}\\Scripts` data :file:`{userbase}` C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}` =============== =========================================================== @@ -380,6 +423,9 @@ C headers :file:`{home}/include/python/{distname}` (Mentally replace slashes with backslashes if you're on Windows.) +.. versionchanged:: 2.4 + The :option:`!--home` option used to be supported only on Unix. + .. _inst-alt-install-prefix-unix: @@ -425,7 +471,7 @@ Python modules :file:`{prefix}/lib/python{X.Y}/site-packages` extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages` scripts :file:`{prefix}/bin` data :file:`{prefix}` -C headers :file:`{prefix}/include/python{X.Y}{abiflags}/{distname}` +C headers :file:`{prefix}/include/python{X.Y}/{distname}` ================= ========================================================== There is no requirement that :option:`!--prefix` or :option:`!--exec-prefix` @@ -508,10 +554,10 @@ C headers ``--install-headers`` These override options can be relative, absolute, or explicitly defined in terms of one of the installation base directories. -(There are two installation base directories, and they are normally the -same---they only differ when you use the Unix "prefix scheme" and supply -different ``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` -will override values computed or given for ``--install-purelib`` and +(There are two installation base directories, and they are normally the same--- +they only differ when you use the Unix "prefix scheme" and supply different +``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will +override values computed or given for ``--install-purelib`` and ``--install-platlib``, and is recommended for schemes that don't make a difference between Python and extension modules.) @@ -538,10 +584,10 @@ in this case.) If you maintain Python on Windows, you might want third-party modules to live in a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` -itself. This is almost as easy as customizing the script installation -directory---you just have to remember that there are two types of modules -to worry about, Python and extension modules, which can conveniently be both -controlled by one option:: +itself. This is almost as easy as customizing the script installation directory +---you just have to remember that there are two types of modules to worry about, +Python and extension modules, which can conveniently be both controlled by one +option:: python setup.py install --install-lib=Site @@ -578,9 +624,7 @@ parsing your configuration file(s). Obviously, specifying the entire installation scheme every time you install a new module distribution would be very tedious. Thus, you can put these options -into your Distutils config file (see section :ref:`inst-config-files`): - -.. code-block:: ini +into your Distutils config file (see section :ref:`inst-config-files`):: [install] install-base=$HOME @@ -589,9 +633,7 @@ into your Distutils config file (see section :ref:`inst-config-files`): install-scripts=python/scripts install-data=python/data -or, equivalently, - -.. code-block:: ini +or, equivalently, :: [install] install-base=$HOME/python @@ -619,11 +661,6 @@ environment variables, such as Mac OS 9, the configuration variables supplied by the Distutils are the only ones you can use.) See section :ref:`inst-config-files` for details. -.. note:: When a :ref:`virtual environment <venv-def>` is activated, any options - that change the installation path will be ignored from all distutils configuration - files to prevent inadvertently installing projects outside of the virtual - environment. - .. XXX need some Windows examples---when would custom installation schemes be needed on those platforms? @@ -678,9 +715,7 @@ A slightly less convenient way is to edit the :file:`site.py` file in Python's standard library, and modify ``sys.path``. :file:`site.py` is automatically imported when the Python interpreter is executed, unless the :option:`-S` switch is supplied to suppress this behaviour. So you could simply edit -:file:`site.py` and add two lines to it: - -.. code-block:: python +:file:`site.py` and add two lines to it:: import sys sys.path.append('/www/python/') @@ -801,9 +836,7 @@ plus a ``global`` section for global options that affect every command. Each section consists of one option per line, specified as ``option=value``. For example, the following is a complete config file that just forces all -commands to run quietly by default: - -.. code-block:: ini +commands to run quietly by default:: [global] verbose=0 @@ -817,9 +850,7 @@ distribution. You could override the default "build base" directory and make the :command:`build\*` commands always forcibly rebuild all files with the -following: - -.. code-block:: ini +following:: [build] build-base=blib |