mirror of
https://github.com/python/cpython.git
synced 2024-12-14 04:17:19 +08:00
a566912049
Most places now refer to setuptools or link to setuptools documentation. Some examples like zipapp need to be updated later.
57 lines
2.1 KiB
ReStructuredText
57 lines
2.1 KiB
ReStructuredText
.. highlight:: c
|
|
|
|
.. _building:
|
|
|
|
*****************************
|
|
Building C and C++ Extensions
|
|
*****************************
|
|
|
|
A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
|
|
``.pyd`` on Windows), which exports an *initialization function*.
|
|
|
|
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 setuptools, the correct filename is generated automatically.
|
|
|
|
The initialization function has the signature:
|
|
|
|
.. c:function:: PyObject* PyInit_modulename(void)
|
|
|
|
It returns either a fully initialized module, or a :c:type:`PyModuleDef`
|
|
instance. See :ref:`initializing-modules` for details.
|
|
|
|
.. highlight:: python
|
|
|
|
For modules with ASCII-only names, the function must be named
|
|
``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the
|
|
module. When using :ref:`multi-phase-initialization`, non-ASCII module names
|
|
are allowed. In this case, the initialization function name is
|
|
``PyInitU_<modulename>``, with ``<modulename>`` encoded using Python's
|
|
*punycode* encoding with hyphens replaced by underscores. In Python::
|
|
|
|
def initfunc_name(name):
|
|
try:
|
|
suffix = b'_' + name.encode('ascii')
|
|
except UnicodeEncodeError:
|
|
suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
|
|
return b'PyInit' + suffix
|
|
|
|
It is possible to export multiple modules from a single shared library by
|
|
defining multiple initialization functions. However, importing them requires
|
|
using symbolic links or a custom importer, because by default only the
|
|
function corresponding to the filename is found.
|
|
See the *"Multiple modules in one library"* section in :pep:`489` for details.
|
|
|
|
|
|
.. highlight:: c
|
|
|
|
.. _setuptools-index:
|
|
|
|
Building C and C++ Extensions with setuptools
|
|
=============================================
|
|
|
|
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.
|