1.. highlightlang:: c 2 3 4.. _building: 5 6******************************************** 7Building C and C++ Extensions with distutils 8******************************************** 9 10.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de> 11 12 13Starting in Python 1.4, Python provides, on Unix, a special make file for 14building make files for building dynamically-linked extensions and custom 15interpreters. Starting with Python 2.0, this mechanism (known as related to 16Makefile.pre.in, and Setup files) is no longer supported. Building custom 17interpreters was rarely used, and extension modules can be built using 18distutils. 19 20Building an extension module using distutils requires that distutils is 21installed on the build machine, which is included in Python 2.x and available 22separately for Python 1.5. Since distutils also supports creation of binary 23packages, users don't necessarily need a compiler and distutils to install the 24extension. 25 26A distutils package contains a driver script, :file:`setup.py`. This is a plain 27Python file, which, in the most simple case, could look like this: 28 29.. code-block:: python 30 31 from distutils.core import setup, Extension 32 33 module1 = Extension('demo', 34 sources = ['demo.c']) 35 36 setup (name = 'PackageName', 37 version = '1.0', 38 description = 'This is a demo package', 39 ext_modules = [module1]) 40 41 42With this :file:`setup.py`, and a file :file:`demo.c`, running :: 43 44 python setup.py build 45 46will compile :file:`demo.c`, and produce an extension module named ``demo`` in 47the :file:`build` directory. Depending on the system, the module file will end 48up in a subdirectory :file:`build/lib.system`, and may have a name like 49:file:`demo.so` or :file:`demo.pyd`. 50 51In the :file:`setup.py`, all execution is performed by calling the ``setup`` 52function. This takes a variable number of keyword arguments, of which the 53example above uses only a subset. Specifically, the example specifies 54meta-information to build packages, and it specifies the contents of the 55package. Normally, a package will contain of addition modules, like Python 56source modules, documentation, subpackages, etc. Please refer to the distutils 57documentation in :ref:`distutils-index` to learn more about the features of 58distutils; this section explains building extension modules only. 59 60It is common to pre-compute arguments to :func:`setup`, to better structure the 61driver script. In the example above, the ``ext_modules`` argument to 62:func:`setup` is a list of extension modules, each of which is an instance of 63the :class:`~distutils.extension.Extension`. In the example, the instance 64defines an extension named ``demo`` which is build by compiling a single source 65file, :file:`demo.c`. 66 67In many cases, building an extension is more complex, since additional 68preprocessor defines and libraries may be needed. This is demonstrated in the 69example below. 70 71.. code-block:: python 72 73 from distutils.core import setup, Extension 74 75 module1 = Extension('demo', 76 define_macros = [('MAJOR_VERSION', '1'), 77 ('MINOR_VERSION', '0')], 78 include_dirs = ['/usr/local/include'], 79 libraries = ['tcl83'], 80 library_dirs = ['/usr/local/lib'], 81 sources = ['demo.c']) 82 83 setup (name = 'PackageName', 84 version = '1.0', 85 description = 'This is a demo package', 86 author = 'Martin v. Loewis', 87 author_email = 'martin@v.loewis.de', 88 url = 'https://docs.python.org/extending/building', 89 long_description = ''' 90 This is really just a demo package. 91 ''', 92 ext_modules = [module1]) 93 94 95In this example, :func:`setup` is called with additional meta-information, which 96is recommended when distribution packages have to be built. For the extension 97itself, it specifies preprocessor defines, include directories, library 98directories, and libraries. Depending on the compiler, distutils passes this 99information in different ways to the compiler. For example, on Unix, this may 100result in the compilation commands :: 101 102 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 103 104 gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so 105 106These lines are for demonstration purposes only; distutils users should trust 107that distutils gets the invocations right. 108 109 110.. _distributing: 111 112Distributing your extension modules 113=================================== 114 115When an extension has been successfully build, there are three ways to use it. 116 117End-users will typically want to install the module, they do so by running :: 118 119 python setup.py install 120 121Module maintainers should produce source packages; to do so, they run :: 122 123 python setup.py sdist 124 125In some cases, additional files need to be included in a source distribution; 126this is done through a :file:`MANIFEST.in` file; see the distutils documentation 127for details. 128 129If the source distribution has been build successfully, maintainers can also 130create binary distributions. Depending on the platform, one of the following 131commands can be used to do so. :: 132 133 python setup.py bdist_wininst 134 python setup.py bdist_rpm 135 python setup.py bdist_dumb 136