Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 54a1d05

Browse files
merwokmerwok
committed
Branch merge
2 parents db79e95 + 6ef038e commit 54a1d05

5 files changed

Lines changed: 255 additions & 97 deletions

File tree

‎Doc/install/index.rst‎

Lines changed: 132 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -279,6 +279,14 @@ statements shown below, and get the output as shown, to find out my
279279
>>> sys.exec_prefix
280280
'/usr'
281281

282+
A few other placeholders are used in this document: :file:`{X.Y}` stands for the
283+
version of Python, for example ``3.2``; :file:`{abiflags}` will be replaced by
284+
the value of :data:`sys.abiflags` or the empty string for platforms which don't
285+
define ABI flags; :file:`{distname}` will be replaced by the name of the module
286+
distribution being installed. Dots and capitalization are important in the
287+
paths; for example, a value that uses ``python3.2`` on UNIX will typically use
288+
``Python32`` on Windows.
289+
282290
If you don't want to install modules to the standard location, or if you don't
283291
have permission to write there, then you need to read about alternate
284292
installations in section :ref:`inst-alt-install`. If you want to customize your
@@ -307,8 +315,61 @@ scheme*) under this base directory in which to install files. The details
307315
differ across platforms, so read whichever of the following sections applies to
308316
you.
309317

318+
Note that the various alternate installation schemes are mutually exclusive: you
319+
can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or
320+
``--install-base`` and ``--install-platbase``, but you can't mix from these
321+
groups.
322+
323+
324+
.. _inst-alt-install-user:
325+
326+
Alternate installation: the user scheme
327+
---------------------------------------
328+
329+
This scheme is designed to be the most convenient solution for users that don't
330+
have write permission to the global site-packages directory or don't want to
331+
install into it. It is enabled with a simple option::
332+
333+
python setup.py install --user
334+
335+
Files will be installed into subdirectories of :data:`site.USER_BASE` (written
336+
as :file:`{userbase}` hereafter). This scheme installs pure Python modules and
337+
extension modules in the same location (also known as :data:`site.USER_SITE`).
338+
Here are the values for UNIX, including Mac OS X:
339+
340+
=============== ===========================================================
341+
Type of file Installation directory
342+
=============== ===========================================================
343+
modules :file:`{userbase}/lib/python{X.Y}/site-packages`
344+
scripts :file:`{userbase}/bin`
345+
data :file:`{userbase}`
346+
C headers :file:`{userbase}/include/python{X.Y}{abiflags}/{distname}`
347+
=============== ===========================================================
348+
349+
And here are the values used on Windows:
350+
351+
=============== ===========================================================
352+
Type of file Installation directory
353+
=============== ===========================================================
354+
modules :file:`{userbase}\\Python{XY}\\site-packages`
355+
scripts :file:`{userbase}\\Scripts`
356+
data :file:`{userbase}`
357+
C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}`
358+
=============== ===========================================================
359+
360+
The advantage of using this scheme compared to the other ones described below is
361+
that the user site-packages directory is under normal conditions always included
362+
in :data:`sys.path` (see :mod:`site` for more information), which means that
363+
there is no additional step to perform after running the :file:`setup.py` script
364+
to finalize the installation.
365+
366+
The :command:`build_ext` command also has a ``--user`` option to add
367+
:file:`{userbase}/include` to the compiler search path for header files and
368+
:file:`{userbase}/lib` to the compiler search path for libraries as well as to
369+
the runtime search path for shared C libraries (rpath).
310370

311-
.. _inst-alt-install-prefix:
371+
372+
.. _inst-alt-install-home:
312373

313374
Alternate installation: the home scheme
314375
---------------------------------------
@@ -330,23 +391,27 @@ will expand this to your home directory::
330391

331392
python setup.py install --home=~
332393

394+
To make Python find the distributions installed with this scheme, you may have
395+
to :ref:`modify Python's search path <inst-search-path>` or edit
396+
:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit
397+
:data:`sys.path`.
398+
333399
The :option:`--home` option defines the installation base directory. Files are
334400
installed to the following directories under the installation base as follows:
335401

