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