Changeset 391 for python/trunk/Doc/install/index.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/install/index.rst (modified) (25 diffs)

python/trunk/Doc/install/index.rst

@@ -8 +8 @@
 
 :Author: Greg Ward
-:Release: |version|
-:Date: |today|
 
 .. TODO: Fill in XXX comments
@@ -73 +71 @@
 --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 anyways).
+instructions (although it's always a good idea to do so anyway).
 
 Of course, things will not always be that easy.  You might be interested in a
@@ -97 +95 @@
 distribution will contain a setup script :file:`setup.py`, and a file named
 :file:`README.txt` or possibly just :file:`README`, which should explain that
-building and installing the module distribution is a simple matter of running ::
+building and installing the module distribution is a simple matter of running
+one command from a terminal::
 
    python setup.py install
+
+For Windows, this command should be run from a command prompt window
+(:menuselection:`Start --> Accessories`)::
+
+   setup.py install
 
 If all these things are true, then you already know how to build and install the
@@ -114 +118 @@
 
 As described in section :ref:`inst-new-standard`, building and installing a module
-distribution using the Distutils is usually one simple command::
+distribution using the Distutils is usually one simple command to run from a
+terminal::
 
    python setup.py install
-
-On Unix, you'd run this command from a shell prompt; on Windows, you have to
-open a command prompt window ("DOS box") and do it there; on Mac OS X, you open
-a :command:`Terminal` window to get a shell prompt.
 
 
@@ -142 +143 @@
 graphical user interface (such as WinZip) or a command-line tool (such as
 :program:`unzip` or :program:`pkunzip`) to unpack the archive.  Then, open a
-command prompt window ("DOS box"), and run::
+command prompt window and run::
 
    cd c:\Temp\foo-1.0
@@ -189 +190 @@
 :option:`--build-base` option. For example::
 
-   python setup.py build --build-base=/tmp/pybuild/foo-1.0
+   python setup.py build --build-base=/path/to/pybuild/foo-1.0
 
 (Or you could do this permanently with a directive in your system or personal
@@ -235 +236 @@
 is pure Python or contains extensions ("non-pure"):
 
+.. tabularcolumns:: |l|l|l|l|
+
 +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
 | Platform        | Standard installation location                      | Default value                                    | Notes |
@@ -242 +245 @@
 | Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1)  |
 +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
-| Windows         | :file:`{prefix}`                                    | :file:`C:\\Python`                               | \(2)  |
+| Windows         | :file:`{prefix}\\Lib\\site-packages`                | :file:`C:\\Python{XY}\\Lib\\site-packages`       | \(2)  |
 +-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
 
@@ -277 +280 @@
    '/usr'
 
+A few other placeholders are used in this document: :file:`{X.Y}` stands for the
+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
@@ -305 +314 @@
 you.
 
-
-.. _inst-alt-install-prefix:
+Note that the various alternate installation schemes are mutually exclusive: you
+can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or
+``--install-base`` and ``--install-platbase``, but you can't mix from these
+groups.
+
+
+.. _inst-alt-install-user:
+
+Alternate installation: the user scheme
+---------------------------------------
+
+This scheme is designed to be the most convenient solution for users that don't
+have write permission to the global site-packages directory or don't want to
+install into it.  It is enabled with a simple option::
+
+   python setup.py install --user
+
+Files will be installed into subdirectories of :data:`site.USER_BASE` (written
+as :file:`{userbase}` hereafter).  This scheme installs pure Python modules and
+extension modules in the same location (also known as :data:`site.USER_SITE`).
+Here are the values for UNIX, including Mac OS X:
+
+=============== ===========================================================
+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}/{distname}`
+=============== ===========================================================
+
+And here are the values used on Windows:
+
+=============== ===========================================================
+Type of file    Installation directory
+=============== ===========================================================
+modules         :file:`{userbase}\\Python{XY}\\site-packages`
+scripts         :file:`{userbase}\\Scripts`
+data            :file:`{userbase}`
+C headers       :file:`{userbase}\\Python{XY}\\Include\\{distname}`
+=============== ===========================================================
+
+The advantage of using this scheme compared to the other ones described below is
+that the user site-packages directory is under normal conditions always included
+in :data:`sys.path` (see :mod:`site` for more information), which means that
+there is no additional step to perform after running the :file:`setup.py` script
+to finalize the installation.
+
+The :command:`build_ext` command also has a ``--user`` option to add
+:file:`{userbase}/include` to the compiler search path for header files and
+:file:`{userbase}/lib` to the compiler search path for libraries as well as to
+the runtime search path for shared C libraries (rpath).
+
+
+.. _inst-alt-install-home:
 
 Alternate installation: the home scheme
@@ -315 +377 @@
 "home" directory on Unix, since it's not unusual for a Unix user to make their
 home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`.