336-
+------------------------------+---------------------------+-----------------------------+
337-
| Type of file | Installation Directory | Override option |
338-
+==============================+===========================+=============================+
339-
| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` |
340-
+------------------------------+---------------------------+-----------------------------+
341-
| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` |
342-
+------------------------------+---------------------------+-----------------------------+
343-
| scripts | :file:`{home}/bin` | :option:`--install-scripts` |
344-
+------------------------------+---------------------------+-----------------------------+
345-
| data | :file:`{home}/share` | :option:`--install-data` |
346-
+------------------------------+---------------------------+-----------------------------+
402+
=============== ===========================================================
403+
Type of file Installation directory
404+
=============== ===========================================================
405+
modules :file:`{home}/lib/python`
406+
scripts :file:`{home}/bin`
407+
data :file:`{home}`
408+
C headers :file:`{home}/include/python/{distname}`
409+
=============== ===========================================================
347410

411+
(Mentally replace slashes with backslashes if you're on Windows.)
348412

349-
.. _inst-alt-install-home:
413+
414+
.. _inst-alt-install-prefix-unix:
350415

351416
Alternate installation: Unix (the prefix scheme)
352417
------------------------------------------------
@@ -355,7 +420,7 @@ The "prefix scheme" is useful when you wish to use one Python installation to
355420
perform the build/install (i.e., to run the setup script), but install modules
356421
into the third-party module directory of a different Python installation (or
357422
something that looks like a different Python installation). If this sounds a
358-
trifle unusual, it is---that's why the "home scheme" comes first. However,
423+
trifle unusual, it is---that's why the user and home schemes come before. However,
359424
there are at least two known cases where the prefix scheme will be useful.
360425

361426
First, consider that many Linux distributions put Python in :file:`/usr`, rather
@@ -383,17 +448,15 @@ non-pure module distributions, but could be expanded to C libraries, binary
383448
executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to
384449
:option:`--prefix`. Files are installed as follows:
385450

386-
+------------------------------+-----------------------------------------------------+-----------------------------+
387-
| Type of file | Installation Directory | Override option |
388-
+==============================+=====================================================+=============================+
389-
| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` |
390-
+------------------------------+-----------------------------------------------------+-----------------------------+
391-
| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` |
392-
+------------------------------+-----------------------------------------------------+-----------------------------+
393-
| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` |
394-
+------------------------------+-----------------------------------------------------+-----------------------------+
395-
| data | :file:`{prefix}/share` | :option:`--install-data` |
396-
+------------------------------+-----------------------------------------------------+-----------------------------+
451+
================= ==========================================================
452+
Type of file Installation directory
453+
================= ==========================================================
454+
Python modules :file:`{prefix}/lib/python{X.Y}/site-packages`
455+
extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages`
456+
scripts :file:`{prefix}/bin`
457+
data :file:`{prefix}`
458+
C headers :file:`{prefix}/include/python{X.Y}{abiflags}/{distname}`
459+
================= ==========================================================
397460

398461
There is no requirement that :option:`--prefix` or :option:`--exec-prefix`
399462
actually point to an alternate Python installation; if the directories listed
@@ -418,7 +481,7 @@ if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an
418481
alternate Python installation, this is immaterial.)
419482

420483

421-
.. _inst-alt-install-windows:
484+
.. _inst-alt-install-prefix-windows:
422485

423486
Alternate installation: Windows (the prefix scheme)
424487
---------------------------------------------------
@@ -433,20 +496,18 @@ locations on Windows. ::
433496
to install modules to the :file:`\\Temp\\Python` directory on the current drive.
434497

