1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
==========================
Building Extension Modules
==========================
Setuptools can build C/C++ extension modules. The keyword argument
``ext_modules`` of ``setup()`` should be a list of instances of the
:class:`setuptools.Extension` class.
For example, let's consider a simple project with only one extension module::
<project_folder>
├── pyproject.toml
└── foo.c
and all project metadata configuration in the ``pyproject.toml`` file:
.. code-block:: toml
# pyproject.toml
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"
[project]
name = "mylib-foo" # as it would appear on PyPI
version = "0.42"
To instruct setuptools to compile the ``foo.c`` file into the extension module
``mylib.foo``, we need to add a ``setup.py`` file similar to the following:
.. code-block:: python
from setuptools import Extension, setup
setup(
ext_modules=[
Extension(
name="mylib.foo", # as it would be imported
# may include packages/namespaces separated by `.`
sources=["foo.c"], # all sources are compiled into a single binary file
),
]
)
.. seealso::
You can find more information on the `Python docs about C/C++ extensions`_.
Alternatively, you might also be interested in learn about `Cython`_.
If you plan to distribute a package that uses extensions across multiple
platforms, :pypi:`cibuildwheel` can also be helpful.
Compiler and linker options
===========================
The command ``build_ext`` builds C/C++ extension modules. It creates
a command line for running the compiler and linker by combining
compiler and linker options from various sources:
.. Reference: `test_customize_compiler` in distutils/tests/test_sysconfig.py
* the ``sysconfig`` variables ``CC``, ``CXX``, ``CCSHARED``,
``LDSHARED``, and ``CFLAGS``,
* the environment variables ``CC``, ``CPP``,
``CXX``, ``LDSHARED`` and ``LDFLAGS``,
``CFLAGS``, ``CPPFLAGS``, ``LDFLAGS``,
* the ``Extension`` attributes ``include_dirs``,
``library_dirs``, ``extra_compile_args``, ``extra_link_args``,
``runtime_library_dirs``.
.. Ignoring AR, ARFLAGS, RANLIB here because they are used by the (obsolete?) build_clib, not build_ext.
The resulting command line is then processed by the compiler and linker.
According to the GCC manual sections on `directory options`_ and
`environment variables`_, the C/C++ compiler searches for files named in
``#include <file>`` directives in the following order:
* first, in directories given by ``-I`` options (in left-to-right order),
* then, in directories given by the environment variable ``CPATH`` (in left-to-right order),
* then, in directories given by ``-isystem`` options (in left-to-right order),
* then, in directories given by the environment variable ``C_INCLUDE_PATH`` (for C) and ``CPLUS_INCLUDE_PATH`` (for C++),
* then, in standard system directories,
* finally, in directories given by ``-idirafter`` options (in left-to-right order).
The linker searches for libraries in the following order:
* first, in directories given by ``-L`` options (in left-to-right order),
* then, in directories given by the environment variable ``LIBRARY_PATH`` (in left-to-right order).
.. important::
All files used to compile your extension need to be available on the system
in the moment setuptools builds your project, so please make sure to include some
documentation on how users can obtain operating system level dependencies
(e.g. compilers and external binary libraries/artifacts).
You will also need to make sure that all auxiliary files that are contained
inside your :term:`project` (e.g. C headers authored by you or your team)
are configured to be included in your :term:`sdist <Source Distribution (or "sdist")>`.
Please have a look on our section on :ref:`Controlling files in the distribution`.
----
API Reference
-------------
.. autoclass:: setuptools.Extension
.. _Python docs about C/C++ extensions: https://docs.python.org/3/extending/extending.html
.. _Cython: https://cython.readthedocs.io/en/stable/index.html
.. _directory options: https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html
.. _environment variables: https://gcc.gnu.org/onlinedocs/gcc/Environment-Variables.html>
|
