Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | .. _building: |
| 4 | |
Nick Coghlan | 2ab5b09 | 2015-07-03 19:49:15 +1000 | [diff] [blame] | 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. |
Berker Peksag | 705c0e3 | 2016-04-09 09:08:05 +0300 | [diff] [blame] | 43 | See the *"Multiple modules in one library"* section in :pep:`489` for details. |
Nick Coghlan | 2ab5b09 | 2015-07-03 19:49:15 +1000 | [diff] [blame] | 44 | |
| 45 | |
| 46 | .. highlightlang:: c |
| 47 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | Building C and C++ Extensions with distutils |
Nick Coghlan | 2ab5b09 | 2015-07-03 19:49:15 +1000 | [diff] [blame] | 49 | ============================================ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 50 | |
| 51 | .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de> |
| 52 | |
Nick Coghlan | 2ab5b09 | 2015-07-03 19:49:15 +1000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
| 57 | A distutils package contains a driver script, :file:`setup.py`. This is a plain |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 58 | Python file, which, in the most simple case, could look like this: |
| 59 | |
| 60 | .. code-block:: python3 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 75 | python setup.py build |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Terry Jan Reedy | 6401e79 | 2016-01-09 12:22:00 -0500 | [diff] [blame] | 86 | package. Normally, a package will contain additional modules, like Python |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Zachary Ware | c75e2dd | 2015-07-21 22:33:16 -0500 | [diff] [blame] | 92 | driver script. In the example above, the ``ext_modules`` argument to |
Berker Peksag | 705c0e3 | 2016-04-09 09:08:05 +0300 | [diff] [blame] | 93 | :func:`~distutils.core.setup` is a list of extension modules, each of which is |
| 94 | an instance of |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 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`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 101 | example below. |
| 102 | |
| 103 | .. code-block:: python3 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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', |
Georg Brandl | e73778c | 2014-10-29 08:36:35 +0100 | [diff] [blame] | 120 | url = 'https://docs.python.org/extending/building', |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | long_description = ''' |
| 122 | This is really just a demo package. |
| 123 | ''', |
| 124 | ext_modules = [module1]) |
| 125 | |
| 126 | |
Berker Peksag | 705c0e3 | 2016-04-09 09:08:05 +0300 | [diff] [blame] | 127 | In this example, :func:`~distutils.core.setup` is called with additional |
| 128 | meta-information, which |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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; |
Berker Peksag | 705c0e3 | 2016-04-09 09:08:05 +0300 | [diff] [blame] | 159 | this is done through a :file:`MANIFEST.in` file; see :ref:`manifest` for details. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |