mirror of
https://github.com/python/cpython.git
synced 2025-08-04 17:08:35 +00:00
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
25 changed files with 26 additions and 4543 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue