Lines Matching +full:- +full:- +full:base +full:- +full:directory
3 .. _install-index:
18 :ref:`What's New <distutils-deprecated>` entry for more information.
22 :ref:`installing-index`
33 recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__
37 .. _inst-intro:
54 See :ref:`installing-index` and :ref:`distributing-index` for more details.
59 .. _inst-new-standard:
62 ------------------------------------
67 in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or
68 :file:`widget-0.9.7.zip`. Next, the archive will unpack into a similarly named
69 directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the
78 (:menuselection:`Start --> Accessories`)::
84 install things in a non-standard way or customize the build process, you don't
89 .. _inst-standard-install:
94 As described in section :ref:`inst-new-standard`, building and installing a module
101 .. _inst-platform-variations:
104 -------------------
106 You should always run the setup command from the distribution root directory,
107 i.e. the top-level subdirectory that the module source distribution unpacks
109 :file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is::
111 gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
112 cd foo-1.0
115 On Windows, you'd probably download :file:`foo-1.0.zip`. If you downloaded the
117 :file:`C:\\Temp\\foo-1.0`; you can use either an archive manipulator with a
118 graphical user interface (such as WinZip) or a command-line tool (such as
122 cd c:\Temp\foo-1.0
126 .. _inst-splitting-up:
129 --------------------
132 prefer to work incrementally---especially useful if you want to customize the
133 build process, or if things are going wrong---you can use the setup script to do
135 will be done by different users---for example, you might want to build a module
137 it yourself, with super-user privileges).
146 first runs the :command:`build` command, which---in this case---quickly notices
147 that it has nothing to do, since everything in the :file:`build` directory is
148 up-to-date.
156 .. _inst-how-build-works:
159 ------------------
162 files to install into a *build directory*. By default, this is :file:`build`
164 to keep the source tree pristine, you can change the build directory with the
165 :option:`!--build-base` option. For example::
167 python setup.py build --build-base=/path/to/pybuild/foo-1.0
170 Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this
175 --- build/ --- lib/
177 --- build/ --- lib.<plat>/
181 platform and Python version. The first form, with just a :file:`lib` directory,
182 is used for "pure module distributions"---that is, module distributions that
185 directories, is used. In that case, the :file:`temp.{plat}` directory holds
187 installed. In either case, the :file:`lib` (or :file:`lib.{plat}`) directory
195 .. _inst-how-install-works:
198 ----------------------
204 directory.
206 If you don't choose an installation directory---i.e., if you just run ``setup.py
207 install``\ ---then the :command:`install` command installs to the standard
208 location for third-party Python modules. This location varies by platform and
210 Unix-based), it also depends on whether the module distribution being installed
211 is pure Python or contains extensions ("non-pure"):
215 +-----------------+-----------------------------------------------------+--------------------------…
218 …pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y…
219 +-----------------+-----------------------------------------------------+--------------------------…
220 | Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/pyt…
221 +-----------------+-----------------------------------------------------+--------------------------…
222 | Windows | :file:`{prefix}\\Lib\\site-packages` | :file:`C:\\Python{XY}\\Li…
223 +-----------------+-----------------------------------------------------+--------------------------…
229 :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on
230 Linux. If you build Python yourself on Linux (or any Unix-like system), the
231 default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`.
234 The default installation directory on Windows was :file:`C:\\Program
237 :file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python
238 is installed to, and where it finds its libraries at run-time. They are always
241 :file:`{exec-prefix}` by running Python in interactive mode and typing a few
243 Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
247 :file:`{prefix}` and :file:`{exec-prefix}`:
249 .. code-block:: pycon
269 installations in section :ref:`inst-alt-install`. If you want to customize your
270 installation directories more heavily, see section :ref:`inst-custom-install` on
274 .. _inst-alt-install:
280 the standard location for third-party Python modules. For example, on a Unix
281 system you might not have permission to write to the standard third-party module
282 directory. Or you might wish to try out a module before making it a standard
284 a distribution already present: you want to make sure your existing base of
289 that you supply a base directory for the installation, and the
291 scheme*) under this base directory in which to install files. The details
296 can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or
297 ``--install-base`` and ``--install-platbase``, but you can't mix from these
301 .. _inst-alt-install-user:
304 ---------------------------------------
307 have write permission to the global site-packages directory or don't want to
310 python setup.py install --user
318 Type of file Installation directory
320 modules :file:`{userbase}/lib/python{X.Y}/site-packages`
329 Type of file Installation directory
331 modules :file:`{userbase}\\Python{XY}\\site-packages`
338 that the user site-packages directory is under normal conditions always included
343 The :command:`build_ext` command also has a ``--user`` option to add
349 .. _inst-alt-install-home:
352 ---------------------------------------
356 "home" directory on Unix, since it's not unusual for a Unix user to make their
357 home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`.
363 python setup.py install --home=<dir>
365 where you can supply any directory you like for the :option:`!--home` option. On
367 will expand this to your home directory::
369 python setup.py install --home=~
372 to :ref:`modify Python's search path <inst-search-path>` or edit
376 The :option:`!--home` option defines the installation base directory. Files are
377 installed to the following directories under the installation base as follows:
380 Type of file Installation directory
391 .. _inst-alt-install-prefix-unix:
394 ------------------------------------------------
398 into the third-party module directory of a different Python installation (or
400 trifle unusual, it is---that's why the user and home schemes come before. However,
405 since in those cases Python is part of "the system" rather than a local add-on.
410 /usr/bin/python setup.py install --prefix=/usr/local
413 remote directory is different from the name used to read it: for example, the
419 /usr/local/bin/python setup.py install --prefix=/mnt/@server/export
421 In either case, the :option:`!--prefix` option defines the installation base, and
422 the :option:`!--exec-prefix` option defines the platform-specific installation
423 base, which is used for platform-specific files. (Currently, this just means
424 non-pure module distributions, but could be expanded to C libraries, binary
425 executables, etc.) If :option:`!--exec-prefix` is not supplied, it defaults to
426 :option:`!--prefix`. Files are installed as follows:
429 Type of file Installation directory
431 Python modules :file:`{prefix}/lib/python{X.Y}/site-packages`
432 extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages`
438 There is no requirement that :option:`!--prefix` or :option:`!--exec-prefix`
443 standard Unix installation uses the prefix scheme, but with :option:`!--prefix`
444 and :option:`!--exec-prefix` supplied by Python itself as ``sys.prefix`` and
457 if your :option:`!--prefix` and :option:`!--exec-prefix` don't even point to an
461 .. _inst-alt-install-prefix-windows:
464 ---------------------------------------------------
466 Windows has no concept of a user's home directory, and since the standard Python
467 installation under Windows is simpler than under Unix, the :option:`!--prefix`
471 python setup.py install --prefix="\Temp\Python"
473 to install modules to the :file:`\\Temp\\Python` directory on the current drive.
475 The installation base is defined by the :option:`!--prefix` option; the
476 :option:`!--exec-prefix` option is not supported under Windows, which means that
481 Type of file Installation directory
483 modules :file:`{prefix}\\Lib\\site-packages`
490 .. _inst-custom-install:
496 :ref:`inst-alt-install` just don't do what you want. You might want to tweak just
497 one or two directories while keeping everything under the same base directory,
508 Python modules ``--install-purelib``
509 extension modules ``--install-platlib``
510 all modules ``--install-lib``
511 scripts ``--install-scripts``
512 data ``--install-data``
513 C headers ``--install-headers``
517 or explicitly defined in terms of one of the installation base directories.
518 (There are two installation base directories, and they are normally the
519 same---they only differ when you use the Unix "prefix scheme" and supply
520 different ``--prefix`` and ``--exec-prefix`` options; using ``--install-lib``
521 will override values computed or given for ``--install-purelib`` and
522 ``--install-platlib``, and is recommended for schemes that don't make a
525 For example, say you're installing a module distribution to your home directory
526 under Unix---but you want scripts to go in :file:`~/scripts` rather than
527 :file:`~/bin`. As you might expect, you can override this directory with the
528 :option:`!--install-scripts` option; in this case, it makes most sense to supply
529 a relative path, which will be interpreted relative to the installation base
530 directory (your home directory, in this case)::
532 python setup.py install --home=~ --install-scripts=scripts
537 :file:`/usr/local/bin` instead, you would supply this absolute directory for the
538 :option:`!--install-scripts` option::
540 python setup.py install --install-scripts=/usr/local/bin
543 whatever your Python interpreter was installed with--- :file:`/usr/local/python`
546 If you maintain Python on Windows, you might want third-party modules to live in
549 directory---you just have to remember that there are two types of modules
553 python setup.py install --install-lib=Site
555 The specified installation directory is relative to :file:`{prefix}`. Of
556 course, you also have to ensure that this directory is in Python's module
557 search path, such as by putting a :file:`.pth` file in a site directory (see
558 :mod:`site`). See section :ref:`inst-search-path` to find out how to modify
562 of the installation directory options. The recommended way to do this is to
564 module-related files under :file:`python` in your home directory, and you want a
565 separate directory for each platform that you use your home directory from, you
568 python setup.py install --home=~ \
569 --install-purelib=python/lib \
570 --install-platlib=python/lib.$PLAT \
571 --install-scripts=python/scripts
572 --install-data=python/data
576 python setup.py install --home=~/python \
577 --install-purelib=lib \
578 --install-platlib='lib.$PLAT' \
579 --install-scripts=scripts
580 --install-data=data
582 ``$PLAT`` is not (necessarily) an environment variable---it will be expanded by
588 into your Distutils config file (see section :ref:`inst-config-files`):
590 .. code-block:: ini
593 install-base=$HOME
594 install-purelib=python/lib
595 install-platlib=python/lib.$PLAT
596 install-scripts=python/scripts
597 install-data=python/data
601 .. code-block:: ini
604 install-base=$HOME/python
605 install-purelib=lib
606 install-platlib=lib.$PLAT
607 install-scripts=scripts
608 install-data=data
611 base directory when you run the setup script. For example, ::
613 python setup.py install --install-base=/tmp
617 want to supply an installation base of :file:`/tmp/python`.)
626 the Distutils are the only ones you can use.) See section :ref:`inst-config-files`
629 .. note:: When a :ref:`virtual environment <venv-def>` is activated, any options
634 .. XXX need some Windows examples---when would custom installation schemes be
640 .. _inst-search-path:
643 ------------------------------
653 [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
657 ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
658 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
659 '/usr/local/lib/python2.3/site-packages']
662 The null string in ``sys.path`` represents the current working directory.
665 :file:`{...}/site-packages/` directory, but you may want to install Python
666 modules into some arbitrary directory. For example, your site may have a
668 Add-on Python modules might then belong in :file:`/www/python`, and in order to
669 import them, this directory must be added to ``sys.path``. There are several
670 different ways to add the directory.
672 The most convenient way is to add a path configuration file to a directory
673 that's already on Python's path, usually to the :file:`.../site-packages/`
674 directory. Path configuration files have an extension of :file:`.pth`, and each
681 directory containing the :file:`.pth` file. See the documentation of
686 imported when the Python interpreter is executed, unless the :option:`-S` switch
690 .. code-block:: python
704 '/www/python/lib/pythonX.Y/plat-linux2', ...]``.
717 .. _inst-config-files:
725 configuration files, which will be consulted before the command-line is parsed.
727 command-line will in turn override configuration files. Furthermore, if
732 .. _inst-config-filenames:
735 ----------------------------------
741 +--------------+----------------------------------------------------------+-------+
745 +--------------+----------------------------------------------------------+-------+
747 +--------------+----------------------------------------------------------+-------+
749 +--------------+----------------------------------------------------------+-------+
753 +--------------+-------------------------------------------------+-------+
757 +--------------+-------------------------------------------------+-------+
759 +--------------+-------------------------------------------------+-------+
761 +--------------+-------------------------------------------------+-------+
764 passing the ``--no-user-cfg`` option.
769 Strictly speaking, the system-wide configuration file lives in the directory
772 :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system
777 home directory will be determined with the :func:`getpwuid` function from the
782 I.e., in the current directory (usually the location of the setup script).
789 part of the standard library---so the system configuration file would be
800 .. _inst-config-syntax:
803 ----------------------
813 .. code-block:: ini
825 You could override the default "build base" directory and make the
829 .. code-block:: ini
832 build-base=blib
835 which corresponds to the command-line arguments ::
837 python setup.py build --build-base=blib --force
839 except that including the :command:`build` command on the command-line means
846 :option:`!--help` option, e.g.::
848 python setup.py build --help
851 :option:`!--help` without a command::
853 python setup.py --help
858 .. _inst-building-ext:
871 .. _inst-tweak-flags:
874 ------------------------------
880 cross-compile Python.
908 :option:`!-I`, :option:`!-D`, :option:`!-U` or :option:`!-C`.
910 * *library* is anything ending in :file:`.a` or beginning with :option:`!-l` or
911 :option:`!-L`.
920 :option:`!-lm` to the line::
922 foo foomodule.c -lm
925 the :option:`!-Xcompiler` *arg* and :option:`!-Xlinker` *arg* options::
927 foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
929 The next option after :option:`!-Xcompiler` and :option:`!-Xlinker` will be
931 be passed the :option:`!-o32` option, and the linker will be passed
932 :option:`!-shared`. If a compiler option requires an argument, you'll have to
933 supply multiple :option:`!-Xcompiler` options; for example, to pass ``-x c++``
934 the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``.
941 .. _inst-non-ms-compilers:
943 Using non-Microsoft compilers on Windows
944 ----------------------------------------
961 .. Should we mention that users have to create cfg-files for the compiler?
969 :file:`python25.lib` is in the :file:`Libs` directory of your Python
984 python setup.py build --compiler=bcpp
987 this in your personal or system-wide configuration file for Distutils (see
988 section :ref:`inst-config-files`.)
998 Document describing how to use Borland's free command-line C++ compiler to build
1016 python setup.py build --compiler=cygwin
1018 and for Cygwin in no-cygwin mode [#]_ or for MinGW type::
1020 python setup.py build --compiler=mingw32
1023 consider writing it in your personal or system-wide configuration file for
1024 Distutils (see section :ref:`inst-config-files`.)
1030 binutils-2.13.90-20030111-1).
1038 .. I don't understand what the next line means. --amk
1047 me" installation, it will appear in the root of the installation directory. In
1048 a shared installation, it will be located in the system directory.
1052 /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
1054 The resulting library has to be placed in the same directory as
1055 :file:`python25.lib`. (Should be the :file:`libs` directory under your Python
1056 installation directory.)
1071 .. [#] This also means you could replace all existing COFF-libraries with OMF-libraries