-This scheme can be used by anyone, regardless of the operating system their
-installing for.
+This scheme can be used by anyone, regardless of the operating system they
+are installing for.
 
 Installing a new module distribution is as simple as ::
@@ -328 +390 @@
    python setup.py install --home=~
 
+To make Python find the distributions installed with this scheme, you may have
+to :ref:`modify Python's search path <inst-search-path>` or edit
+:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit
+:data:`sys.path`.
+
 The :option:`--home` option defines the installation base directory.  Files are
 installed to the following directories under the installation base as follows:
 
-+------------------------------+---------------------------+-----------------------------+
-| Type of file                 | Installation Directory    | Override option             |
-+==============================+===========================+=============================+
-| pure module distribution     | :file:`{home}/lib/python` | :option:`--install-purelib` |
-+------------------------------+---------------------------+-----------------------------+
-| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` |
-+------------------------------+---------------------------+-----------------------------+
-| scripts                      | :file:`{home}/bin`        | :option:`--install-scripts` |
-+------------------------------+---------------------------+-----------------------------+
-| data                         | :file:`{home}/share`      | :option:`--install-data`    |
-+------------------------------+---------------------------+-----------------------------+
+=============== ===========================================================
+Type of file    Installation directory
+=============== ===========================================================
+modules         :file:`{home}/lib/python`
+scripts         :file:`{home}/bin`
+data            :file:`{home}`
+C headers       :file:`{home}/include/python/{distname}`
+=============== ===========================================================
+
+(Mentally replace slashes with backslashes if you're on Windows.)
 
 .. versionchanged:: 2.4
@@ -347 +413 @@
 
 
-.. _inst-alt-install-home:
+.. _inst-alt-install-prefix-unix:
 
 Alternate installation: Unix (the prefix scheme)
@@ -356 +422 @@
 into the third-party module directory of a different Python installation (or
 something that looks like a different Python installation).  If this sounds a
-trifle unusual, it is---that's why the "home scheme" comes first.  However,
+trifle unusual, it is---that's why the user and home schemes come before.  However,
 there are at least two known cases where the prefix scheme will be useful.
 
@@ -384 +450 @@
 :option:`--prefix`.  Files are installed as follows:
 
-+------------------------------+-----------------------------------------------------+-----------------------------+
-| Type of file                 | Installation Directory                              | Override option             |
-+==============================+=====================================================+=============================+
-| pure module distribution     | :file:`{prefix}/lib/python{X.Y}/site-packages`      | :option:`--install-purelib` |
-+------------------------------+-----------------------------------------------------+-----------------------------+
-| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` |
-+------------------------------+-----------------------------------------------------+-----------------------------+
-| scripts                      | :file:`{prefix}/bin`                                | :option:`--install-scripts` |
-+------------------------------+-----------------------------------------------------+-----------------------------+
-| data                         | :file:`{prefix}/share`                              | :option:`--install-data`    |
-+------------------------------+-----------------------------------------------------+-----------------------------+
+================= ==========================================================
+Type of file      Installation directory
+================= ==========================================================
+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}/{distname}`
+================= ==========================================================
 
 There is no requirement that :option:`--prefix` or :option:`--exec-prefix`
@@ -419 +483 @@
 
 
-.. _inst-alt-install-windows:
+.. _inst-alt-install-prefix-windows:
 
 Alternate installation: Windows (the prefix scheme)
@@ -434 +498 @@
 
 The installation base is defined by the :option:`--prefix` option; the
-:option:`--exec-prefix` option is not supported under Windows. Files are
-installed as follows:
-
-+------------------------------+---------------------------+-----------------------------+
-| Type of file                 | Installation Directory    | Override option             |
-+==============================+===========================+=============================+
-| pure module distribution     | :file:`{prefix}`          | :option:`--install-purelib` |
-+------------------------------+---------------------------+-----------------------------+
-| non-pure module distribution | :file:`{prefix}`          | :option:`--install-platlib` |
-+------------------------------+---------------------------+-----------------------------+
-| scripts                      | :file:`{prefix}\\Scripts` | :option:`--install-scripts` |
-+------------------------------+---------------------------+-----------------------------+
-| data                         | :file:`{prefix}\\Data`    | :option:`--install-data`    |
-+------------------------------+---------------------------+-----------------------------+
+:option:`--exec-prefix` option is not supported under Windows, which means that
+pure Python modules and extension modules are installed into the same location.
+Files are installed as follows:
+
+=============== ==========================================================
+Type of file    Installation directory
+=============== ==========================================================
+modules         :file:`{prefix}\\Lib\\site-packages`
+scripts         :file:`{prefix}\\Scripts`
+data            :file:`{prefix}`
+C headers       :file:`{prefix}\\Include\\{distname}`
+=============== ==========================================================
 
 
@@ -461 +523 @@
 case, you're creating a *custom installation scheme*.
 
-You probably noticed the column of "override options" in the tables describing
-the alternate installation schemes above.  Those options are how you define a
-custom installation scheme.  These override options can be relative, absolute,
+To create a custom installation scheme, you start with one of the alternate
+schemes and override some of the installation directories used for the various
+types of files, using these options:
+
+====================== =======================
+Type of file           Override option
+====================== =======================
+Python modules         ``--install-purelib``
+extension modules      ``--install-platlib``
+all modules            ``--install-lib``
+scripts                ``--install-scripts``
+data                   ``--install-data``
+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
-:option:`--prefix` and :option:`--exec-prefix` options.)
+``--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.)
 
 For example, say you're installing a module distribution to your home directory
@@ -494 +572 @@
 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,
-pure modules and non-pure modules (i.e., modules from a non-pure distribution).
-For example::
-
-   python setup.py install --install-purelib=Site --install-platlib=Site
-
-The specified installation directories are relative to :file:`{prefix}`.  Of
-course, you also have to ensure that these directories are in Python's module
-search path, such as by putting a :file:`.pth` file in :file:`{prefix}`.  See
-section :ref:`inst-search-path` to find out how to modify Python's search path.
+Python and extension modules, which can conveniently be both controlled by one
+option::
+
+   python setup.py install --install-lib=Site
+
+The specified installation directory is relative to :file:`{prefix}`.  Of
+course, you also have to ensure that this directory is in Python's module
+search path, such as by putting a :file:`.pth` file in a site directory (see
+:mod:`site`).  See section :ref:`inst-search-path` to find out how to modify
+Python's search path.
 
 If you want to define an entire installation scheme, you just have to supply all
@@ -554 +633 @@
    python setup.py install --install-base=/tmp
 
-would install pure modules to :file:`{/tmp/python/lib}` in the first case, and
-to :file:`{/tmp/lib}` in the second case.  (For the second case, you probably
+would install pure modules to :file:`/tmp/python/lib` in the first case, and
+to :file:`/tmp/lib` in the second case.  (For the second case, you probably
 want to supply an installation base of :file:`/tmp/python`.)
 
@@ -572 +651 @@
 
 
-.. XXX I'm not sure where this section should go.
+.. XXX Move this to Doc/using
 
 .. _inst-search-path:
@@ -695 +774 @@
 +--------------+-------------------------------------------------+-------+
 
+On all platforms, the "personal" file can be temporarily disabled by
+passing the `--no-user-cfg` option.
+
 Notes:
 
@@ -930 +1012 @@
 ^^^^^^^^^^^^^^^^^^^^^^
 
-These instructions only apply if you're using a version of Python prior  to
-2.4.1 with a MinGW prior to 3.0.0 (with binutils-2.13.90-20030111-1).
-
 This section describes the necessary steps to use Distutils with the GNU C/C++
 compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter
@@ -938 +1017 @@
 following steps.
 
-These compilers require some special libraries. This task is more complex than
+Not all extensions can be built with MinGW or Cygwin, but many can.  Extensions
+most likely to not work are those that use C++ or depend on Microsoft Visual C
+extensions.
+
+To let Distutils compile your extension with Cygwin you have to type::
+
+   python setup.py build --compiler=cygwin
+
+and for Cygwin in no-cygwin mode [#]_ or for MinGW type::
+
+   python setup.py build --compiler=mingw32
+
+If you want to use any of these options/compilers as default, you should
+consider writing it in your personal or system-wide configuration file for
+Distutils (see section :ref:`inst-config-files`.)
+
+Older Versions of Python and MinGW
+""""""""""""""""""""""""""""""""""
+The following instructions only apply if you're using a version of Python
+inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with
+binutils-2.13.90-20030111-1).
+
+These compilers require some special libraries.  This task is more complex than
 for Borland's C++, because there is no program to convert the library.  First
 you have to create a list of symbols which the Python DLL exports. (You can find
 a good program for this task at
-http://www.emmestech.com/software/pexports-0.43/download_pexports.html).
+http://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/).
 
 .. I don't understand what the next line means. --amk
@@ -968 +1069 @@
 normal libraries do.
 
-To let Distutils compile your extension with Cygwin you now have to type ::
-
-   python setup.py build --compiler=cygwin
-
-and for Cygwin in no-cygwin mode [#]_ or for MinGW type::
-
-   python setup.py build --compiler=mingw32
-
-If you want to use any of these options/compilers as default, you should
-consider to write it in your personal or system-wide configuration file for
-Distutils (see section :ref:`inst-config-files`.)
-
 
 .. seealso::