mirror of https://github.com/python/cpython
gh-85454: Remove distutils documentation (#95239)
Most places now refer to setuptools or link to setuptools documentation. Some examples like zipapp need to be updated later.
This commit is contained in:
Christian Heimes
GitHub
parent
d58be48369
commit
a566912049
|
|
@ -27,5 +27,4 @@
|
|||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
distutils/index.rst
|
||||
install/index.rst
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
.. note::
|
||||
|
||||
This document is being retained solely until the ``setuptools`` documentation
|
||||
at https://setuptools.readthedocs.io/en/latest/setuptools.html
|
||||
independently covers all of the relevant information currently included here.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,392 +0,0 @@
|
|||
.. _built-dist:
|
||||
|
||||
****************************
|
||||
Creating Built Distributions
|
||||
****************************
|
||||
|
||||
.. include:: ./_setuptools_disclaimer.rst
|
||||
|
||||
A "built distribution" is what you're probably used to thinking of either as a
|
||||
"binary package" or an "installer" (depending on your background). It's not
|
||||
necessarily binary, though, because it might contain only Python source code
|
||||
and/or byte-code; and we don't call it a package, because that word is already
|
||||
spoken for in Python. (And "installer" is a term specific to the world of
|
||||
mainstream desktop systems.)
|
||||
|
||||
A built distribution is how you make life as easy as possible for installers of
|
||||
your module distribution: for users of RPM-based Linux systems, it's a binary
|
||||
RPM; for Windows users, it's an executable installer; for Debian-based Linux
|
||||
users, it's a Debian package; and so forth. Obviously, no one person will be
|
||||
able to create built distributions for every platform under the sun, so the
|
||||
Distutils are designed to enable module developers to concentrate on their
|
||||
specialty---writing code and creating source distributions---while an
|
||||
intermediary species called *packagers* springs up to turn source distributions
|
||||
into built distributions for as many platforms as there are packagers.
|
||||
|
||||
Of course, the module developer could be their own packager; or the packager could
|
||||
be a volunteer "out there" somewhere who has access to a platform which the
|
||||
original developer does not; or it could be software periodically grabbing new
|
||||
source distributions and turning them into built distributions for as many
|
||||
platforms as the software has access to. Regardless of who they are, a packager
|
||||
uses the setup script and the :command:`bdist` command family to generate built
|
||||
distributions.
|
||||
|
||||
As a simple example, if I run the following command in the Distutils source
|
||||
tree::
|
||||
|
||||
python setup.py bdist
|
||||
|
||||
then the Distutils builds my module distribution (the Distutils itself in this
|
||||
case), does a "fake" installation (also in the :file:`build` directory), and
|
||||
creates the default type of built distribution for my platform. The default
|
||||
format for built distributions is a "dumb" tar file on Unix, and a simple
|
||||
executable installer on Windows. (That tar file is considered "dumb" because it
|
||||
has to be unpacked in a specific location to work.)
|
||||
|
||||
Thus, the above command on a Unix system creates
|
||||
:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place
|
||||
installs the Distutils just as though you had downloaded the source distribution
|
||||
and run ``python setup.py install``. (The "right place" is either the root of
|
||||
the filesystem or Python's :file:`{prefix}` directory, depending on the options
|
||||
given to the :command:`bdist_dumb` command; the default is to make dumb
|
||||
distributions relative to :file:`{prefix}`.)
|
||||
|
||||
Obviously, for pure Python distributions, this isn't any simpler than just
|
||||
running ``python setup.py install``\ ---but for non-pure distributions, which
|
||||
include extensions that would need to be compiled, it can mean the difference
|
||||
between someone being able to use your extensions or not. And creating "smart"
|
||||
built distributions, such as an RPM package or an executable installer for
|
||||
Windows, is far more convenient for users even if your distribution doesn't
|
||||
include any extensions.
|
||||
|
||||
The :command:`bdist` command has a :option:`!--formats` option, similar to the
|
||||
:command:`sdist` command, which you can use to select the types of built
|
||||
distribution to generate: for example, ::
|
||||
|
||||
python setup.py bdist --format=zip
|
||||
|
||||
would, when run on a Unix system, create
|
||||
:file:`Distutils-1.0.{plat}.zip`\ ---again, this archive would be unpacked
|
||||
from the root directory to install the Distutils.
|
||||
|
||||
The available formats for built distributions are:
|
||||
|
||||
+-------------+------------------------------+---------+
|
||||
| Format | Description | Notes |
|
||||
+=============+==============================+=========+
|
||||
| ``gztar`` | gzipped tar file | \(1) |
|
||||
| | (:file:`.tar.gz`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``bztar`` | bzipped tar file | |
|
||||
| | (:file:`.tar.bz2`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``xztar`` | xzipped tar file | |
|
||||
| | (:file:`.tar.xz`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``ztar`` | compressed tar file | \(3) |
|
||||
| | (:file:`.tar.Z`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``tar`` | tar file (:file:`.tar`) | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``zip`` | zip file (:file:`.zip`) | (2),(4) |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``rpm`` | RPM | \(5) |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``pkgtool`` | Solaris :program:`pkgtool` | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``sdux`` | HP-UX :program:`swinstall` | |
|
||||
+-------------+------------------------------+---------+
|
||||
| ``msi`` | Microsoft Installer. | |
|
||||
+-------------+------------------------------+---------+
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
Added support for the ``xztar`` format.
|
||||
|
||||
|
||||
Notes:
|
||||
|
||||
(1)
|
||||
default on Unix
|
||||
|
||||
(2)
|
||||
default on Windows
|
||||
|
||||
(3)
|
||||
requires external :program:`compress` utility.
|
||||
|
||||
(4)
|
||||
requires either external :program:`zip` utility or :mod:`zipfile` module (part
|
||||
of the standard Python library since Python 1.6)
|
||||
|
||||
(5)
|
||||
requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm
|
||||
--version`` to find out which version you have)
|
||||
|
||||
You don't have to use the :command:`bdist` command with the :option:`!--formats`
|
||||
option; you can also use the command that directly implements the format you're
|
||||
interested in. Some of these :command:`bdist` "sub-commands" actually generate
|
||||
several similar formats; for instance, the :command:`bdist_dumb` command
|
||||
generates all the "dumb" archive formats (``tar``, ``gztar``, ``bztar``,
|
||||
``xztar``, ``ztar``, and ``zip``), and :command:`bdist_rpm` generates both
|
||||
binary and source RPMs. The :command:`bdist` sub-commands, and the formats
|
||||
generated by each, are:
|
||||
|
||||
+--------------------------+-------------------------------------+
|
||||
| Command | Formats |
|
||||
+==========================+=====================================+
|
||||
| :command:`bdist_dumb` | tar, gztar, bztar, xztar, ztar, zip |
|
||||
+--------------------------+-------------------------------------+
|
||||
| :command:`bdist_rpm` | rpm, srpm |
|
||||
+--------------------------+-------------------------------------+
|
||||
|
||||
The following sections give details on the individual :command:`bdist_\*`
|
||||
commands.
|
||||
|
||||
|
||||
.. .. _creating-dumb:
|
||||
|
||||
.. Creating dumb built distributions
|
||||
.. =================================
|
||||
|
||||
.. XXX Need to document absolute vs. prefix-relative packages here, but first
|
||||
I have to implement it!
|
||||
|
||||
|
||||
.. _creating-rpms:
|
||||
|
||||
Creating RPM packages
|
||||
=====================
|
||||
|
||||
The RPM format is used by many popular Linux distributions, including Red Hat,
|
||||
SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux
|
||||
distributions) is your usual environment, creating RPM packages for other users
|
||||
of that same distribution is trivial. Depending on the complexity of your module
|
||||
distribution and differences between Linux distributions, you may also be able
|
||||
to create RPMs that work on different RPM-based distributions.
|
||||
|
||||
The usual way to create an RPM of your module distribution is to run the
|
||||
:command:`bdist_rpm` command::
|
||||
|
||||
python setup.py bdist_rpm
|
||||
|
||||
or the :command:`bdist` command with the :option:`!--format` option::
|
||||
|
||||
python setup.py bdist --formats=rpm
|
||||
|
||||
The former allows you to specify RPM-specific options; the latter allows you to
|
||||
easily specify multiple formats in one run. If you need to do both, you can
|
||||
explicitly specify multiple :command:`bdist_\*` commands and their options::
|
||||
|
||||
python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>"
|
||||
|
||||
Creating RPM packages is driven by a :file:`.spec` file, much as using the
|
||||
Distutils is driven by the setup script. To make your life easier, the
|
||||
:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the
|
||||
information you supply in the setup script, on the command line, and in any
|
||||
Distutils configuration files. Various options and sections in the
|
||||
:file:`.spec` file are derived from options in the setup script as follows:
|
||||
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| RPM :file:`.spec` file option or section | Distutils setup script option |
|
||||
+==========================================+==============================================+
|
||||
| Name | ``name`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Summary (in preamble) | ``description`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Version | ``version`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Vendor | ``author`` and ``author_email``, |
|
||||
| | or --- & ``maintainer`` and |
|
||||
| | ``maintainer_email`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Copyright | ``license`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| Url | ``url`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
| %description (section) | ``long_description`` |
|
||||
+------------------------------------------+----------------------------------------------+
|
||||
|
||||
Additionally, there are many options in :file:`.spec` files that don't have
|
||||
corresponding options in the setup script. Most of these are handled through
|
||||
options to the :command:`bdist_rpm` command as follows:
|
||||
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value |
|
||||
| or section | | |
|
||||
+===============================+=============================+=========================+
|
||||
| Release | ``release`` | "1" |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Group | ``group`` | "Development/Libraries" |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Vendor | ``vendor`` | (see above) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Packager | ``packager`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Provides | ``provides`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Requires | ``requires`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Conflicts | ``conflicts`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Obsoletes | ``obsoletes`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Distribution | ``distribution_name`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| BuildRequires | ``build_requires`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
| Icon | ``icon`` | (none) |
|
||||
+-------------------------------+-----------------------------+-------------------------+
|
||||
|
||||
Obviously, supplying even a few of these options on the command-line would be
|
||||
tedious and error-prone, so it's usually best to put them in the setup
|
||||
configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If
|
||||
you distribute or package many Python module distributions, you might want to
|
||||
put options that apply to all of them in your personal Distutils configuration
|
||||
file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable
|
||||
this file, you can pass the :option:`!--no-user-cfg` option to :file:`setup.py`.
|
||||
|
||||
There are three steps to building a binary RPM package, all of which are
|
||||
handled automatically by the Distutils:
|
||||
|
||||
#. create a :file:`.spec` file, which describes the package (analogous to the
|
||||
Distutils setup script; in fact, much of the information in the setup script
|
||||
winds up in the :file:`.spec` file)
|
||||
|
||||
#. create the source RPM
|
||||
|
||||
#. create the "binary" RPM (which may or may not contain binary code, depending
|
||||
on whether your module distribution contains Python extensions)
|
||||
|
||||
Normally, RPM bundles the last two steps together; when you use the Distutils,
|
||||
all three steps are typically bundled together.
|
||||
|
||||
If you wish, you can separate these three steps. You can use the
|
||||
:option:`!--spec-only` option to make :command:`bdist_rpm` just create the
|
||||
:file:`.spec` file and exit; in this case, the :file:`.spec` file will be
|
||||
written to the "distribution directory"---normally :file:`dist/`, but
|
||||
customizable with the :option:`!--dist-dir` option. (Normally, the :file:`.spec`
|
||||
file winds up deep in the "build tree," in a temporary directory created by
|
||||
:command:`bdist_rpm`.)
|
||||
|
||||
.. % \XXX{this isn't implemented yet---is it needed?!}
|
||||
.. % You can also specify a custom \file{.spec} file with the
|
||||
.. % \longprogramopt{spec-file} option; used in conjunction with
|
||||
.. % \longprogramopt{spec-only}, this gives you an opportunity to customize
|
||||
.. % the \file{.spec} file manually:
|
||||
.. %
|
||||
.. % \ begin{verbatim}
|
||||
.. % > python setup.py bdist_rpm --spec-only
|
||||
.. % # ...edit dist/FooBar-1.0.spec
|
||||
.. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
|
||||
.. % \ end{verbatim}
|
||||
.. %
|
||||
.. % (Although a better way to do this is probably to override the standard
|
||||
.. % \command{bdist\_rpm} command with one that writes whatever else you want
|
||||
.. % to the \file{.spec} file.)
|
||||
|
||||
|
||||
.. _cross-compile-windows:
|
||||
|
||||
Cross-compiling on Windows
|
||||
==========================
|
||||
|
||||
Starting with Python 2.6, distutils is capable of cross-compiling between
|
||||
Windows platforms. In practice, this means that with the correct tools
|
||||
installed, you can use a 32bit version of Windows to create 64bit extensions
|
||||
and vice-versa.
|
||||
|
||||
To build for an alternate platform, specify the :option:`!--plat-name` option
|
||||
to the build command. Valid values are currently 'win32', and 'win-amd64'.
|
||||
For example, on a 32bit version of Windows, you could execute::
|
||||
|
||||
python setup.py build --plat-name=win-amd64
|
||||
|
||||
to build a 64bit version of your extension.
|
||||
|
||||
would create a 64bit installation executable on your 32bit version of Windows.
|
||||
|
||||
To cross-compile, you must download the Python source code and cross-compile
|
||||
Python itself for the platform you are targeting - it is not possible from a
|
||||
binary installation of Python (as the .lib etc file for other platforms are
|
||||
not included.) In practice, this means the user of a 32 bit operating
|
||||
system will need to use Visual Studio 2008 to open the
|
||||
:file:`PCbuild/PCbuild.sln` solution in the Python source tree and build the
|
||||
"x64" configuration of the 'pythoncore' project before cross-compiling
|
||||
extensions is possible.
|
||||
|
||||
Note that by default, Visual Studio 2008 does not install 64bit compilers or
|
||||
tools. You may need to reexecute the Visual Studio setup process and select
|
||||
these tools (using Control Panel->[Add/Remove] Programs is a convenient way to
|
||||
check or modify your existing install.)
|
||||
|
||||
.. _postinstallation-script:
|
||||
|
||||
The Postinstallation script
|
||||
---------------------------
|
||||
|
||||
Starting with Python 2.3, a postinstallation script can be specified with the
|
||||
:option:`!--install-script` option. The basename of the script must be
|
||||
specified, and the script filename must also be listed in the scripts argument
|
||||
to the setup function.
|
||||
|
||||
This script will be run at installation time on the target system after all the
|
||||
files have been copied, with ``argv[1]`` set to :option:`!-install`, and again at
|
||||
uninstallation time before the files are removed with ``argv[1]`` set to
|
||||
:option:`!-remove`.
|
||||
|
||||
The installation script runs embedded in the windows installer, every output
|
||||
(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be
|
||||
displayed in the GUI after the script has finished.
|
||||
|
||||
Some functions especially useful in this context are available as additional
|
||||
built-in functions in the installation script.
|
||||
|
||||
|
||||
.. function:: directory_created(path)
|
||||
file_created(path)
|
||||
|
||||
These functions should be called when a directory or file is created by the
|
||||
postinstall script at installation time. It will register *path* with the
|
||||
uninstaller, so that it will be removed when the distribution is uninstalled.
|
||||
To be safe, directories are only removed if they are empty.
|
||||
|
||||
|
||||
.. function:: get_special_folder_path(csidl_string)
|
||||
|
||||
This function can be used to retrieve special folder locations on Windows like
|
||||
the Start Menu or the Desktop. It returns the full path to the folder.
|
||||
*csidl_string* must be one of the following strings::
|
||||
|
||||
"CSIDL_APPDATA"
|
||||
|
||||
"CSIDL_COMMON_STARTMENU"
|
||||
"CSIDL_STARTMENU"
|
||||
|
||||
"CSIDL_COMMON_DESKTOPDIRECTORY"
|
||||
"CSIDL_DESKTOPDIRECTORY"
|
||||
|
||||
"CSIDL_COMMON_STARTUP"
|
||||
"CSIDL_STARTUP"
|
||||
|
||||
"CSIDL_COMMON_PROGRAMS"
|
||||
"CSIDL_PROGRAMS"
|
||||
|
||||
"CSIDL_FONTS"
|
||||
|
||||
If the folder cannot be retrieved, :exc:`OSError` is raised.
|
||||
|
||||
Which folders are available depends on the exact Windows version, and probably
|
||||
also the configuration. For details refer to Microsoft's documentation of the
|
||||
:c:func:`SHGetSpecialFolderPath` function.
|
||||
|
||||
|
||||
.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])
|
||||
|
||||
This function creates a shortcut. *target* is the path to the program to be
|
||||
started by the shortcut. *description* is the description of the shortcut.
|
||||
*filename* is the title of the shortcut that the user will see. *arguments*
|
||||
specifies the command line arguments, if any. *workdir* is the working directory
|
||||
for the program. *iconpath* is the file containing the icon for the shortcut,
|
||||
and *iconindex* is the index of the icon in the file *iconpath*. Again, for
|
||||
details consult the Microsoft documentation for the :class:`IShellLink`
|
||||
interface.
|
||||
|
|
@ -1,105 +0,0 @@
|
|||
.. _reference:
|
||||
|
||||
*****************
|
||||
Command Reference
|
||||
*****************
|
||||
|
||||
.. include:: ./_setuptools_disclaimer.rst
|
||||
|
||||
.. % \section{Building modules: the \protect\command{build} command family}
|
||||
.. % \label{build-cmds}
|
||||
.. % \subsubsection{\protect\command{build}}
|
||||
.. % \label{build-cmd}
|
||||
.. % \subsubsection{\protect\command{build\_py}}
|
||||
.. % \label{build-py-cmd}
|
||||
.. % \subsubsection{\protect\command{build\_ext}}
|
||||
.. % \label{build-ext-cmd}
|
||||
.. % \subsubsection{\protect\command{build\_clib}}
|
||||
.. % \label{build-clib-cmd}
|
||||
|
||||
|
||||
.. _install-cmd:
|
||||
|
||||
Installing modules: the :command:`install` command family
|
||||
=========================================================
|
||||
|
||||
The install command ensures that the build commands have been run and then runs
|
||||
the subcommands :command:`install_lib`, :command:`install_data` and
|
||||
:command:`install_scripts`.
|
||||
|
||||
.. % \subsubsection{\protect\command{install\_lib}}
|
||||
.. % \label{install-lib-cmd}
|
||||
|
||||
|
||||
.. _install-data-cmd:
|
||||
|
||||
:command:`install_data`
|
||||
-----------------------
|
||||
|
||||
This command installs all data files provided with the distribution.
|
||||
|
||||
|
||||
.. _install-scripts-cmd:
|
||||
|
||||
:command:`install_scripts`
|
||||
--------------------------
|
||||
|
||||
This command installs all (Python) scripts in the distribution.
|
||||
|
||||
.. % \subsection{Cleaning up: the \protect\command{clean} command}
|
||||
.. % \label{clean-cmd}
|
||||
|
||||
|
||||
.. _sdist-cmd:
|
||||
|
||||
Creating a source distribution: the :command:`sdist` command
|
||||
============================================================
|
||||
|
||||
.. XXX fragment moved down from above: needs context!
|
||||
|
||||
The manifest template commands are:
|
||||
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
| Command | Description |
|
||||
+===========================================+===============================================+
|
||||
| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
|
||||
| | patterns |
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
|
||||
| | patterns |
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
|
||||
| ...` | the listed patterns |
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
|
||||
| ...` | the listed patterns |
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
|
||||
| | matching --- & any of the listed patterns |
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
|
||||
| | matching --- & any of the listed patterns |
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
| :command:`prune dir` | exclude all files under *dir* |
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
| :command:`graft dir` | include all files under *dir* |
|
||||
+-------------------------------------------+-----------------------------------------------+
|
||||
|
||||
The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
|
||||
regular filename characters, ``?`` matches any single regular filename
|
||||
character, and ``[range]`` matches any of the characters in *range* (e.g.,
|
||||
``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename
|
||||
character" is platform-specific: on Unix it is anything except slash; on Windows
|
||||
anything except backslash or colon.
|
||||
|
||||
.. XXX Windows support not there yet
|
||||
|
||||
.. % \section{Creating a built distribution: the
|
||||
.. % \protect\command{bdist} command family}
|
||||
.. % \label{bdist-cmds}
|
||||
|
||||
.. % \subsection{\protect\command{bdist}}
|
||||
.. % \subsection{\protect\command{bdist\_dumb}}
|
||||
.. % \subsection{\protect\command{bdist\_rpm}}
|
||||
|
||||
|
||||
|
|
@ -1,144 +0,0 @@
|
|||
.. _setup-config:
|
||||
|
||||
************************************
|
||||
Writing the Setup Configuration File
|
||||
************************************
|
||||
|
||||
.. include:: ./_setuptools_disclaimer.rst
|
||||
|
||||
Often, it's not possible to write down everything needed to build a distribution
|
||||
*a priori*: you may need to get some information from the user, or from the
|
||||
user's system, in order to proceed. As long as that information is fairly
|
||||
simple---a list of directories to search for C header files or libraries, for
|
||||
example---then providing a configuration file, :file:`setup.cfg`, for users to
|
||||
edit is a cheap and easy way to solicit it. Configuration files also let you
|
||||
provide default values for any command option, which the installer can then
|
||||
override either on the command-line or by editing the config file.
|
||||
|
||||
The setup configuration file is a useful middle-ground between the setup
|
||||
script---which, ideally, would be opaque to installers [#]_---and the command-line to
|
||||
the setup script, which is outside of your control and entirely up to the
|
||||
installer. In fact, :file:`setup.cfg` (and any other Distutils configuration
|
||||
files present on the target system) are processed after the contents of the
|
||||
setup script, but before the command-line. This has several useful
|
||||
consequences:
|
||||
|
||||
.. % (If you have more advanced needs, such as determining which extensions
|
||||
.. % to build based on what capabilities are present on the target system,
|
||||
.. % then you need the Distutils ``auto-configuration'' facility. This
|
||||
.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
|
||||
.. % or stable enough yet for real-world use.)
|
||||
|
||||
* installers can override some of what you put in :file:`setup.py` by editing
|
||||
:file:`setup.cfg`
|
||||
|
||||
* you can provide non-standard defaults for options that are not easily set in
|
||||
:file:`setup.py`
|
||||
|
||||
* installers can override anything in :file:`setup.cfg` using the command-line
|
||||
options to :file:`setup.py`
|
||||
|
||||
The basic syntax of the configuration file is simple:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[command]
|
||||
option=value
|
||||
...
|
||||
|
||||
where *command* is one of the Distutils commands (e.g. :command:`build_py`,
|
||||
:command:`install`), and *option* is one of the options that command supports.
|
||||
Any number of options can be supplied for each command, and any number of
|
||||
command sections can be included in the file. Blank lines are ignored, as are
|
||||
comments, which run from a ``'#'`` character until the end of the line. Long
|
||||
option values can be split across multiple lines simply by indenting the
|
||||
continuation lines.
|
||||
|
||||
You can find out the list of options supported by a particular command with the
|
||||
universal :option:`!--help` option, e.g.
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
$ python setup.py --help build_ext
|
||||
[...]
|
||||
Options for 'build_ext' command:
|
||||
--build-lib (-b) directory for compiled extension modules
|
||||
--build-temp (-t) directory for temporary files (build by-products)
|
||||
--inplace (-i) ignore build-lib and put compiled extensions into the
|
||||
source directory alongside your pure Python modules
|
||||
--include-dirs (-I) list of directories to search for header files
|
||||
--define (-D) C preprocessor macros to define
|
||||
--undef (-U) C preprocessor macros to undefine
|
||||
--swig-opts list of SWIG command line options
|
||||
[...]
|
||||
|
||||
Note that an option spelled :option:`!--foo-bar` on the command-line is spelled
|
||||
``foo_bar`` in configuration files.
|
||||
|
||||
.. _distutils-build-ext-inplace:
|
||||
|
||||
For example, say you want your extensions to be built "in-place"---that is, you
|
||||
have an extension :mod:`pkg.ext`, and you want the compiled extension file
|
||||
(:file:`ext.so` on Unix, say) to be put in the same source directory as your
|
||||
pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the
|
||||
:option:`!--inplace` option on the command-line to ensure this:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
python setup.py build_ext --inplace
|
||||
|
||||
But this requires that you always specify the :command:`build_ext` command
|
||||
explicitly, and remember to provide :option:`!--inplace`. An easier way is to
|
||||
"set and forget" this option, by encoding it in :file:`setup.cfg`, the
|
||||
configuration file for this distribution:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[build_ext]
|
||||
inplace=1
|
||||
|
||||
This will affect all builds of this module distribution, whether or not you
|
||||
explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in
|
||||
your source distribution, it will also affect end-user builds---which is
|
||||
probably a bad idea for this option, since always building extensions in-place
|
||||
would break installation of the module distribution. In certain peculiar cases,
|
||||
though, modules are built right in their installation directory, so this is
|
||||
conceivably a useful ability. (Distributing extensions that expect to be built
|
||||
in their installation directory is almost always a bad idea, though.)
|
||||
|
||||
Another example: certain commands take a lot of options that don't change from
|
||||
run to run; for example, :command:`bdist_rpm` needs to know everything required
|
||||
to generate a "spec" file for creating an RPM distribution. Some of this
|
||||
information comes from the setup script, and some is automatically generated by
|
||||
the Distutils (such as the list of files installed). But some of it has to be
|
||||
supplied as options to :command:`bdist_rpm`, which would be very tedious to do
|
||||
on the command-line for every run. Hence, here is a snippet from the Distutils'
|
||||
own :file:`setup.cfg`:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[bdist_rpm]
|
||||
release = 1
|
||||
packager = Greg Ward <gward@python.net>
|
||||
doc_files = CHANGES.txt
|
||||
README.txt
|
||||
USAGE.txt
|
||||
doc/
|
||||
examples/
|
||||
|
||||
Note that the ``doc_files`` option is simply a whitespace-separated string
|
||||
split across multiple lines for readability.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`inst-config-syntax` in "Installing Python Modules"
|
||||
More information on the configuration files is available in the manual for
|
||||
system administrators.
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#] This ideal probably won't be achieved until auto-configuration is fully
|
||||
supported by the Distutils.
|
||||
|
||||
|
|
@ -1,340 +0,0 @@
|
|||
.. _distutils_examples:
|
||||
|
||||
******************
|
||||
Distutils Examples
|
||||
******************
|
||||
|
||||
.. include:: ./_setuptools_disclaimer.rst
|
||||
|
||||
This chapter provides a number of basic examples to help get started with
|
||||
distutils. Additional information about using distutils can be found in the
|
||||
Distutils Cookbook.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Distutils Cookbook <https://wiki.python.org/moin/Distutils/Cookbook>`_
|
||||
Collection of recipes showing how to achieve more control over distutils.
|
||||
|
||||
|
||||
.. _pure-mod:
|
||||
|
||||
Pure Python distribution (by module)
|
||||
====================================
|
||||
|
||||
If you're just distributing a couple of modules, especially if they don't live
|
||||
in a particular package, you can specify them individually using the
|
||||
``py_modules`` option in the setup script.
|
||||
|
||||
In the simplest case, you'll have two files to worry about: a setup script and
|
||||
the single module you're distributing, :file:`foo.py` in this example::
|
||||
|
||||
<root>/
|
||||
setup.py
|
||||
foo.py
|
||||
|
||||
(In all diagrams in this section, *<root>* will refer to the distribution root
|
||||
directory.) A minimal setup script to describe this situation would be::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foo',
|
||||
version='1.0',
|
||||
py_modules=['foo'],
|
||||
)
|
||||
|
||||
Note that the name of the distribution is specified independently with the
|
||||
``name`` option, and there's no rule that says it has to be the same as
|
||||
the name of the sole module in the distribution (although that's probably a good
|
||||
convention to follow). However, the distribution name is used to generate
|
||||
filenames, so you should stick to letters, digits, underscores, and hyphens.
|
||||
|
||||
Since ``py_modules`` is a list, you can of course specify multiple
|
||||
modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
|
||||
setup might look like this::
|
||||
|
||||
<root>/
|
||||
setup.py
|
||||
foo.py
|
||||
bar.py
|
||||
|
||||
and the setup script might be ::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
py_modules=['foo', 'bar'],
|
||||
)
|
||||
|
||||
You can put module source files into another directory, but if you have enough
|
||||
modules to do that, it's probably easier to specify modules by package rather
|
||||
than listing them individually.
|
||||
|
||||
|
||||
.. _pure-pkg:
|
||||
|
||||
Pure Python distribution (by package)
|
||||
=====================================
|
||||
|
||||
If you have more than a couple of modules to distribute, especially if they are
|
||||
in multiple packages, it's probably easier to specify whole packages rather than
|
||||
individual modules. This works even if your modules are not in a package; you
|
||||
can just tell the Distutils to process modules from the root package, and that
|
||||
works the same as any other package (except that you don't have to have an
|
||||
:file:`__init__.py` file).
|
||||
|
||||
The setup script from the last example could also be written as ::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
packages=[''],
|
||||
)
|
||||
|
||||
(The empty string stands for the root package.)
|
||||
|
||||
If those two files are moved into a subdirectory, but remain in the root
|
||||
package, e.g.::
|
||||
|
||||
<root>/
|
||||
setup.py
|
||||
src/ foo.py
|
||||
bar.py
|
||||
|
||||
then you would still specify the root package, but you have to tell the
|
||||
Distutils where source files in the root package live::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
package_dir={'': 'src'},
|
||||
packages=[''],
|
||||
)
|
||||
|
||||
More typically, though, you will want to distribute multiple modules in the same
|
||||
package (or in sub-packages). For example, if the :mod:`foo` and :mod:`bar`
|
||||
modules belong in package :mod:`foobar`, one way to layout your source tree is
|
||||
::
|
||||
|
||||
<root>/
|
||||
setup.py
|
||||
foobar/
|
||||
__init__.py
|
||||
foo.py
|
||||
bar.py
|
||||
|
||||
This is in fact the default layout expected by the Distutils, and the one that
|
||||
requires the least work to describe in your setup script::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
packages=['foobar'],
|
||||
)
|
||||
|
||||
If you want to put modules in directories not named for their package, then you
|
||||
need to use the ``package_dir`` option again. For example, if the
|
||||
:file:`src` directory holds modules in the :mod:`foobar` package::
|
||||
|
||||
<root>/
|
||||
setup.py
|
||||
src/
|
||||
__init__.py
|
||||
foo.py
|
||||
bar.py
|
||||
|
||||
an appropriate setup script would be ::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
package_dir={'foobar': 'src'},
|
||||
packages=['foobar'],
|
||||
)
|
||||
|
||||
Or, you might put modules from your main package right in the distribution
|
||||
root::
|
||||
|
||||
<root>/
|
||||
setup.py
|
||||
__init__.py
|
||||
foo.py
|
||||
bar.py
|
||||
|
||||
in which case your setup script would be ::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
package_dir={'foobar': ''},
|
||||
packages=['foobar'],
|
||||
)
|
||||
|
||||
(The empty string also stands for the current directory.)
|
||||
|
||||
If you have sub-packages, they must be explicitly listed in ``packages``,
|
||||
but any entries in ``package_dir`` automatically extend to sub-packages.
|
||||
(In other words, the Distutils does *not* scan your source tree, trying to
|
||||
figure out which directories correspond to Python packages by looking for
|
||||
:file:`__init__.py` files.) Thus, if the default layout grows a sub-package::
|
||||
|
||||
<root>/
|
||||
setup.py
|
||||
foobar/
|
||||
__init__.py
|
||||
foo.py
|
||||
bar.py
|
||||
subfoo/
|
||||
__init__.py
|
||||
blah.py
|
||||
|
||||
then the corresponding setup script would be ::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
packages=['foobar', 'foobar.subfoo'],
|
||||
)
|
||||
|
||||
|
||||
.. _single-ext:
|
||||
|
||||
Single extension module
|
||||
=======================
|
||||
|
||||
Extension modules are specified using the ``ext_modules`` option.
|
||||
``package_dir`` has no effect on where extension source files are found;
|
||||
it only affects the source for pure Python modules. The simplest case, a
|
||||
single extension module in a single C source file, is::
|
||||
|
||||
<root>/
|
||||
setup.py
|
||||
foo.c
|
||||
|
||||
If the :mod:`foo` extension belongs in the root package, the setup script for
|
||||
this could be ::
|
||||
|
||||
from distutils.core import setup
|
||||
from distutils.extension import Extension
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
ext_modules=[Extension('foo', ['foo.c'])],
|
||||
)
|
||||
|
||||
If the extension actually belongs in a package, say :mod:`foopkg`, then
|
||||
|
||||
With exactly the same source tree layout, this extension can be put in the
|
||||
:mod:`foopkg` package simply by changing the name of the extension::
|
||||
|
||||
from distutils.core import setup
|
||||
from distutils.extension import Extension
|
||||
setup(name='foobar',
|
||||
version='1.0',
|
||||
ext_modules=[Extension('foopkg.foo', ['foo.c'])],
|
||||
)
|
||||
|
||||
Checking a package
|
||||
==================
|
||||
|
||||
The ``check`` command allows you to verify if your package meta-data
|
||||
meet the minimum requirements to build a distribution.
|
||||
|
||||
To run it, just call it using your :file:`setup.py` script. If something is
|
||||
missing, ``check`` will display a warning.
|
||||
|
||||
Let's take an example with a simple script::
|
||||
|
||||
from distutils.core import setup
|
||||
|
||||
setup(name='foobar')
|
||||
|
||||
Running the ``check`` command will display some warnings:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
$ python setup.py check
|
||||
running check
|
||||
warning: check: missing required meta-data: version, url
|
||||
warning: check: missing meta-data: either (author and author_email) or
|
||||
(maintainer and maintainer_email) should be supplied
|
||||
|
||||
|
||||
If you use the reStructuredText syntax in the ``long_description`` field and
|
||||
`docutils`_ is installed you can check if the syntax is fine with the
|
||||
``check`` command, using the ``restructuredtext`` option.
|
||||
|
||||
For example, if the :file:`setup.py` script is changed like this::
|
||||
|
||||
from distutils.core import setup
|
||||
|
||||
desc = """\
|
||||
My description
|
||||
==============
|
||||
|
||||
This is the description of the ``foobar`` package.
|
||||
"""
|
||||
|
||||
setup(name='foobar', version='1', author='tarek',
|
||||
author_email='tarek@ziade.org',
|
||||
url='http://example.com', long_description=desc)
|
||||
|
||||
Where the long description is broken, ``check`` will be able to detect it
|
||||
by using the :mod:`docutils` parser:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
$ python setup.py check --restructuredtext
|
||||
running check
|
||||
warning: check: Title underline too short. (line 2)
|
||||
warning: check: Could not finish the parsing.
|
||||
|
||||
Reading the metadata
|
||||
=====================
|
||||
|
||||
The :func:`distutils.core.setup` function provides a command-line interface
|
||||
that allows you to query the metadata fields of a project through the
|
||||
``setup.py`` script of a given project:
|
||||
|
||||
.. code-block:: shell-session
|
||||
|
||||
$ python setup.py --name
|
||||
distribute
|
||||
|
||||
This call reads the ``name`` metadata by running the
|
||||
:func:`distutils.core.setup` function. Although, when a source or binary
|
||||
distribution is created with Distutils, the metadata fields are written
|
||||
in a static file called :file:`PKG-INFO`. When a Distutils-based project is
|
||||
installed in Python, the :file:`PKG-INFO` file is copied alongside the modules
|
||||
and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`,
|
||||
where ``NAME`` is the name of the project, ``VERSION`` its version as defined
|
||||
in the Metadata, and ``pyX.X`` the major and minor version of Python like
|
||||
``2.7`` or ``3.2``.
|
||||
|
||||
You can read back this static file, by using the
|
||||
:class:`distutils.dist.DistributionMetadata` class and its
|
||||
:func:`read_pkg_file` method::
|
||||
|
||||
>>> from distutils.dist import DistributionMetadata
|
||||
>>> metadata = DistributionMetadata()
|
||||
>>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
|
||||
>>> metadata.name
|
||||
'distribute'
|
||||
>>> metadata.version
|
||||
'0.6.8'
|
||||
>>> metadata.description
|
||||
'Easily download, build, install, upgrade, and uninstall Python packages'
|
||||
|
||||
Notice that the class can also be instantiated with a metadata file path to
|
||||
loads its values::
|
||||
|
||||
>>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
|
||||
>>> DistributionMetadata(pkg_info_path).name
|
||||
'distribute'
|
||||
|
||||
|
||||
.. % \section{Multiple extension modules}
|
||||
.. % \label{multiple-ext}
|
||||
|
||||
.. % \section{Putting it all together}
|
||||
|
||||
|
||||
.. _docutils: http://docutils.sourceforge.net
|
||||
|
|
@ -1,98 +0,0 @@
|
|||
.. _extending-distutils:
|
||||
|
||||
*******************
|
||||
Extending Distutils
|
||||
*******************
|
||||
|
||||
.. include:: ./_setuptools_disclaimer.rst
|
||||
|
||||
Distutils can be extended in various ways. Most extensions take the form of new
|
||||
commands or replacements for existing commands. New commands may be written to
|
||||
support new types of platform-specific packaging, for example, while
|
||||
replacements for existing commands may be made to modify details of how the
|
||||
command operates on a package.
|
||||
|
||||
Most extensions of the distutils are made within :file:`setup.py` scripts that
|
||||
want to modify existing commands; many simply add a few file extensions that
|
||||
should be copied into packages in addition to :file:`.py` files as a
|
||||
convenience.
|
||||
|
||||
Most distutils command implementations are subclasses of the
|
||||
:class:`distutils.cmd.Command` class. New commands may directly inherit from
|
||||
:class:`Command`, while replacements often derive from :class:`Command`
|
||||
indirectly, directly subclassing the command they are replacing. Commands are
|
||||
required to derive from :class:`Command`.
|
||||
|
||||
.. % \section{Extending existing commands}
|
||||
.. % \label{extend-existing}
|
||||
|
||||
.. % \section{Writing new commands}
|
||||
.. % \label{new-commands}
|
||||
.. % \XXX{Would an uninstall command be a good example here?}
|
||||
|
||||
|
||||
Integrating new commands
|
||||
========================
|
||||
|
||||
There are different ways to integrate new command implementations into
|
||||
distutils. The most difficult is to lobby for the inclusion of the new features
|
||||
in distutils itself, and wait for (and require) a version of Python that
|
||||
provides that support. This is really hard for many reasons.
|
||||
|
||||
The most common, and possibly the most reasonable for most needs, is to include
|
||||
the new implementations with your :file:`setup.py` script, and cause the
|
||||
:func:`distutils.core.setup` function use them::
|
||||
|
||||
from distutils.command.build_py import build_py as _build_py
|
||||
from distutils.core import setup
|
||||
|
||||
class build_py(_build_py):
|
||||
"""Specialized Python source builder."""
|
||||
|
||||
# implement whatever needs to be different...
|
||||
|
||||
setup(cmdclass={'build_py': build_py},
|
||||
...)
|
||||
|
||||
This approach is most valuable if the new implementations must be used to use a
|
||||
particular package, as everyone interested in the package will need to have the
|
||||
new command implementation.
|
||||
|
||||
Beginning with Python 2.4, a third option is available, intended to allow new
|
||||
commands to be added which can support existing :file:`setup.py` scripts without
|
||||
requiring modifications to the Python installation. This is expected to allow
|
||||
third-party extensions to provide support for additional packaging systems, but
|
||||
the commands can be used for anything distutils commands can be used for. A new
|
||||
configuration option, ``command_packages`` (command-line option
|
||||
:option:`!--command-packages`), can be used to specify additional packages to be
|
||||
searched for modules implementing commands. Like all distutils options, this
|
||||
can be specified on the command line or in a configuration file. This option
|
||||
can only be set in the ``[global]`` section of a configuration file, or before
|
||||
any commands on the command line. If set in a configuration file, it can be
|
||||
overridden from the command line; setting it to an empty string on the command
|
||||
line causes the default to be used. This should never be set in a configuration
|
||||
file provided with a package.
|
||||
|
||||
This new option can be used to add any number of packages to the list of
|
||||
packages searched for command implementations; multiple package names should be
|
||||
separated by commas. When not specified, the search is only performed in the
|
||||
:mod:`distutils.command` package. When :file:`setup.py` is run with the option
|
||||
``--command-packages distcmds,buildcmds``, however, the packages
|
||||
:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched
|
||||
in that order. New commands are expected to be implemented in modules of the
|
||||
same name as the command by classes sharing the same name. Given the example
|
||||
command line option above, the command :command:`bdist_openpkg` could be
|
||||
implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or
|
||||
:class:`buildcmds.bdist_openpkg.bdist_openpkg`.
|
||||
|
||||
|
||||
Adding new distribution types
|
||||
=============================
|
||||
|
||||
Commands that create distributions (files in the :file:`dist/` directory) need
|
||||
to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that
|
||||
:command:`upload` can upload it to PyPI. The *filename* in the pair contains no
|
||||
path information, only the name of the file itself. In dry-run mode, pairs
|
||||
should still be added to represent what would have been created.
|
||||
|
||||
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
.. _distutils-index:
|
||||
|
||||
##############################################
|
||||
Distributing Python Modules (Legacy version)
|
||||
##############################################
|
||||
|
||||
:Authors: Greg Ward, Anthony Baxter
|
||||
:Email: distutils-sig@python.org
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`distributing-index`
|
||||
The up to date module distribution documentations
|
||||
|
||||
.. note::
|
||||
|
||||
The entire ``distutils`` package has been deprecated and will be
|
||||
removed in Python 3.12. This documentation is retained as a
|
||||
reference only, and will be removed with the package. See the
|
||||
:ref:`What's New <distutils-deprecated>` entry for more information.
|
||||
|
||||
.. include:: ./_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/>`__
|
||||
in the Python Packaging User Guide for more information.
|
||||
|
||||
This document describes the Python Distribution Utilities ("Distutils") from
|
||||
the module developer's point of view, describing the underlying capabilities
|
||||
that ``setuptools`` builds on to allow Python developers to make Python modules
|
||||
and extensions readily available to a wider audience.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
|
||||
introduction.rst
|
||||
setupscript.rst
|
||||
configfile.rst
|
||||
sourcedist.rst
|
||||
builtdist.rst
|
||||
examples.rst
|
||||
extending.rst
|
||||
commandref.rst
|
||||
apiref.rst
|
||||
|
|
@ -1,203 +0,0 @@
|
|||
.. _distutils-intro:
|
||||
|
||||
****************************
|
||||
An Introduction to Distutils
|
||||
****************************
|
||||
|
||||
.. include:: ./_setuptools_disclaimer.rst
|
||||
|
||||
This document covers using the Distutils to distribute your Python modules,
|
||||
concentrating on the role of developer/distributor: if you're looking for
|
||||
information on installing Python modules, you should refer to the
|
||||
:ref:`install-index` chapter.
|
||||
|
||||
|
||||
.. _distutils-concepts:
|
||||
|
||||
Concepts & Terminology
|
||||
======================
|
||||
|
||||
Using the Distutils is quite simple, both for module developers and for
|
||||
users/administrators installing third-party modules. As a developer, your
|
||||
responsibilities (apart from writing solid, well-documented and well-tested
|
||||
code, of course!) are:
|
||||
|
||||
* write a setup script (:file:`setup.py` by convention)
|
||||
|
||||
* (optional) write a setup configuration file
|
||||
|
||||
* create a source distribution
|
||||
|
||||
* (optional) create one or more built (binary) distributions
|
||||
|
||||
Each of these tasks is covered in this document.
|
||||
|
||||
Not all module developers have access to a multitude of platforms, so it's not
|
||||
always feasible to expect them to create a multitude of built distributions. It
|
||||
is hoped that a class of intermediaries, called *packagers*, will arise to
|
||||
address this need. Packagers will take source distributions released by module
|
||||
developers, build them on one or more platforms, and release the resulting built
|
||||
distributions. Thus, users on the most popular platforms will be able to
|
||||
install most popular Python module distributions in the most natural way for
|
||||
their platform, without having to run a single setup script or compile a line of
|
||||
code.
|
||||
|
||||
|
||||
.. _distutils-simple-example:
|
||||
|
||||
A Simple Example
|
||||
================
|
||||
|
||||
The setup script is usually quite simple, although since it's written in Python,
|
||||
there are no arbitrary limits to what you can do with it, though you should be
|
||||
careful about putting arbitrarily expensive operations in your setup script.
|
||||
Unlike, say, Autoconf-style configure scripts, the setup script may be run
|
||||
multiple times in the course of building and installing your module
|
||||
distribution.
|
||||
|
||||
If all you want to do is distribute a module called :mod:`foo`, contained in a
|
||||
file :file:`foo.py`, then your setup script can be as simple as this::
|
||||
|
||||
from distutils.core import setup
|
||||
setup(name='foo',
|
||||
version='1.0',
|
||||
py_modules=['foo'],
|
||||
)
|
||||
|
||||
Some observations:
|
||||
|
||||
* most information that you supply to the Distutils is supplied as keyword
|
||||
arguments to the :func:`setup` function
|
||||
|
||||
* those keyword arguments fall into two categories: package metadata (name,
|
||||
version number) and information about what's in the package (a list of pure
|
||||
Python modules, in this case)
|
||||
|
||||
* modules are specified by module name, not filename (the same will hold true
|
||||
for packages and extensions)
|
||||
|
||||
* it's recommended that you supply a little more metadata, in particular your
|
||||
name, email address and a URL for the project (see section :ref:`setup-script`
|
||||
for an example)
|
||||
|
||||
To create a source distribution for this module, you would create a setup
|
||||
script, :file:`setup.py`, containing the above code, and run this command from a
|
||||
terminal::
|
||||
|
||||
python setup.py sdist
|
||||
|
||||
For Windows, open a command prompt window (:menuselection:`Start -->
|
||||
Accessories`) and change the command to::
|
||||
|
||||
setup.py sdist
|
||||
|
||||
:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
|
||||
containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
|
||||
The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
|
||||
will unpack into a directory :file:`foo-1.0`.
|
||||
|
||||
If an end-user wishes to install your :mod:`foo` module, all they have to do is
|
||||
download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
|
||||
:file:`foo-1.0` directory---run ::
|
||||
|
||||
python setup.py install
|
||||
|
||||
which will ultimately copy :file:`foo.py` to the appropriate directory for
|
||||
third-party modules in their Python installation.
|
||||
|
||||
This simple example demonstrates some fundamental concepts of the Distutils.
|
||||
First, both developers and installers have the same basic user interface, i.e.
|
||||
the setup script. The difference is which Distutils *commands* they use: the
|
||||
:command:`sdist` command is almost exclusively for module developers, while
|
||||
:command:`install` is more often for installers (although most developers will
|
||||
want to install their own code occasionally).
|
||||
|
||||
Other useful built distribution formats are RPM, implemented by the
|
||||
:command:`bdist_rpm` command, Solaris :program:`pkgtool`
|
||||
(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
|
||||
(:command:`bdist_sdux`). For example, the following command will create an RPM
|
||||
file called :file:`foo-1.0.noarch.rpm`::
|
||||
|
||||
python setup.py bdist_rpm
|
||||
|
||||
(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
|
||||
this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
|
||||
Mandrake Linux.)
|
||||
|
||||
You can find out what distribution formats are available at any time by running
|
||||
::
|
||||
|
||||
python setup.py bdist --help-formats
|
||||
|
||||
|
||||
.. _python-terms:
|
||||
|
||||
General Python terminology
|
||||
==========================
|
||||
|
||||
If you're reading this document, you probably have a good idea of what modules,
|
||||
extensions, and so forth are. Nevertheless, just to be sure that everyone is
|
||||
operating from a common starting point, we offer the following glossary of
|
||||
common Python terms:
|
||||
|
||||
module
|
||||
the basic unit of code reusability in Python: a block of code imported by some
|
||||
other code. Three types of modules concern us here: pure Python modules,
|
||||
extension modules, and packages.
|
||||
|
||||
pure Python module
|
||||
a module written in Python and contained in a single :file:`.py` file (and
|
||||
possibly associated :file:`.pyc` files). Sometimes referred to as a
|
||||
"pure module."
|
||||
|
||||
extension module
|
||||
a module written in the low-level language of the Python implementation: C/C++
|
||||
for Python, Java for Jython. Typically contained in a single dynamically
|
||||
loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
|
||||
extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
|
||||
extensions on Windows, or a Java class file for Jython extensions. (Note that
|
||||
currently, the Distutils only handles C/C++ extensions for Python.)
|
||||
|
||||
package
|
||||
a module that contains other modules; typically contained in a directory in the
|
||||
filesystem and distinguished from other directories by the presence of a file
|
||||
:file:`__init__.py`.
|
||||
|
||||
root package
|
||||
the root of the hierarchy of packages. (This isn't really a package, since it
|
||||
doesn't have an :file:`__init__.py` file. But we have to call it something.)
|
||||
The vast majority of the standard library is in the root package, as are many
|
||||
small, standalone third-party modules that don't belong to a larger module
|
||||
collection. Unlike regular packages, modules in the root package can be found in
|
||||
many directories: in fact, every directory listed in ``sys.path`` contributes
|
||||
modules to the root package.
|
||||
|
||||
|
||||
.. _distutils-term:
|
||||
|
||||
Distutils-specific terminology
|
||||
==============================
|
||||
|
||||
The following terms apply more specifically to the domain of distributing Python
|
||||
modules using the Distutils:
|
||||
|
||||
module distribution
|
||||
a collection of Python modules distributed together as a single downloadable
|
||||
resource and meant to be installed *en masse*. Examples of some well-known
|
||||
module distributions are NumPy, SciPy, Pillow,
|
||||
or mxBase. (This would be called a *package*, except that term is
|
||||
already taken in the Python context: a single module distribution may contain
|
||||
zero, one, or many Python packages.)
|
||||
|
||||
pure module distribution
|
||||
a module distribution that contains only pure Python modules and packages.
|
||||
Sometimes referred to as a "pure distribution."
|
||||
|
||||
non-pure module distribution
|
||||
a module distribution that contains at least one extension module. Sometimes
|
||||
referred to as a "non-pure distribution."
|
||||
|
||||
distribution root
|
||||
the top-level directory of your source tree (or source distribution); the
|
||||
directory where :file:`setup.py` exists. Generally :file:`setup.py` will be
|
||||
run from this directory.
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
:orphan:
|
||||
|
||||
.. _package-index:
|
||||
|
||||
*******************************
|
||||
The Python Package Index (PyPI)
|
||||
*******************************
|
||||
|
||||
The `Python Package Index (PyPI)`_ stores metadata describing distributions
|
||||
packaged with distutils and other publishing tools, as well the distribution
|
||||
archives themselves.
|
||||
|
||||
References to up to date PyPI documentation can be found at
|
||||
:ref:`publishing-python-packages`.
|
||||
|
||||
.. _Python Package Index (PyPI): https://pypi.org
|
||||
|
|
@ -1,713 +0,0 @@
|
|||
.. _setup-script:
|
||||
|
||||
************************
|
||||
Writing the Setup Script
|
||||
************************
|
||||
|
||||
.. include:: ./_setuptools_disclaimer.rst
|
||||
|
||||
The setup script is the centre of all activity in building, distributing, and
|
||||
installing modules using the Distutils. The main purpose of the setup script is
|
||||
to describe your module distribution to the Distutils, so that the various
|
||||
commands that operate on your modules do the right thing. As we saw in section
|
||||
:ref:`distutils-simple-example` above, the setup script consists mainly of a call to
|
||||
:func:`setup`, and most information supplied to the Distutils by the module
|
||||
developer is supplied as keyword arguments to :func:`setup`.
|
||||
|
||||
Here's a slightly more involved example, which we'll follow for the next couple
|
||||
of sections: the Distutils' own setup script. (Keep in mind that although the
|
||||
Distutils are included with Python 1.6 and later, they also have an independent
|
||||
existence so that Python 1.5.2 users can use them to install other module
|
||||
distributions. The Distutils' own setup script, shown here, is used to install
|
||||
the package into Python 1.5.2.) ::
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from distutils.core import setup
|
||||
|
||||
setup(name='Distutils',
|
||||
version='1.0',
|
||||
description='Python Distribution Utilities',
|
||||
author='Greg Ward',
|
||||
author_email='gward@python.net',
|
||||
url='https://www.python.org/sigs/distutils-sig/',
|
||||
packages=['distutils', 'distutils.command'],
|
||||
)
|
||||
|
||||
There are only two differences between this and the trivial one-file
|
||||
distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
|
||||
specification of pure Python modules by package, rather than by module. This is
|
||||
important since the Distutils consist of a couple of dozen modules split into
|
||||
(so far) two packages; an explicit list of every module would be tedious to
|
||||
generate and difficult to maintain. For more information on the additional
|
||||
meta-data, see section :ref:`meta-data`.
|
||||
|
||||
Note that any pathnames (files or directories) supplied in the setup script
|
||||
should be written using the Unix convention, i.e. slash-separated. The
|
||||
Distutils will take care of converting this platform-neutral representation into
|
||||
whatever is appropriate on your current platform before actually using the
|
||||
pathname. This makes your setup script portable across operating systems, which
|
||||
of course is one of the major goals of the Distutils. In this spirit, all
|
||||
pathnames in this document are slash-separated.
|
||||
|
||||
This, of course, only applies to pathnames given to Distutils functions. If
|
||||
you, for example, use standard Python functions such as :func:`glob.glob` or
|
||||
:func:`os.listdir` to specify files, you should be careful to write portable
|
||||
code instead of hardcoding path separators::
|
||||
|
||||
glob.glob(os.path.join('mydir', 'subdir', '*.html'))
|
||||
os.listdir(os.path.join('mydir', 'subdir'))
|
||||
|
||||
|
||||
.. _listing-packages:
|
||||
|
||||
Listing whole packages
|
||||
======================
|
||||
|
||||
The ``packages`` option tells the Distutils to process (build, distribute,
|
||||
install, etc.) all pure Python modules found in each package mentioned in the
|
||||
``packages`` list. In order to do this, of course, there has to be a
|
||||
correspondence between package names and directories in the filesystem. The
|
||||
default correspondence is the most obvious one, i.e. package :mod:`distutils` is
|
||||
found in the directory :file:`distutils` relative to the distribution root.
|
||||
Thus, when you say ``packages = ['foo']`` in your setup script, you are
|
||||
promising that the Distutils will find a file :file:`foo/__init__.py` (which
|
||||
might be spelled differently on your system, but you get the idea) relative to
|
||||
the directory where your setup script lives. If you break this promise, the
|
||||
Distutils will issue a warning but still process the broken package anyway.
|
||||
|
||||
If you use a different convention to lay out your source directory, that's no
|
||||
problem: you just have to supply the ``package_dir`` option to tell the
|
||||
Distutils about your convention. For example, say you keep all Python source
|
||||
under :file:`lib`, so that modules in the "root package" (i.e., not in any
|
||||
package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
|
||||
:file:`lib/foo`, and so forth. Then you would put ::
|
||||
|
||||
package_dir = {'': 'lib'}
|
||||
|
||||
in your setup script. The keys to this dictionary are package names, and an
|
||||
empty package name stands for the root package. The values are directory names
|
||||
relative to your distribution root. In this case, when you say ``packages =
|
||||
['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
|
||||
|
||||
Another possible convention is to put the :mod:`foo` package right in
|
||||
:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be
|
||||
written in the setup script as ::
|
||||
|
||||
package_dir = {'foo': 'lib'}
|
||||
|
||||
A ``package: dir`` entry in the ``package_dir`` dictionary implicitly
|
||||
applies to all packages below *package*, so the :mod:`foo.bar` case is
|
||||
automatically handled here. In this example, having ``packages = ['foo',
|
||||
'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
|
||||
:file:`lib/bar/__init__.py`. (Keep in mind that although ``package_dir``
|
||||
applies recursively, you must explicitly list all packages in
|
||||
``packages``: the Distutils will *not* recursively scan your source tree
|
||||
looking for any directory with an :file:`__init__.py` file.)
|
||||
|
||||
|
||||
.. _listing-modules:
|
||||
|
||||
Listing individual modules
|
||||
==========================
|
||||
|
||||
For a small module distribution, you might prefer to list all modules rather
|
||||
than listing packages---especially the case of a single module that goes in the
|
||||
"root package" (i.e., no package at all). This simplest case was shown in
|
||||
section :ref:`distutils-simple-example`; here is a slightly more involved example::
|
||||
|
||||
py_modules = ['mod1', 'pkg.mod2']
|
||||
|
||||
This describes two modules, one of them in the "root" package, the other in the
|
||||
:mod:`pkg` package. Again, the default package/directory layout implies that
|
||||
these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
|
||||
that :file:`pkg/__init__.py` exists as well. And again, you can override the
|
||||
package/directory correspondence using the ``package_dir`` option.
|
||||
|
||||
|
||||
.. _describing-extensions:
|
||||
|
||||
Describing extension modules
|
||||
============================
|
||||
|
||||
Just as writing Python extension modules is a bit more complicated than writing
|
||||
pure Python modules, describing them to the Distutils is a bit more complicated.
|
||||
Unlike pure modules, it's not enough just to list modules or packages and expect
|
||||
the Distutils to go out and find the right files; you have to specify the
|
||||
extension name, source file(s), and any compile/link requirements (include
|
||||
directories, libraries to link with, etc.).
|
||||
|
||||
.. XXX read over this section
|
||||
|
||||
All of this is done through another keyword argument to :func:`setup`, the
|
||||
``ext_modules`` option. ``ext_modules`` is just a list of
|
||||
:class:`~distutils.core.Extension` instances, each of which describes a
|
||||
single extension module.
|
||||
Suppose your distribution includes a single extension, called :mod:`foo` and
|
||||
implemented by :file:`foo.c`. If no additional instructions to the
|
||||
compiler/linker are needed, describing this extension is quite simple::
|
||||
|
||||
Extension('foo', ['foo.c'])
|
||||
|
||||
The :class:`Extension` class can be imported from :mod:`distutils.core` along
|
||||
with :func:`setup`. Thus, the setup script for a module distribution that
|
||||
contains only this one extension and nothing else might be::
|
||||
|
||||
from distutils.core import setup, Extension
|
||||
setup(name='foo',
|
||||
version='1.0',
|
||||
ext_modules=[Extension('foo', ['foo.c'])],
|
||||
)
|
||||
|
||||
The :class:`Extension` class (actually, the underlying extension-building
|
||||
machinery implemented by the :command:`build_ext` command) supports a great deal
|
||||
of flexibility in describing Python extensions, which is explained in the
|
||||
following sections.
|
||||
|
||||
|
||||
Extension names and packages
|
||||
----------------------------
|
||||
|
||||
The first argument to the :class:`~distutils.core.Extension` constructor is
|
||||
always the name of the extension, including any package names. For example, ::
|
||||
|
||||
Extension('foo', ['src/foo1.c', 'src/foo2.c'])
|
||||
|
||||
describes an extension that lives in the root package, while ::
|
||||
|
||||
Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
|
||||
|
||||
describes the same extension in the :mod:`pkg` package. The source files and
|
||||
resulting object code are identical in both cases; the only difference is where
|
||||
in the filesystem (and therefore where in Python's namespace hierarchy) the
|
||||
resulting extension lives.
|
||||
|
||||
If you have a number of extensions all in the same package (or all under the
|
||||
same base package), use the ``ext_package`` keyword argument to
|
||||
:func:`setup`. For example, ::
|
||||
|
||||
setup(...,
|
||||
ext_package='pkg',
|
||||
ext_modules=[Extension('foo', ['foo.c']),
|
||||
Extension('subpkg.bar', ['bar.c'])],
|
||||
)
|
||||
|
||||
will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
|
||||
:mod:`pkg.subpkg.bar`.
|
||||
|
||||
|
||||
Extension source files
|
||||
----------------------
|
||||
|
||||
The second argument to the :class:`~distutils.core.Extension` constructor is
|
||||
a list of source
|
||||
files. Since the Distutils currently only support C, C++, and Objective-C
|
||||
extensions, these are normally C/C++/Objective-C source files. (Be sure to use
|
||||
appropriate extensions to distinguish C++ source files: :file:`.cc` and
|
||||
:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
|
||||
|
||||
However, you can also include SWIG interface (:file:`.i`) files in the list; the
|
||||
:command:`build_ext` command knows how to deal with SWIG extensions: it will run
|
||||
SWIG on the interface file and compile the resulting C/C++ file into your
|
||||
extension.
|
||||
|
||||
.. XXX SWIG support is rough around the edges and largely untested!
|
||||
|
||||
This warning notwithstanding, options to SWIG can be currently passed like
|
||||
this::
|
||||
|
||||
setup(...,
|
||||
ext_modules=[Extension('_foo', ['foo.i'],
|
||||
swig_opts=['-modern', '-I../include'])],
|
||||
py_modules=['foo'],
|
||||
)
|
||||
|
||||
Or on the commandline like this::
|
||||
|
||||
> python setup.py build_ext --swig-opts="-modern -I../include"
|
||||
|
||||
On some platforms, you can include non-source files that are processed by the
|
||||
compiler and included in your extension. Currently, this just means Windows
|
||||
message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
|
||||
Visual C++. These will be compiled to binary resource (:file:`.res`) files and
|
||||
linked into the executable.
|
||||
|
||||
|
||||
Preprocessor options
|
||||
--------------------
|
||||
|
||||
Three optional arguments to :class:`~distutils.core.Extension` will help if
|
||||
you need to specify include directories to search or preprocessor macros to
|
||||
define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``.
|
||||
|
||||
For example, if your extension requires header files in the :file:`include`
|
||||
directory under your distribution root, use the ``include_dirs`` option::
|
||||
|
||||
Extension('foo', ['foo.c'], include_dirs=['include'])
|
||||
|
||||
You can specify absolute directories there; if you know that your extension will
|
||||
only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
|
||||
away with ::
|
||||
|
||||
Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
|
||||
|
||||
You should avoid this sort of non-portable usage if you plan to distribute your
|
||||
code: it's probably better to write C code like ::
|
||||
|
||||
#include <X11/Xlib.h>
|
||||
|
||||
If you need to include header files from some other Python extension, you can
|
||||
take advantage of the fact that header files are installed in a consistent way
|
||||
by the Distutils :command:`install_headers` command. For example, the Numerical
|
||||
Python header files are installed (on a standard Unix installation) to
|
||||
:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
|
||||
according to your platform and Python installation.) Since the Python include
|
||||
directory---\ :file:`/usr/local/include/python1.5` in this case---is always
|
||||
included in the search path when building Python extensions, the best approach
|
||||
is to write C code like ::
|
||||
|
||||
#include <Numerical/arrayobject.h>
|
||||
|
||||
If you must put the :file:`Numerical` include directory right into your header
|
||||
search path, though, you can find that directory using the Distutils
|
||||
:mod:`distutils.sysconfig` module::
|
||||
|
||||
from distutils.sysconfig import get_python_inc
|
||||
incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
|
||||
setup(...,
|
||||
Extension(..., include_dirs=[incdir]),
|
||||
)
|
||||
|
||||
Even though this is quite portable---it will work on any Python installation,
|
||||
regardless of platform---it's probably easier to just write your C code in the
|
||||
sensible way.
|
||||
|
||||
You can define and undefine pre-processor macros with the ``define_macros`` and
|
||||
``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
|
||||
tuples, where ``name`` is the name of the macro to define (a string) and
|
||||
``value`` is its value: either a string or ``None``. (Defining a macro ``FOO``
|
||||
to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
|
||||
most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is
|
||||
just a list of macros to undefine.
|
||||
|
||||
For example::
|
||||
|
||||
Extension(...,
|
||||
define_macros=[('NDEBUG', '1'),
|
||||
('HAVE_STRFTIME', None)],
|
||||
undef_macros=['HAVE_FOO', 'HAVE_BAR'])
|
||||
|
||||
is the equivalent of having this at the top of every C source file::
|
||||
|
||||
#define NDEBUG 1
|
||||
#define HAVE_STRFTIME
|
||||
#undef HAVE_FOO
|
||||
#undef HAVE_BAR
|
||||
|
||||
|
||||
Library options
|
||||
---------------
|
||||
|
||||
You can also specify the libraries to link against when building your extension,
|
||||
and the directories to search for those libraries. The ``libraries`` option is
|
||||
a list of libraries to link against, ``library_dirs`` is a list of directories
|
||||
to search for libraries at link-time, and ``runtime_library_dirs`` is a list of
|
||||
directories to search for shared (dynamically loaded) libraries at run-time.
|
||||
|
||||
For example, if you need to link against libraries known to be in the standard
|
||||
library search path on target systems ::
|
||||
|
||||
Extension(...,
|
||||
libraries=['gdbm', 'readline'])
|
||||
|
||||
If you need to link with libraries in a non-standard location, you'll have to
|
||||
include the location in ``library_dirs``::
|
||||
|
||||
Extension(...,
|
||||
library_dirs=['/usr/X11R6/lib'],
|
||||
libraries=['X11', 'Xt'])
|
||||
|
||||
(Again, this sort of non-portable construct should be avoided if you intend to
|
||||
distribute your code.)
|
||||
|
||||
.. XXX Should mention clib libraries here or somewhere else!
|
||||
|
||||
|
||||
Other options
|
||||
-------------
|
||||
|
||||
There are still some other options which can be used to handle special cases.
|
||||
|
||||
The ``optional`` option is a boolean; if it is true,
|
||||
a build failure in the extension will not abort the build process, but
|
||||
instead simply not install the failing extension.
|
||||
|
||||
The ``extra_objects`` option is a list of object files to be passed to the
|
||||
linker. These files must not have extensions, as the default extension for the
|
||||
compiler is used.
|
||||
|
||||
``extra_compile_args`` and ``extra_link_args`` can be used to
|
||||
specify additional command line options for the respective compiler and linker
|
||||
command lines.
|
||||
|
||||
``export_symbols`` is only useful on Windows. It can contain a list of
|
||||
symbols (functions or variables) to be exported. This option is not needed when
|
||||
building compiled extensions: Distutils will automatically add ``initmodule``
|
||||
to the list of exported symbols.
|
||||
|
||||
The ``depends`` option is a list of files that the extension depends on
|
||||
(for example header files). The build command will call the compiler on the
|
||||
sources to rebuild extension if any on this files has been modified since the
|
||||
previous build.
|
||||
|
||||
Relationships between Distributions and Packages
|
||||
================================================
|
||||
|
||||
A distribution may relate to packages in three specific ways:
|
||||
|
||||
#. It can require packages or modules.
|
||||
|
||||
#. It can provide packages or modules.
|
||||
|
||||
#. It can obsolete packages or modules.
|
||||
|
||||
These relationships can be specified using keyword arguments to the
|
||||
:func:`distutils.core.setup` function.
|
||||
|
||||
Dependencies on other Python modules and packages can be specified by supplying
|
||||
the *requires* keyword argument to :func:`setup`. The value must be a list of
|
||||
strings. Each string specifies a package that is required, and optionally what
|
||||
versions are sufficient.
|
||||
|
||||
To specify that any version of a module or package is required, the string
|
||||
should consist entirely of the module or package name. Examples include
|
||||
``'mymodule'`` and ``'xml.parsers.expat'``.
|
||||
|
||||
If specific versions are required, a sequence of qualifiers can be supplied in
|
||||
parentheses. Each qualifier may consist of a comparison operator and a version
|
||||
number. The accepted comparison operators are::
|
||||
|
||||
< > ==
|
||||
<= >= !=
|
||||
|
||||
These can be combined by using multiple qualifiers separated by commas (and
|
||||
optional whitespace). In this case, all of the qualifiers must be matched; a
|
||||
logical AND is used to combine the evaluations.
|
||||
|
||||
Let's look at a bunch of examples:
|
||||
|
||||
+-------------------------+----------------------------------------------+
|
||||
| Requires Expression | Explanation |
|
||||
+=========================+==============================================+
|
||||
| ``==1.0`` | Only version ``1.0`` is compatible |
|
||||
+-------------------------+----------------------------------------------+
|
||||
| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |
|
||||
| | is compatible, except ``1.5.1`` |
|
||||
+-------------------------+----------------------------------------------+
|
||||
|
||||
Now that we can specify dependencies, we also need to be able to specify what we
|
||||
provide that other distributions can require. This is done using the *provides*
|
||||
keyword argument to :func:`setup`. The value for this keyword is a list of
|
||||
strings, each of which names a Python module or package, and optionally
|
||||
identifies the version. If the version is not specified, it is assumed to match
|
||||
that of the distribution.
|
||||
|
||||
Some examples:
|
||||
|
||||
+---------------------+----------------------------------------------+
|
||||
| Provides Expression | Explanation |
|
||||
+=====================+==============================================+
|
||||
| ``mypkg`` | Provide ``mypkg``, using the distribution |
|
||||
| | version |
|
||||
+---------------------+----------------------------------------------+
|
||||
| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of |
|
||||
| | the distribution version |
|
||||
+---------------------+----------------------------------------------+
|
||||
|
||||
A package can declare that it obsoletes other packages using the *obsoletes*
|
||||
keyword argument. The value for this is similar to that of the *requires*
|
||||
keyword: a list of strings giving module or package specifiers. Each specifier
|
||||
consists of a module or package name optionally followed by one or more version
|
||||
qualifiers. Version qualifiers are given in parentheses after the module or
|
||||
package name.
|
||||
|
||||
The versions identified by the qualifiers are those that are obsoleted by the
|
||||
distribution being described. If no qualifiers are given, all versions of the
|
||||
named module or package are understood to be obsoleted.
|
||||
|
||||
.. _distutils-installing-scripts:
|
||||
|
||||
Installing Scripts
|
||||
==================
|
||||
|
||||
So far we have been dealing with pure and non-pure Python modules, which are
|
||||
usually not run by themselves but imported by scripts.
|
||||
|
||||
Scripts are files containing Python source code, intended to be started from the
|
||||
command line. Scripts don't require Distutils to do anything very complicated.
|
||||
The only clever feature is that if the first line of the script starts with
|
||||
``#!`` and contains the word "python", the Distutils will adjust the first line
|
||||
to refer to the current interpreter location. By default, it is replaced with
|
||||
the current interpreter location. The :option:`!--executable` (or :option:`!-e`)
|
||||
option will allow the interpreter path to be explicitly overridden.
|
||||
|
||||
The ``scripts`` option simply is a list of files to be handled in this
|
||||
way. From the PyXML setup script::
|
||||
|
||||
setup(...,
|
||||
scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
|
||||
)
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
All the scripts will also be added to the ``MANIFEST`` file if no template is
|
||||
provided. See :ref:`manifest`.
|
||||
|
||||
|
||||
.. _distutils-installing-package-data:
|
||||
|
||||
Installing Package Data
|
||||
=======================
|
||||
|
||||
Often, additional files need to be installed into a package. These files are
|
||||
often data that's closely related to the package's implementation, or text files
|
||||
containing documentation that might be of interest to programmers using the
|
||||
package. These files are called :dfn:`package data`.
|
||||
|
||||
Package data can be added to packages using the ``package_data`` keyword
|
||||
argument to the :func:`setup` function. The value must be a mapping from
|
||||
package name to a list of relative path names that should be copied into the
|
||||
package. The paths are interpreted as relative to the directory containing the
|
||||
package (information from the ``package_dir`` mapping is used if appropriate);
|
||||
that is, the files are expected to be part of the package in the source
|
||||
directories. They may contain glob patterns as well.
|
||||
|
||||
The path names may contain directory portions; any necessary directories will be
|
||||
created in the installation.
|
||||
|
||||
For example, if a package should contain a subdirectory with several data files,
|
||||
the files can be arranged like this in the source tree::
|
||||
|
||||
setup.py
|
||||
src/
|
||||
mypkg/
|
||||
__init__.py
|
||||
module.py
|
||||
data/
|
||||
tables.dat
|
||||
spoons.dat
|
||||
forks.dat
|
||||
|
||||
The corresponding call to :func:`setup` might be::
|
||||
|
||||
setup(...,
|
||||
packages=['mypkg'],
|
||||
package_dir={'mypkg': 'src/mypkg'},
|
||||
package_data={'mypkg': ['data/*.dat']},
|
||||
)
|
||||
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
All the files that match ``package_data`` will be added to the ``MANIFEST``
|
||||
file if no template is provided. See :ref:`manifest`.
|
||||
|
||||
|
||||
.. _distutils-additional-files:
|
||||
|
||||
Installing Additional Files
|
||||
===========================
|
||||
|
||||
The ``data_files`` option can be used to specify additional files needed
|
||||
by the module distribution: configuration files, message catalogs, data files,
|
||||
anything which doesn't fit in the previous categories.
|
||||
|
||||
``data_files`` specifies a sequence of (*directory*, *files*) pairs in the
|
||||
following way::
|
||||
|
||||
setup(...,
|
||||
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
|
||||
('config', ['cfg/data.cfg'])],
|
||||
)
|
||||
|
||||
Each (*directory*, *files*) pair in the sequence specifies the installation
|
||||
directory and the files to install there.
|
||||
|
||||
Each file name in *files* is interpreted relative to the :file:`setup.py`
|
||||
script at the top of the package source distribution. Note that you can
|
||||
specify the directory where the data files will be installed, but you cannot
|
||||
rename the data files themselves.
|
||||
|
||||
The *directory* should be a relative path. It is interpreted relative to the
|
||||
installation prefix (Python's ``sys.prefix`` for system installations;
|
||||
``site.USER_BASE`` for user installations). Distutils allows *directory* to be
|
||||
an absolute installation path, but this is discouraged since it is
|
||||
incompatible with the wheel packaging format. No directory information from
|
||||
*files* is used to determine the final location of the installed file; only
|
||||
the name of the file is used.
|
||||
|
||||
You can specify the ``data_files`` options as a simple sequence of files
|
||||
without specifying a target directory, but this is not recommended, and the
|
||||
:command:`install` command will print a warning in this case. To install data
|
||||
files directly in the target directory, an empty string should be given as the
|
||||
directory.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
All the files that match ``data_files`` will be added to the ``MANIFEST``
|
||||
file if no template is provided. See :ref:`manifest`.
|
||||
|
||||
|
||||
.. _meta-data:
|
||||
|
||||
Additional meta-data
|
||||
====================
|
||||
|
||||
The setup script may include additional meta-data beyond the name and version.
|
||||
This information includes:
|
||||
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| Meta-Data | Description | Value | Notes |
|
||||
+======================+===========================+=================+========+
|
||||
| ``name`` | name of the package | short string | \(1) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``version`` | version of this release | short string | (1)(2) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``author`` | package author's name | short string | \(3) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``author_email`` | email address of the | email address | \(3) |
|
||||
| | package author | | |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``maintainer`` | package maintainer's name | short string | \(3) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``maintainer_email`` | email address of the | email address | \(3) |
|
||||
| | package maintainer | | |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``url`` | home page for the package | URL | \(1) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``description`` | short, summary | short string | |
|
||||
| | description of the | | |
|
||||
| | package | | |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``long_description`` | longer description of the | long string | \(4) |
|
||||
| | package | | |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``download_url`` | location where the | URL | |
|
||||
| | package may be downloaded | | |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``classifiers`` | a list of classifiers | list of strings | (6)(7) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``platforms`` | a list of platforms | list of strings | (6)(8) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``keywords`` | a list of keywords | list of strings | (6)(8) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
| ``license`` | license for the package | short string | \(5) |
|
||||
+----------------------+---------------------------+-----------------+--------+
|
||||
|
||||
Notes:
|
||||
|
||||
(1)
|
||||
These fields are required.
|
||||
|
||||
(2)
|
||||
It is recommended that versions take the form *major.minor[.patch[.sub]]*.
|
||||
|
||||
(3)
|
||||
Either the author or the maintainer must be identified. If maintainer is
|
||||
provided, distutils lists it as the author in :file:`PKG-INFO`.
|
||||
|
||||
(4)
|
||||
The ``long_description`` field is used by PyPI when you publish a package,
|
||||
to build its project page.
|
||||
|
||||
(5)
|
||||
The ``license`` field is a text indicating the license covering the
|
||||
package where the license is not a selection from the "License" Trove
|
||||
classifiers. See the ``Classifier`` field. Notice that
|
||||
there's a ``licence`` distribution option which is deprecated but still
|
||||
acts as an alias for ``license``.
|
||||
|
||||
(6)
|
||||
This field must be a list.
|
||||
|
||||
(7)
|
||||
The valid classifiers are listed on
|
||||
`PyPI <https://pypi.org/classifiers>`_.
|
||||
|
||||
(8)
|
||||
To preserve backward compatibility, this field also accepts a string. If
|
||||
you pass a comma-separated string ``'foo, bar'``, it will be converted to
|
||||
``['foo', 'bar']``, Otherwise, it will be converted to a list of one
|
||||
string.
|
||||
|
||||
'short string'
|
||||
A single line of text, not more than 200 characters.
|
||||
|
||||
'long string'
|
||||
Multiple lines of plain text in reStructuredText format (see
|
||||
http://docutils.sourceforge.net/).
|
||||
|
||||
'list of strings'
|
||||
See below.
|
||||
|
||||
Encoding the version information is an art in itself. Python packages generally
|
||||
adhere to the version format *major.minor[.patch][sub]*. The major number is 0
|
||||
for initial, experimental releases of software. It is incremented for releases
|
||||
that represent major milestones in a package. The minor number is incremented
|
||||
when important new features are added to the package. The patch number
|
||||
increments when bug-fix releases are made. Additional trailing version
|
||||
information is sometimes used to indicate sub-releases. These are
|
||||
"a1,a2,...,aN" (for alpha releases, where functionality and API may change),
|
||||
"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"
|
||||
(for final pre-release release testing). Some examples:
|
||||
|
||||
0.1.0
|
||||
the first, experimental release of a package
|
||||
|
||||
1.0.1a2
|
||||
the second alpha release of the first patch version of 1.0
|
||||
|
||||
``classifiers`` must be specified in a list::
|
||||
|
||||
setup(...,
|
||||
classifiers=[
|
||||
'Development Status :: 4 - Beta',
|
||||
'Environment :: Console',
|
||||
'Environment :: Web Environment',
|
||||
'Intended Audience :: End Users/Desktop',
|
||||
'Intended Audience :: Developers',
|
||||
'Intended Audience :: System Administrators',
|
||||
'License :: OSI Approved :: Python Software Foundation License',
|
||||
'Operating System :: MacOS :: MacOS X',
|
||||
'Operating System :: Microsoft :: Windows',
|
||||
'Operating System :: POSIX',
|
||||
'Programming Language :: Python',
|
||||
'Topic :: Communications :: Email',
|
||||
'Topic :: Office/Business',
|
||||
'Topic :: Software Development :: Bug Tracking',
|
||||
],
|
||||
)
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
:class:`~distutils.core.setup` now warns when ``classifiers``, ``keywords``
|
||||
or ``platforms`` fields are not specified as a list or a string.
|
||||
|
||||
.. _debug-setup-script:
|
||||
|
||||
Debugging the setup script
|
||||
==========================
|
||||
|
||||
Sometimes things go wrong, and the setup script doesn't do what the developer
|
||||
wants.
|
||||
|
||||
Distutils catches any exceptions when running the setup script, and print a
|
||||
simple error message before the script is terminated. The motivation for this
|
||||
behaviour is to not confuse administrators who don't know much about Python and
|
||||
are trying to install a package. If they get a big long traceback from deep
|
||||
inside the guts of Distutils, they may think the package or the Python
|
||||
installation is broken because they don't read all the way down to the bottom
|
||||
and see that it's a permission problem.
|
||||
|
||||
On the other hand, this doesn't help the developer to find the cause of the
|
||||
failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set
|
||||
to anything except an empty string, and distutils will now print detailed
|
||||
information about what it is doing, dump the full traceback when an exception
|
||||
occurs, and print the whole command line when an external program (like a C
|
||||
compiler) fails.
|
||||
|
|
@ -1,245 +0,0 @@
|
|||
.. _source-dist:
|
||||
|
||||
******************************
|
||||
Creating a Source Distribution
|
||||
******************************
|
||||
|
||||
.. include:: ./_setuptools_disclaimer.rst
|
||||
|
||||
As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
|
||||
to create a source distribution. In the simplest case, ::
|
||||
|
||||
python setup.py sdist
|
||||
|
||||
(assuming you haven't specified any :command:`sdist` options in the setup script
|
||||
or config file), :command:`sdist` creates the archive of the default format for
|
||||
the current platform. The default format is a gzip'ed tar file
|
||||
(:file:`.tar.gz`) on Unix, and ZIP file on Windows.
|
||||
|
||||
You can specify as many formats as you like using the :option:`!--formats`
|
||||
option, for example::
|
||||
|
||||
python setup.py sdist --formats=gztar,zip
|
||||
|
||||
to create a gzipped tarball and a zip file. The available formats are:
|
||||
|
||||
+-----------+-------------------------+-------------+
|
||||
| Format | Description | Notes |
|
||||
+===========+=========================+=============+
|
||||
| ``zip`` | zip file (:file:`.zip`) | (1),(3) |
|
||||
+-----------+-------------------------+-------------+
|
||||
| ``gztar`` | gzip'ed tar file | \(2) |
|
||||
| | (:file:`.tar.gz`) | |
|
||||
+-----------+-------------------------+-------------+
|
||||
| ``bztar`` | bzip2'ed tar file | \(5) |
|
||||
| | (:file:`.tar.bz2`) | |
|
||||
+-----------+-------------------------+-------------+
|
||||
| ``xztar`` | xz'ed tar file | \(5) |
|
||||
| | (:file:`.tar.xz`) | |
|
||||
+-----------+-------------------------+-------------+
|
||||
| ``ztar`` | compressed tar file | (4),(5) |
|
||||
| | (:file:`.tar.Z`) | |
|
||||
+-----------+-------------------------+-------------+
|
||||
| ``tar`` | tar file (:file:`.tar`) | \(5) |
|
||||
+-----------+-------------------------+-------------+
|
||||
|
||||
.. versionchanged:: 3.5
|
||||
Added support for the ``xztar`` format.
|
||||
|
||||
Notes:
|
||||
|
||||
(1)
|
||||
default on Windows
|
||||
|
||||
(2)
|
||||
default on Unix
|
||||
|
||||
(3)
|
||||
requires either external :program:`zip` utility or :mod:`zipfile` module (part
|
||||
of the standard Python library since Python 1.6)
|
||||
|
||||
(4)
|
||||
requires the :program:`compress` program. Notice that this format is now
|
||||
pending for deprecation and will be removed in the future versions of Python.
|
||||
(5)
|
||||
deprecated by `PEP 527 <https://peps.python.org/pep-0527/>`_;
|
||||
`PyPI <https://pypi.org>`_ only accepts ``.zip`` and ``.tar.gz`` files.
|
||||
|
||||
When using any ``tar`` format (``gztar``, ``bztar``, ``xztar``, ``ztar`` or
|
||||
``tar``), under Unix you can specify the ``owner`` and ``group`` names
|
||||
that will be set for each member of the archive.
|
||||
|
||||
For example, if you want all files of the archive to be owned by root::
|
||||
|
||||
python setup.py sdist --owner=root --group=root
|
||||
|
||||
|
||||
.. _manifest:
|
||||
|
||||
Specifying the files to distribute
|
||||
==================================
|
||||
|
||||
If you don't supply an explicit list of files (or instructions on how to
|
||||
generate one), the :command:`sdist` command puts a minimal default set into the
|
||||
source distribution:
|
||||
|
||||
* all Python source files implied by the ``py_modules`` and
|
||||
``packages`` options
|
||||
|
||||
* all C source files mentioned in the ``ext_modules`` or
|
||||
``libraries`` options
|
||||
|
||||
.. XXX getting C library sources currently broken---no
|
||||
:meth:`get_source_files` method in :file:`build_clib.py`!
|
||||
|
||||
* scripts identified by the ``scripts`` option
|
||||
See :ref:`distutils-installing-scripts`.
|
||||
|
||||
* anything that looks like a test script: :file:`test/test\*.py` (currently, the
|
||||
Distutils don't do anything with test scripts except include them in source
|
||||
distributions, but in the future there will be a standard for testing Python
|
||||
module distributions)
|
||||
|
||||
* Any of the standard README files (:file:`README`, :file:`README.txt`,
|
||||
or :file:`README.rst`), :file:`setup.py` (or whatever you called your setup
|
||||
script), and :file:`setup.cfg`.
|
||||
|
||||
* all files that matches the ``package_data`` metadata.
|
||||
See :ref:`distutils-installing-package-data`.
|
||||
|
||||
* all files that matches the ``data_files`` metadata.
|
||||
See :ref:`distutils-additional-files`.
|
||||
|
||||
Sometimes this is enough, but usually you will want to specify additional files
|
||||
to distribute. The typical way to do this is to write a *manifest template*,
|
||||
called :file:`MANIFEST.in` by default. The manifest template is just a list of
|
||||
instructions for how to generate your manifest file, :file:`MANIFEST`, which is
|
||||
the exact list of files to include in your source distribution. The
|
||||
:command:`sdist` command processes this template and generates a manifest based
|
||||
on its instructions and what it finds in the filesystem.
|
||||
|
||||
If you prefer to roll your own manifest file, the format is simple: one filename
|
||||
per line, regular files (or symlinks to them) only. If you do supply your own
|
||||
:file:`MANIFEST`, you must specify everything: the default set of files
|
||||
described above does not apply in this case.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
An existing generated :file:`MANIFEST` will be regenerated without
|
||||
:command:`sdist` comparing its modification time to the one of
|
||||
:file:`MANIFEST.in` or :file:`setup.py`.
|
||||
|
||||
.. versionchanged:: 3.1.3
|
||||
:file:`MANIFEST` files start with a comment indicating they are generated.
|
||||
Files without this comment are not overwritten or removed.
|
||||
|
||||
.. versionchanged:: 3.2.2
|
||||
:command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in`
|
||||
exists, like it used to do.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
:file:`README.rst` is now included in the list of distutils standard READMEs.
|
||||
|
||||
|
||||
The manifest template has one command per line, where each command specifies a
|
||||
set of files to include or exclude from the source distribution. For an
|
||||
example, again we turn to the Distutils' own manifest template:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
include *.txt
|
||||
recursive-include examples *.txt *.py
|
||||
prune examples/sample?/build
|
||||
|
||||
The meanings should be fairly clear: include all files in the distribution root
|
||||
matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory
|
||||
matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
|
||||
:file:`examples/sample?/build`. All of this is done *after* the standard
|
||||
include set, so you can exclude files from the standard set with explicit
|
||||
instructions in the manifest template. (Or, you can use the
|
||||
:option:`!--no-defaults` option to disable the standard set entirely.) There are
|
||||
several other commands available in the manifest template mini-language; see
|
||||
section :ref:`sdist-cmd`.
|
||||
|
||||
The order of commands in the manifest template matters: initially, we have the
|
||||
list of default files as described above, and each command in the template adds
|
||||
to or removes from that list of files. Once we have fully processed the
|
||||
manifest template, we remove files that should not be included in the source
|
||||
distribution:
|
||||
|
||||
* all files in the Distutils "build" tree (default :file:`build/`)
|
||||
|
||||
* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`,
|
||||
:file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs`
|
||||
|
||||
Now we have our complete list of files, which is written to the manifest for
|
||||
future reference, and then used to build the source distribution archive(s).
|
||||
|
||||
You can disable the default set of included files with the
|
||||
:option:`!--no-defaults` option, and you can disable the standard exclude set
|
||||
with :option:`!--no-prune`.
|
||||
|
||||
Following the Distutils' own manifest template, let's trace how the
|
||||
:command:`sdist` command builds the list of files to include in the Distutils
|
||||
source distribution:
|
||||
|
||||
#. include all Python source files in the :file:`distutils` and
|
||||
:file:`distutils/command` subdirectories (because packages corresponding to
|
||||
those two directories were mentioned in the ``packages`` option in the
|
||||
setup script---see section :ref:`setup-script`)
|
||||
|
||||
#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
|
||||
files)
|
||||
|
||||
#. include :file:`test/test\*.py` (standard files)
|
||||
|
||||
#. include :file:`\*.txt` in the distribution root (this will find
|
||||
:file:`README.txt` a second time, but such redundancies are weeded out later)
|
||||
|
||||
#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree
|
||||
under :file:`examples`,
|
||||
|
||||
#. exclude all files in the sub-trees starting at directories matching
|
||||
:file:`examples/sample?/build`\ ---this may exclude files included by the
|
||||
previous two steps, so it's important that the ``prune`` command in the manifest
|
||||
template comes after the ``recursive-include`` command
|
||||
|
||||
#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`,
|
||||
:file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs`
|
||||
directories
|
||||
|
||||
Just like in the setup script, file and directory names in the manifest template
|
||||
should always be slash-separated; the Distutils will take care of converting
|
||||
them to the standard representation on your platform. That way, the manifest
|
||||
template is portable across operating systems.
|
||||
|
||||
|
||||
.. _manifest-options:
|
||||
|
||||
Manifest-related options
|
||||
========================
|
||||
|
||||
The normal course of operations for the :command:`sdist` command is as follows:
|
||||
|
||||
* if the manifest file (:file:`MANIFEST` by default) exists and the first line
|
||||
does not have a comment indicating it is generated from :file:`MANIFEST.in`,
|
||||
then it is used as is, unaltered
|
||||
|
||||
* if the manifest file doesn't exist or has been previously automatically
|
||||
generated, read :file:`MANIFEST.in` and create the manifest
|
||||
|
||||
* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
|
||||
with just the default file set
|
||||
|
||||
* use the list of files now in :file:`MANIFEST` (either just generated or read
|
||||
in) to create the source distribution archive(s)
|
||||
|
||||
There are a couple of options that modify this behaviour. First, use the
|
||||
:option:`!--no-defaults` and :option:`!--no-prune` to disable the standard
|
||||
"include" and "exclude" sets.
|
||||
|
||||
Second, you might just want to (re)generate the manifest, but not create a source
|
||||
distribution::
|
||||
|
||||
python setup.py sdist --manifest-only
|
||||
|
||||
:option:`!-o` is a shortcut for :option:`!--manifest-only`.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
:orphan:
|
||||
|
||||
***************************************
|
||||
Uploading Packages to the Package Index
|
||||
***************************************
|
||||
|
||||
References to up to date PyPI documentation can be found at
|
||||
:ref:`publishing-python-packages`.
|
||||
|
|
@ -11,7 +11,7 @@ A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
|
|||
|
||||
To be importable, the shared library must be available on :envvar:`PYTHONPATH`,
|
||||
and must be named after the module name, with an appropriate extension.
|
||||
When using distutils, the correct filename is generated automatically.
|
||||
When using setuptools, the correct filename is generated automatically.
|
||||
|
||||
The initialization function has the signature:
|
||||
|
||||
|
|
@ -45,122 +45,12 @@ See the *"Multiple modules in one library"* section in :pep:`489` for details.
|
|||
|
||||
.. highlight:: c
|
||||
|
||||
Building C and C++ Extensions with distutils
|
||||
============================================
|
||||
.. _setuptools-index:
|
||||
|
||||
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
|
||||
Building C and C++ Extensions with setuptools
|
||||
=============================================
|
||||
|
||||
Extension modules can be built using distutils, which is included in Python.
|
||||
Since distutils also supports creation of binary packages, users don't
|
||||
necessarily need a compiler and distutils to install the extension.
|
||||
|
||||
A distutils package contains a driver script, :file:`setup.py`. This is a plain
|
||||
Python file, which, in the most simple case, could look like this:
|
||||
|
||||
.. code-block:: python3
|
||||
|
||||
from distutils.core import setup, Extension
|
||||
|
||||
module1 = Extension('demo',
|
||||
sources = ['demo.c'])
|
||||
|
||||
setup (name = 'PackageName',
|
||||
version = '1.0',
|
||||
description = 'This is a demo package',
|
||||
ext_modules = [module1])
|
||||
|
||||
|
||||
With this :file:`setup.py`, and a file :file:`demo.c`, running ::
|
||||
|
||||
python setup.py build
|
||||
|
||||
will compile :file:`demo.c`, and produce an extension module named ``demo`` in
|
||||
the :file:`build` directory. Depending on the system, the module file will end
|
||||
up in a subdirectory :file:`build/lib.system`, and may have a name like
|
||||
:file:`demo.so` or :file:`demo.pyd`.
|
||||
|
||||
In the :file:`setup.py`, all execution is performed by calling the ``setup``
|
||||
function. This takes a variable number of keyword arguments, of which the
|
||||
example above uses only a subset. Specifically, the example specifies
|
||||
meta-information to build packages, and it specifies the contents of the
|
||||
package. Normally, a package will contain additional modules, like Python
|
||||
source modules, documentation, subpackages, etc. Please refer to the distutils
|
||||
documentation in :ref:`distutils-index` to learn more about the features of
|
||||
distutils; this section explains building extension modules only.
|
||||
|
||||
It is common to pre-compute arguments to :func:`setup`, to better structure the
|
||||
driver script. In the example above, the ``ext_modules`` argument to
|
||||
:func:`~distutils.core.setup` is a list of extension modules, each of which is
|
||||
an instance of
|
||||
the :class:`~distutils.extension.Extension`. In the example, the instance
|
||||
defines an extension named ``demo`` which is build by compiling a single source
|
||||
file, :file:`demo.c`.
|
||||
|
||||
In many cases, building an extension is more complex, since additional
|
||||
preprocessor defines and libraries may be needed. This is demonstrated in the
|
||||
example below.
|
||||
|
||||
.. code-block:: python3
|
||||
|
||||
from distutils.core import setup, Extension
|
||||
|
||||
module1 = Extension('demo',
|
||||
define_macros = [('MAJOR_VERSION', '1'),
|
||||
('MINOR_VERSION', '0')],
|
||||
include_dirs = ['/usr/local/include'],
|
||||
libraries = ['tcl83'],
|
||||
library_dirs = ['/usr/local/lib'],
|
||||
sources = ['demo.c'])
|
||||
|
||||
setup (name = 'PackageName',
|
||||
version = '1.0',
|
||||
description = 'This is a demo package',
|
||||
author = 'Martin v. Loewis',
|
||||
author_email = 'martin@v.loewis.de',
|
||||
url = 'https://docs.python.org/extending/building',
|
||||
long_description = '''
|
||||
This is really just a demo package.
|
||||
''',
|
||||
ext_modules = [module1])
|
||||
|
||||
|
||||
In this example, :func:`~distutils.core.setup` is called with additional
|
||||
meta-information, which
|
||||
is recommended when distribution packages have to be built. For the extension
|
||||
itself, it specifies preprocessor defines, include directories, library
|
||||
directories, and libraries. Depending on the compiler, distutils passes this
|
||||
information in different ways to the compiler. For example, on Unix, this may
|
||||
result in the compilation commands ::
|
||||
|
||||
gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
|
||||
|
||||
gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
|
||||
|
||||
These lines are for demonstration purposes only; distutils users should trust
|
||||
that distutils gets the invocations right.
|
||||
|
||||
|
||||
.. _distributing:
|
||||
|
||||
Distributing your extension modules
|
||||
===================================
|
||||
|
||||
When an extension has been successfully built, there are three ways to use it.
|
||||
|
||||
End-users will typically want to install the module, they do so by running ::
|
||||
|
||||
python setup.py install
|
||||
|
||||
Module maintainers should produce source packages; to do so, they run ::
|
||||
|
||||
python setup.py sdist
|
||||
|
||||
In some cases, additional files need to be included in a source distribution;
|
||||
this is done through a :file:`MANIFEST.in` file; see :ref:`manifest` for details.
|
||||
|
||||
If the source distribution has been built successfully, maintainers can also
|
||||
create binary distributions. Depending on the platform, one of the following
|
||||
commands can be used to do so. ::
|
||||
|
||||
python setup.py bdist_rpm
|
||||
python setup.py bdist_dumb
|
||||
Python 3.12 and newer no longer come with distutils. Please refer to the
|
||||
``setuptools`` documentation at
|
||||
https://setuptools.readthedocs.io/en/latest/setuptools.html
|
||||
to learn more about how build and distribute C/C++ extensions with setuptools.
|
||||
|
|
|
|||
|
|
@ -34,10 +34,10 @@ A Cookbook Approach
|
|||
===================
|
||||
|
||||
There are two approaches to building extension modules on Windows, just as there
|
||||
are on Unix: use the :mod:`distutils` package to control the build process, or
|
||||
do things manually. The distutils approach works well for most extensions;
|
||||
documentation on using :mod:`distutils` to build and package extension modules
|
||||
is available in :ref:`distutils-index`. If you find you really need to do
|
||||
are on Unix: use the ``setuptools`` package to control the build process, or
|
||||
do things manually. The setuptools approach works well for most extensions;
|
||||
documentation on using ``setuptools`` to build and package extension modules
|
||||
is available in :ref:`setuptools-index`. If you find you really need to do
|
||||
things manually, it may be instructive to study the project file for the
|
||||
:source:`winsound <PCbuild/winsound.vcxproj>` standard library module.
|
||||
|
||||
|
|
|
|||
|
|
@ -23,7 +23,11 @@
|
|||
The up to date module installation documentation. For regular Python
|
||||
usage, you almost certainly want that document rather than this one.
|
||||
|
||||
.. include:: ../distutils/_setuptools_disclaimer.rst
|
||||
.. note::
|
||||
|
||||
This document is being retained solely until the ``setuptools`` documentation
|
||||
at https://setuptools.readthedocs.io/en/latest/setuptools.html
|
||||
independently covers all of the relevant information currently included here.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,6 @@ with a local index server, or without any index server at all.
|
|||
|
||||
.. toctree::
|
||||
|
||||
distutils.rst
|
||||
ensurepip.rst
|
||||
venv.rst
|
||||
zipapp.rst
|
||||
|
|
|
|||
|
|
@ -1,49 +0,0 @@
|
|||
:mod:`distutils` --- Building and installing Python modules
|
||||
===========================================================
|
||||
|
||||
.. module:: distutils
|
||||
:synopsis: Support for building and installing Python modules into an
|
||||
existing Python installation.
|
||||
|
||||
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
|
||||
|
||||
--------------
|
||||
|
||||
:mod:`distutils` is deprecated with removal planned for Python 3.12.
|
||||
See the :ref:`What's New <distutils-deprecated>` entry for more information.
|
||||
|
||||
--------------
|
||||
|
||||
The :mod:`distutils` package provides support for building and installing
|
||||
additional modules into a Python installation. The new modules may be either
|
||||
100%-pure Python, or may be extension modules written in C, or may be
|
||||
collections of Python packages which include modules coded in both Python and C.
|
||||
|
||||
Most Python users will *not* want to use this module directly, but instead
|
||||
use the cross-version tools maintained by the Python Packaging Authority. In
|
||||
particular,
|
||||
`setuptools <https://setuptools.readthedocs.io/en/latest/>`__ is an
|
||||
enhanced alternative to :mod:`distutils` that provides:
|
||||
|
||||
* support for declaring project dependencies
|
||||
* additional mechanisms for configuring which files to include in source
|
||||
releases (including plugins for integration with version control systems)
|
||||
* the ability to declare project "entry points", which can be used as the
|
||||
basis for application plugin systems
|
||||
* the ability to automatically generate Windows command line executables at
|
||||
installation time rather than needing to prebuild them
|
||||
* consistent behaviour across all supported Python versions
|
||||
|
||||
The recommended `pip <https://pip.pypa.io/>`__ installer runs all
|
||||
``setup.py`` scripts with ``setuptools``, even if the script itself only
|
||||
imports ``distutils``. Refer to the
|
||||
`Python Packaging User Guide <https://packaging.python.org>`_ for more
|
||||
information.
|
||||
|
||||
For the benefits of packaging tool authors and users seeking a deeper
|
||||
understanding of the details of the current packaging and distribution
|
||||
system, the legacy :mod:`distutils` based user documentation and API
|
||||
reference remain available:
|
||||
|
||||
* :ref:`install-index`
|
||||
* :ref:`distutils-index`
|
||||
|
|
@ -25,7 +25,7 @@ Configuration variables
|
|||
|
||||
A Python distribution contains a :file:`Makefile` and a :file:`pyconfig.h`
|
||||
header file that are necessary to build both the Python binary itself and
|
||||
third-party C extensions compiled using :mod:`distutils`.
|
||||
third-party C extensions compiled using ``setuptools``.
|
||||
|
||||
:mod:`sysconfig` puts all variables found in these files in a dictionary that
|
||||
can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ Creating virtual environments
|
|||
Python installation).
|
||||
|
||||
When a virtual environment is active, any options that change the
|
||||
installation path will be ignored from all :mod:`distutils` configuration
|
||||
installation path will be ignored from all ``setuptools`` configuration
|
||||
files to prevent projects being inadvertently installed outside of the
|
||||
virtual environment.
|
||||
|
||||
|
|
|
|||
|
|
@ -599,7 +599,7 @@ Main files of the build system
|
|||
* :file:`pyconfig.h` (created by :file:`configure`);
|
||||
* :file:`Modules/Setup`: C extensions built by the Makefile using
|
||||
:file:`Module/makesetup` shell script;
|
||||
* :file:`setup.py`: C extensions built using the :mod:`distutils` module.
|
||||
* :file:`setup.py`: C extensions built using the ``setuptools`` package.
|
||||
|
||||
Main build steps
|
||||
----------------
|
||||
|
|
|
|||
|
|
@ -1187,11 +1187,10 @@ shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
|
|||
cx_Freeze
|
||||
---------
|
||||
|
||||
`cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ is a :mod:`distutils`
|
||||
extension (see :ref:`extending-distutils`) which wraps Python scripts into
|
||||
executable Windows programs (:file:`{*}.exe` files). When you have done this,
|
||||
you can distribute your application without requiring your users to install
|
||||
Python.
|
||||
`cx_Freeze <https://cx-freeze.readthedocs.io/en/latest/>`_ is a ``distutils``
|
||||
extension which wraps Python scripts into executable Windows programs
|
||||
(:file:`{*}.exe` files). When you have done this, you can distribute your
|
||||
application without requiring your users to install Python.
|
||||
|
||||
|
||||
Compiling Python on Windows
|
||||
|
|
|
|||
|
|
@ -2697,7 +2697,7 @@ projects.
|
|||
|
||||
However, as this migration is currently still incomplete, the legacy
|
||||
versions of those guides remaining available as :ref:`install-index`
|
||||
and :ref:`distutils-index`.
|
||||
and :ref:`setuptools-index`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
|
|||
|
|
@ -247,7 +247,7 @@ projects.
|
|||
|
||||
However, as this migration is currently still incomplete, the legacy
|
||||
versions of those guides remaining available as :ref:`install-index`
|
||||
and :ref:`distutils-index`.
|
||||
and :ref:`setuptools-index`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue