1.. highlight:: c
2
3.. _building:
4
5*****************************
6Building C and C++ Extensions
7*****************************
8
9A C extension for CPython is a shared library (e.g. a ``.so`` file on Linux,
10``.pyd`` on Windows), which exports an *initialization function*.
11
12To be importable, the shared library must be available on :envvar:`PYTHONPATH`,
13and must be named after the module name, with an appropriate extension.
14When using distutils, the correct filename is generated automatically.
15
16The initialization function has the signature:
17
18.. c:function:: PyObject* PyInit_modulename(void)
19
20It returns either a fully-initialized module, or a :c:type:`PyModuleDef`
21instance. See :ref:`initializing-modules` for details.
22
23.. highlight:: python
24
25For modules with ASCII-only names, the function must be named
26``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the
27module. When using :ref:`multi-phase-initialization`, non-ASCII module names
28are allowed. In this case, the initialization function name is
29``PyInitU_<modulename>``, with ``<modulename>`` encoded using Python's
30*punycode* encoding with hyphens replaced by underscores. In Python::
31
32    def initfunc_name(name):
33        try:
34            suffix = b'_' + name.encode('ascii')
35        except UnicodeEncodeError:
36            suffix = b'U_' + name.encode('punycode').replace(b'-', b'_')
37        return b'PyInit' + suffix
38
39It is possible to export multiple modules from a single shared library by
40defining multiple initialization functions. However, importing them requires
41using symbolic links or a custom importer, because by default only the
42function corresponding to the filename is found.
43See the *"Multiple modules in one library"* section in :pep:`489` for details.
44
45
46.. highlight:: c
47
48Building C and C++ Extensions with distutils
49============================================
50
51.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
52
53Extension modules can be built using distutils,  which is included in Python.
54Since distutils also supports creation of binary packages, users don't
55necessarily need a compiler and distutils to install the extension.
56
57A distutils package contains a driver script, :file:`setup.py`. This is a plain
58Python file, which, in the most simple case, could look like this:
59
60.. code-block:: python3
61
62   from distutils.core import setup, Extension
63
64   module1 = Extension('demo',
65                       sources = ['demo.c'])
66
67   setup (name = 'PackageName',
68          version = '1.0',
69          description = 'This is a demo package',
70          ext_modules = [module1])
71
72
73With this :file:`setup.py`, and a file :file:`demo.c`, running ::
74
75   python setup.py build
76
77will compile :file:`demo.c`, and produce an extension module named ``demo`` in
78the :file:`build` directory. Depending on the system, the module file will end
79up in a subdirectory :file:`build/lib.system`, and may have a name like
80:file:`demo.so` or :file:`demo.pyd`.
81
82In the :file:`setup.py`, all execution is performed by calling the ``setup``
83function. This takes a variable number of keyword arguments, of which the
84example above uses only a subset. Specifically, the example specifies
85meta-information to build packages, and it specifies the contents of the
86package.  Normally, a package will contain additional modules, like Python
87source modules, documentation, subpackages, etc. Please refer to the distutils
88documentation in :ref:`distutils-index` to learn more about the features of
89distutils; this section explains building extension modules only.
90
91It is common to pre-compute arguments to :func:`setup`, to better structure the
92driver script. In the example above, the ``ext_modules`` argument to
93:func:`~distutils.core.setup` is a list of extension modules, each of which is
94an instance of
95the :class:`~distutils.extension.Extension`. In the example, the instance
96defines an extension named ``demo`` which is build by compiling a single source
97file, :file:`demo.c`.
98
99In many cases, building an extension is more complex, since additional
100preprocessor defines and libraries may be needed. This is demonstrated in the
101example below.
102
103.. code-block:: python3
104
105   from distutils.core import setup, Extension
106
107   module1 = Extension('demo',
108                       define_macros = [('MAJOR_VERSION', '1'),
109                                        ('MINOR_VERSION', '0')],
110                       include_dirs = ['/usr/local/include'],
111                       libraries = ['tcl83'],
112                       library_dirs = ['/usr/local/lib'],
113                       sources = ['demo.c'])
114
115   setup (name = 'PackageName',
116          version = '1.0',
117          description = 'This is a demo package',
118          author = 'Martin v. Loewis',
119          author_email = 'martin@v.loewis.de',
120          url = 'https://docs.python.org/extending/building',
121          long_description = '''
122   This is really just a demo package.
123   ''',
124          ext_modules = [module1])
125
126
127In this example, :func:`~distutils.core.setup` is called with additional
128meta-information, which
129is recommended when distribution packages have to be built. For the extension
130itself, it specifies preprocessor defines, include directories, library
131directories, and libraries. Depending on the compiler, distutils passes this
132information in different ways to the compiler. For example, on Unix, this may
133result in the compilation commands ::
134
135   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
136
137   gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
138
139These lines are for demonstration purposes only; distutils users should trust
140that distutils gets the invocations right.
141
142
143.. _distributing:
144
145Distributing your extension modules
146===================================
147
148When an extension has been successfully built, there are three ways to use it.
149
150End-users will typically want to install the module, they do so by running ::
151
152   python setup.py install
153
154Module maintainers should produce source packages; to do so, they run ::
155
156   python setup.py sdist
157
158In some cases, additional files need to be included in a source distribution;
159this is done through a :file:`MANIFEST.in` file; see :ref:`manifest` for details.
160
161If the source distribution has been built successfully, maintainers can also
162create binary distributions. Depending on the platform, one of the following
163commands can be used to do so. ::
164
165   python setup.py bdist_wininst
166   python setup.py bdist_rpm
167   python setup.py bdist_dumb
168