1 .. highlightlang:: c 2 3 .. _building: 4 5 ***************************** 6 Building C and C++ Extensions 7 ***************************** 8 9 A 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 12 To be importable, the shared library must be available on :envvar:`PYTHONPATH`, 13 and must be named after the module name, with an appropriate extension. 14 When using distutils, the correct filename is generated automatically. 15 16 The initialization function has the signature: 17 18 .. c:function:: PyObject* PyInit_modulename(void) 19 20 It returns either a fully-initialized module, or a :c:type:`PyModuleDef` 21 instance. See :ref:`initializing-modules` for details. 22 23 .. highlightlang:: python 24 25 For modules with ASCII-only names, the function must be named 26 ``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the 27 module. When using :ref:`multi-phase-initialization`, non-ASCII module names 28 are 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 39 It is possible to export multiple modules from a single shared library by 40 defining multiple initialization functions. However, importing them requires 41 using symbolic links or a custom importer, because by default only the 42 function corresponding to the filename is found. 43 See the *"Multiple modules in one library"* section in :pep:`489` for details. 44 45 46 .. highlightlang:: c 47 48 Building C and C++ Extensions with distutils 49 ============================================ 50 51 .. sectionauthor:: Martin v. Lwis <martin (a] v.loewis.de> 52 53 Extension modules can be built using distutils, which is included in Python. 54 Since distutils also supports creation of binary packages, users don't 55 necessarily need a compiler and distutils to install the extension. 56 57 A distutils package contains a driver script, :file:`setup.py`. This is a plain 58 Python 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 73 With this :file:`setup.py`, and a file :file:`demo.c`, running :: 74 75 python setup.py build 76 77 will compile :file:`demo.c`, and produce an extension module named ``demo`` in 78 the :file:`build` directory. Depending on the system, the module file will end 79 up in a subdirectory :file:`build/lib.system`, and may have a name like 80 :file:`demo.so` or :file:`demo.pyd`. 81 82 In the :file:`setup.py`, all execution is performed by calling the ``setup`` 83 function. This takes a variable number of keyword arguments, of which the 84 example above uses only a subset. Specifically, the example specifies 85 meta-information to build packages, and it specifies the contents of the 86 package. Normally, a package will contain additional modules, like Python 87 source modules, documentation, subpackages, etc. Please refer to the distutils 88 documentation in :ref:`distutils-index` to learn more about the features of 89 distutils; this section explains building extension modules only. 90 91 It is common to pre-compute arguments to :func:`setup`, to better structure the 92 driver 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 94 an instance of 95 the :class:`~distutils.extension.Extension`. In the example, the instance 96 defines an extension named ``demo`` which is build by compiling a single source 97 file, :file:`demo.c`. 98 99 In many cases, building an extension is more complex, since additional 100 preprocessor defines and libraries may be needed. This is demonstrated in the 101 example 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 (a] 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 127 In this example, :func:`~distutils.core.setup` is called with additional 128 meta-information, which 129 is recommended when distribution packages have to be built. For the extension 130 itself, it specifies preprocessor defines, include directories, library 131 directories, and libraries. Depending on the compiler, distutils passes this 132 information in different ways to the compiler. For example, on Unix, this may 133 result 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 139 These lines are for demonstration purposes only; distutils users should trust 140 that distutils gets the invocations right. 141 142 143 .. _distributing: 144 145 Distributing your extension modules 146 =================================== 147 148 When an extension has been successfully build, there are three ways to use it. 149 150 End-users will typically want to install the module, they do so by running :: 151 152 python setup.py install 153 154 Module maintainers should produce source packages; to do so, they run :: 155 156 python setup.py sdist 157 158 In some cases, additional files need to be included in a source distribution; 159 this is done through a :file:`MANIFEST.in` file; see :ref:`manifest` for details. 160 161 If the source distribution has been build successfully, maintainers can also 162 create binary distributions. Depending on the platform, one of the following 163 commands 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
