1 .. highlightlang:: c 2 3 4 .. _building: 5 6 ******************************************** 7 Building C and C++ Extensions with distutils 8 ******************************************** 9 10 .. sectionauthor:: Martin v. Lwis <martin (a] v.loewis.de> 11 12 13 Starting in Python 1.4, Python provides, on Unix, a special make file for 14 building make files for building dynamically-linked extensions and custom 15 interpreters. Starting with Python 2.0, this mechanism (known as related to 16 Makefile.pre.in, and Setup files) is no longer supported. Building custom 17 interpreters was rarely used, and extension modules can be built using 18 distutils. 19 20 Building an extension module using distutils requires that distutils is 21 installed on the build machine, which is included in Python 2.x and available 22 separately for Python 1.5. Since distutils also supports creation of binary 23 packages, users don't necessarily need a compiler and distutils to install the 24 extension. 25 26 A distutils package contains a driver script, :file:`setup.py`. This is a plain 27 Python 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 42 With this :file:`setup.py`, and a file :file:`demo.c`, running :: 43 44 python setup.py build 45 46 will compile :file:`demo.c`, and produce an extension module named ``demo`` in 47 the :file:`build` directory. Depending on the system, the module file will end 48 up in a subdirectory :file:`build/lib.system`, and may have a name like 49 :file:`demo.so` or :file:`demo.pyd`. 50 51 In the :file:`setup.py`, all execution is performed by calling the ``setup`` 52 function. This takes a variable number of keyword arguments, of which the 53 example above uses only a subset. Specifically, the example specifies 54 meta-information to build packages, and it specifies the contents of the 55 package. Normally, a package will contain of addition modules, like Python 56 source modules, documentation, subpackages, etc. Please refer to the distutils 57 documentation in :ref:`distutils-index` to learn more about the features of 58 distutils; this section explains building extension modules only. 59 60 It is common to pre-compute arguments to :func:`setup`, to better structure the 61 driver 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 63 the :class:`~distutils.extension.Extension`. In the example, the instance 64 defines an extension named ``demo`` which is build by compiling a single source 65 file, :file:`demo.c`. 66 67 In many cases, building an extension is more complex, since additional 68 preprocessor defines and libraries may be needed. This is demonstrated in the 69 example 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 (a] 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 95 In this example, :func:`setup` is called with additional meta-information, which 96 is recommended when distribution packages have to be built. For the extension 97 itself, it specifies preprocessor defines, include directories, library 98 directories, and libraries. Depending on the compiler, distutils passes this 99 information in different ways to the compiler. For example, on Unix, this may 100 result 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 106 These lines are for demonstration purposes only; distutils users should trust 107 that distutils gets the invocations right. 108 109 110 .. _distributing: 111 112 Distributing your extension modules 113 =================================== 114 115 When an extension has been successfully build, there are three ways to use it. 116 117 End-users will typically want to install the module, they do so by running :: 118 119 python setup.py install 120 121 Module maintainers should produce source packages; to do so, they run :: 122 123 python setup.py sdist 124 125 In some cases, additional files need to be included in a source distribution; 126 this is done through a :file:`MANIFEST.in` file; see the distutils documentation 127 for details. 128 129 If the source distribution has been build successfully, maintainers can also 130 create binary distributions. Depending on the platform, one of the following 131 commands 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
