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