435498
The installation base is defined by the :option:`--prefix` option; the
436-
:option:`--exec-prefix` option is not supported under Windows. Files are
437-
installed as follows:
438-
439-
+------------------------------+---------------------------+-----------------------------+
440-
| Type of file | Installation Directory | Override option |
441-
+==============================+===========================+=============================+
442-
| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` |
443-
+------------------------------+---------------------------+-----------------------------+
444-
| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` |
445-
+------------------------------+---------------------------+-----------------------------+
446-
| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` |
447-
+------------------------------+---------------------------+-----------------------------+
448-
| data | :file:`{prefix}\\Data` | :option:`--install-data` |
449-
+------------------------------+---------------------------+-----------------------------+
499+
:option:`--exec-prefix` option is not supported under Windows, which means that
500+
pure Python modules and extension modules are installed into the same location.
501+
Files are installed as follows:
502+
503+
=============== ==========================================================
504+
Type of file Installation directory
505+
=============== ==========================================================
506+
modules :file:`{prefix}\\Lib\\site-packages`
507+
scripts :file:`{prefix}\\Scripts`
508+
data :file:`{prefix}`
509+
C headers :file:`{prefix}\\Include\\{distname}`
510+
=============== ==========================================================
450511

451512

452513
.. _inst-custom-install:
@@ -460,13 +521,29 @@ one or two directories while keeping everything under the same base directory,
460521
or you might want to completely redefine the installation scheme. In either
461522
case, you're creating a *custom installation scheme*.
462523

463-
You probably noticed the column of "override options" in the tables describing
464-
the alternate installation schemes above. Those options are how you define a
465-
custom installation scheme. These override options can be relative, absolute,
524+
To create a custom installation scheme, you start with one of the alternate
525+
schemes and override some of the installation directories used for the various
526+
types of files, using these options:
527+
528+
====================== =======================
529+
Type of file Override option
530+
====================== =======================
531+
Python modules ``--install-purelib``
532+
extension modules ``--install-platlib``
533+
all modules ``--install-lib``
534+
scripts ``--install-scripts``
535+
data ``--install-data``
536+
C headers ``--install-headers``
537+
====================== =======================
538+
539+
These override options can be relative, absolute,
466540
or explicitly defined in terms of one of the installation base directories.
467541
(There are two installation base directories, and they are normally the same---
468542
they only differ when you use the Unix "prefix scheme" and supply different
469-
:option:`--prefix` and :option:`--exec-prefix` options.)
543+
``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will
544+
override values computed or given for ``--install-purelib`` and
545+
``--install-platlib``, and is recommended for schemes that don't make a
546+
difference between Python and extension modules.)
470547

471548
For example, say you're installing a module distribution to your home directory
472549
under Unix---but you want scripts to go in :file:`~/scripts` rather than
@@ -493,15 +570,16 @@ If you maintain Python on Windows, you might want third-party modules to live in
493570
a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}`
494571
itself. This is almost as easy as customizing the script installation directory
495572
---you just have to remember that there are two types of modules to worry about,
496-
pure modules and non-pure modules (i.e., modules from a non-pure distribution).
497-
For example::
573+
Python and extension modules, which can conveniently be both controlled by one
574+
option::
498575

499-
python setup.py install --install-purelib=Site --install-platlib=Site
576+
python setup.py install --install-lib=Site
500577

501-
The specified installation directories are relative to :file:`{prefix}`. Of
502-
course, you also have to ensure that these directories are in Python's module
503-
search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See
504-
section :ref:`inst-search-path` to find out how to modify Python's search path.
578+
The specified installation directory is relative to :file:`{prefix}`. Of
579+
course, you also have to ensure that this directory is in Python's module
580+
search path, such as by putting a :file:`.pth` file in a site directory (see
581+
:mod:`site`). See section :ref:`inst-search-path` to find out how to modify
582+
Python's search path.
505583

506584
If you want to define an entire installation scheme, you just have to supply all
507585
of the installation directory options. The recommended way to do this is to
@@ -553,8 +631,8 @@ base directory when you run the setup script. For example, ::
553631

554632
python setup.py install --install-base=/tmp
555633

556-
would install pure modules to :file:`{/tmp/python/lib}` in the first case, and
557-
to :file:`{/tmp/lib}` in the second case. (For the second case, you probably
634+
would install pure modules to :file:`/tmp/python/lib` in the first case, and
635+
to :file:`/tmp/lib` in the second case. (For the second case, you probably
558636
want to supply an installation base of :file:`/tmp/python`.)
559637

560638
You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample
@@ -571,7 +649,7 @@ for details.
571649
needed on those platforms?
572650
573651
574-
.. XXX I'm not sure where this section should go.
652+
.. XXX Move this to Doc/using
575653
576654
.. _inst-search-path:
577655

0 commit comments

Comments
 (0)