Lines Matching +full:build +full:- +full:pristine
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:
48 In the many years since Python 2.0 was released, tightly coupling the build
51 ``pip`` package installer and the ``setuptools`` build system, rather than
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`)::
82 If all these things are true, then you already know how to build and install the
84 install things in a non-standard way or customize the build process, you don't
89 .. _inst-standard-install:
91 Standard Build and Install
94 As described in section :ref:`inst-new-standard`, building and installing a module
101 .. _inst-platform-variations:
104 -------------------
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
134 one thing at a time. This is particularly helpful when the build and install
135 will be done by different users---for example, you might want to build a module
137 it yourself, with super-user privileges).
139 For example, you can build everything in one step, and then install everything
142 python setup.py build
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 ------------------
161 As implied above, the :command:`build` command is responsible for putting the
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
173 The default layout for the build tree is as follows::
175 --- build/ --- lib/
177 --- build/ --- lib.<plat>/
182 is used for "pure module distributions"---that is, module distributions that
195 .. _inst-how-install-works:
198 ----------------------
200 After the :command:`build` command runs (whether you run it explicitly, or the
203 :file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation
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`.
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
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
320 modules :file:`{userbase}/lib/python{X.Y}/site-packages`
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 ---------------------------------------
354 The idea behind the "home scheme" is that you build and maintain a personal
363 python setup.py install --home=<dir>
365 where you can supply any directory you like for the :option:`!--home` option. On
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
391 .. _inst-alt-install-prefix-unix:
394 ------------------------------------------------
397 perform the build/install (i.e., to run the setup script), but install modules
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
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:
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
454 in this way is compatible with the interpreter used to build them. The best way
456 (possibly different builds, or possibly copies of the same build). (Of course,
457 if your :option:`!--prefix` and :option:`!--exec-prefix` don't even point to an
461 .. _inst-alt-install-prefix-windows:
464 ---------------------------------------------------
467 installation under Windows is simpler than under Unix, the :option:`!--prefix`
471 python setup.py install --prefix="\Temp\Python"
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
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
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``
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
526 under Unix---but you want scripts to go in :file:`~/scripts` rather than
528 :option:`!--install-scripts` option; in this case, it makes most sense to supply
532 python setup.py install --home=~ --install-scripts=scripts
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
558 :mod:`site`). See section :ref:`inst-search-path` to find out how to modify
564 module-related files under :file:`python` in your home directory, and you want a
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
613 python setup.py install --install-base=/tmp
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']
665 :file:`{...}/site-packages/` directory, but you may want to install Python
668 Add-on Python modules might then belong in :file:`/www/python`, and in order to
673 that's already on Python's path, usually to the :file:`.../site-packages/`
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
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
826 :command:`build\*` commands always forcibly rebuild all files with the
829 .. code-block:: ini
831 [build]
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.
889 to build. Each line in a :file:`Setup` describes a single module. Lines have
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`.
914 add it by editing the :file:`Setup` file and running ``python setup.py build``.
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?
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
1052 /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
1071 .. [#] This also means you could replace all existing COFF-libraries with OMF-libraries