Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="dist.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="dist.html" title='Distributing Python Modules' /> | |
8 | <link rel='index' href='genindex.html' title='Index' /> | |
9 | <link rel='last' href='about.html' title='About this document...' /> | |
10 | <link rel='help' href='about.html' title='About this document...' /> | |
11 | <link rel="next" href="node10.html" /> | |
12 | <link rel="prev" href="listing-modules.html" /> | |
13 | <link rel="parent" href="setup-script.html" /> | |
14 | <link rel="next" href="node10.html" /> | |
15 | <meta name='aesop' content='information' /> | |
16 | <title>2.3 Describing extension modules</title> | |
17 | </head> | |
18 | <body> | |
19 | <DIV CLASS="navigation"> | |
20 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
21 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
22 | <tr> | |
23 | <td class='online-navigation'><a rel="prev" title="2.2 Listing individual modules" | |
24 | href="listing-modules.html"><img src='../icons/previous.png' | |
25 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
26 | <td class='online-navigation'><a rel="parent" title="2. Writing the Setup" | |
27 | href="setup-script.html"><img src='../icons/up.png' | |
28 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
29 | <td class='online-navigation'><a rel="next" title="2.4 Installing Scripts" | |
30 | href="node10.html"><img src='../icons/next.png' | |
31 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
32 | <td align="center" width="100%">Distributing Python Modules</td> | |
33 | <td class='online-navigation'><img src='../icons/blank.png' | |
34 | border='0' height='32' alt='' width='32' /></td> | |
35 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
36 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
37 | <td class='online-navigation'><a rel="index" title="Index" | |
38 | href="genindex.html"><img src='../icons/index.png' | |
39 | border='0' height='32' alt='Index' width='32' /></A></td> | |
40 | </tr></table> | |
41 | <div class='online-navigation'> | |
42 | <b class="navlabel">Previous:</b> | |
43 | <a class="sectref" rel="prev" href="listing-modules.html">2.2 Listing individual modules</A> | |
44 | <b class="navlabel">Up:</b> | |
45 | <a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A> | |
46 | <b class="navlabel">Next:</b> | |
47 | <a class="sectref" rel="next" href="node10.html">2.4 Installing Scripts</A> | |
48 | </div> | |
49 | <hr /></div> | |
50 | </DIV> | |
51 | <!--End of Navigation Panel--> | |
52 | <div class='online-navigation'> | |
53 | <!--Table of Child-Links--> | |
54 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> | |
55 | ||
56 | <UL CLASS="ChildLinks"> | |
57 | <LI><A href="describing-extensions.html#SECTION002310000000000000000">2.3.1 Extension names and packages</a> | |
58 | <LI><A href="describing-extensions.html#SECTION002320000000000000000">2.3.2 Extension source files</a> | |
59 | <LI><A href="describing-extensions.html#SECTION002330000000000000000">2.3.3 Preprocessor options</a> | |
60 | <LI><A href="describing-extensions.html#SECTION002340000000000000000">2.3.4 Library options</a> | |
61 | <LI><A href="describing-extensions.html#SECTION002350000000000000000">2.3.5 Other options</a> | |
62 | </ul> | |
63 | <!--End of Table of Child-Links--> | |
64 | </div> | |
65 | <HR> | |
66 | ||
67 | <H1><A NAME="SECTION002300000000000000000"></A> | |
68 | <A NAME="describing-extensions"></A> | |
69 | <BR> | |
70 | 2.3 Describing extension modules | |
71 | </H1> | |
72 | ||
73 | <P> | |
74 | Just as writing Python extension modules is a bit more complicated than | |
75 | writing pure Python modules, describing them to the Distutils is a bit | |
76 | more complicated. Unlike pure modules, it's not enough just to list | |
77 | modules or packages and expect the Distutils to go out and find the | |
78 | right files; you have to specify the extension name, source file(s), and | |
79 | any compile/link requirements (include directories, libraries to link | |
80 | with, etc.). | |
81 | ||
82 | <P> | |
83 | All of this is done through another keyword argument to | |
84 | <tt class="function">setup()</tt>, the <span class="du-option">ext_modules</span> option. <span class="du-option">ext_modules</span> | |
85 | is just a list of <tt class="class">Extension</tt> instances, each of which describes a | |
86 | single extension module. Suppose your distribution includes a single | |
87 | extension, called <tt class="module">foo</tt> and implemented by <span class="file">foo.c</span>. If no | |
88 | additional instructions to the compiler/linker are needed, describing | |
89 | this extension is quite simple: | |
90 | ||
91 | <P> | |
92 | <div class="verbatim"><pre> | |
93 | Extension('foo', ['foo.c']) | |
94 | </pre></div> | |
95 | ||
96 | <P> | |
97 | The <tt class="class">Extension</tt> class can be imported from | |
98 | <tt class="module">distutils.core</tt> along with <tt class="function">setup()</tt>. Thus, the setup | |
99 | script for a module distribution that contains only this one extension | |
100 | and nothing else might be: | |
101 | ||
102 | <P> | |
103 | <div class="verbatim"><pre> | |
104 | from distutils.core import setup, Extension | |
105 | setup(name='foo', | |
106 | version='1.0', | |
107 | ext_modules=[Extension('foo', ['foo.c'])], | |
108 | ) | |
109 | </pre></div> | |
110 | ||
111 | <P> | |
112 | The <tt class="class">Extension</tt> class (actually, the underlying extension-building | |
113 | machinery implemented by the <code class="du-command">build_ext</code> command) supports a | |
114 | great deal of flexibility in describing Python extensions, which is | |
115 | explained in the following sections. | |
116 | ||
117 | <P> | |
118 | ||
119 | <H2><A NAME="SECTION002310000000000000000"> | |
120 | 2.3.1 Extension names and packages</A> | |
121 | </H2> | |
122 | ||
123 | <P> | |
124 | The first argument to the <tt class="class">Extension</tt> constructor is always the | |
125 | name of the extension, including any package names. For example, | |
126 | ||
127 | <P> | |
128 | <div class="verbatim"><pre> | |
129 | Extension('foo', ['src/foo1.c', 'src/foo2.c']) | |
130 | </pre></div> | |
131 | ||
132 | <P> | |
133 | describes an extension that lives in the root package, while | |
134 | ||
135 | <P> | |
136 | <div class="verbatim"><pre> | |
137 | Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) | |
138 | </pre></div> | |
139 | ||
140 | <P> | |
141 | describes the same extension in the <tt class="module">pkg</tt> package. The source | |
142 | files and resulting object code are identical in both cases; the only | |
143 | difference is where in the filesystem (and therefore where in Python's | |
144 | namespace hierarchy) the resulting extension lives. | |
145 | ||
146 | <P> | |
147 | If you have a number of extensions all in the same package (or all under | |
148 | the same base package), use the <span class="du-option">ext_package</span> keyword argument | |
149 | to <tt class="function">setup()</tt>. For example, | |
150 | ||
151 | <P> | |
152 | <div class="verbatim"><pre> | |
153 | setup(... | |
154 | ext_package='pkg', | |
155 | ext_modules=[Extension('foo', ['foo.c']), | |
156 | Extension('subpkg.bar', ['bar.c'])], | |
157 | ) | |
158 | </pre></div> | |
159 | ||
160 | <P> | |
161 | will compile <span class="file">foo.c</span> to the extension <tt class="module">pkg.foo</tt>, and | |
162 | <span class="file">bar.c</span> to <tt class="module">pkg.subpkg.bar</tt>. | |
163 | ||
164 | <P> | |
165 | ||
166 | <H2><A NAME="SECTION002320000000000000000"> | |
167 | 2.3.2 Extension source files</A> | |
168 | </H2> | |
169 | ||
170 | <P> | |
171 | The second argument to the <tt class="class">Extension</tt> constructor is a list of | |
172 | source files. Since the Distutils currently only support C, C++, and | |
173 | Objective-C extensions, these are normally C/C++/Objective-C source | |
174 | files. (Be sure to use appropriate extensions to distinguish C++ source files: <span class="file">.cc</span> and <span class="file">.cpp</span> seem to be recognized by both | |
175 | <span class="Unix">Unix</span> and Windows compilers.) | |
176 | ||
177 | <P> | |
178 | However, you can also include SWIG interface (<span class="file">.i</span>) files in the | |
179 | list; the <code class="du-command">build_ext</code> command knows how to deal with SWIG | |
180 | extensions: it will run SWIG on the interface file and compile the | |
181 | resulting C/C++ file into your extension. | |
182 | ||
183 | <P> | |
184 | <b class="du-xxx">SWIG support is rough around the edges and largely untested; | |
185 | especially SWIG support for C++ extensions! Explain in more detail | |
186 | here when the interface firms up.</b> | |
187 | ||
188 | <P> | |
189 | On some platforms, you can include non-source files that are processed | |
190 | by the compiler and included in your extension. Currently, this just | |
191 | means Windows message text (<span class="file">.mc</span>) files and resource definition | |
192 | (<span class="file">.rc</span>) files for Visual C++. These will be compiled to binary resource | |
193 | (<span class="file">.res</span>) files and linked into the executable. | |
194 | ||
195 | <P> | |
196 | ||
197 | <H2><A NAME="SECTION002330000000000000000"> | |
198 | 2.3.3 Preprocessor options</A> | |
199 | </H2> | |
200 | ||
201 | <P> | |
202 | Three optional arguments to <tt class="class">Extension</tt> will help if you need to | |
203 | specify include directories to search or preprocessor macros to | |
204 | define/undefine: <code>include_dirs</code>, <code>define_macros</code>, and | |
205 | <code>undef_macros</code>. | |
206 | ||
207 | <P> | |
208 | For example, if your extension requires header files in the | |
209 | <span class="file">include</span> directory under your distribution root, use the | |
210 | <code>include_dirs</code> option: | |
211 | ||
212 | <P> | |
213 | <div class="verbatim"><pre> | |
214 | Extension('foo', ['foo.c'], include_dirs=['include']) | |
215 | </pre></div> | |
216 | ||
217 | <P> | |
218 | You can specify absolute directories there; if you know that your | |
219 | extension will only be built on <span class="Unix">Unix</span> systems with X11R6 installed to | |
220 | <span class="file">/usr</span>, you can get away with | |
221 | ||
222 | <P> | |
223 | <div class="verbatim"><pre> | |
224 | Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) | |
225 | </pre></div> | |
226 | ||
227 | <P> | |
228 | You should avoid this sort of non-portable usage if you plan to | |
229 | distribute your code: it's probably better to write C code like | |
230 | <div class="verbatim"><pre> | |
231 | #include <X11/Xlib.h> | |
232 | </pre></div> | |
233 | ||
234 | <P> | |
235 | If you need to include header files from some other Python extension, | |
236 | you can take advantage of the fact that header files are installed in a | |
237 | consistent way by the Distutils <code class="du-command">install_header</code> command. For | |
238 | example, the Numerical Python header files are installed (on a standard | |
239 | Unix installation) to <span class="file">/usr/local/include/python1.5/Numerical</span>. | |
240 | (The exact location will differ according to your platform and Python | |
241 | installation.) Since the Python include | |
242 | directory--<span class="file">/usr/local/include/python1.5</span> in this case--is always | |
243 | included in the search path when building Python extensions, the best | |
244 | approach is to write C code like | |
245 | <div class="verbatim"><pre> | |
246 | #include <Numerical/arrayobject.h> | |
247 | </pre></div> | |
248 | If you must put the <span class="file">Numerical</span> include directory right into your | |
249 | header search path, though, you can find that directory using the | |
250 | Distutils <tt class="module"><a href="module-distutils.sysconfig.html">distutils.sysconfig</a></tt> module: | |
251 | ||
252 | <P> | |
253 | <div class="verbatim"><pre> | |
254 | from distutils.sysconfig import get_python_inc | |
255 | incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') | |
256 | setup(..., | |
257 | Extension(..., include_dirs=[incdir]), | |
258 | ) | |
259 | </pre></div> | |
260 | ||
261 | <P> | |
262 | Even though this is quite portable--it will work on any Python | |
263 | installation, regardless of platform--it's probably easier to just | |
264 | write your C code in the sensible way. | |
265 | ||
266 | <P> | |
267 | You can define and undefine pre-processor macros with the | |
268 | <code>define_macros</code> and <code>undef_macros</code> options. | |
269 | <code>define_macros</code> takes a list of <code>(name, value)</code> tuples, where | |
270 | <code>name</code> is the name of the macro to define (a string) and | |
271 | <code>value</code> is its value: either a string or <code>None</code>. (Defining a | |
272 | macro <code>FOO</code> to <code>None</code> is the equivalent of a bare | |
273 | <code>#define FOO</code> in your C source: with most compilers, this sets | |
274 | <code>FOO</code> to the string <code>1</code>.) <code>undef_macros</code> is just | |
275 | a list of macros to undefine. | |
276 | ||
277 | <P> | |
278 | For example: | |
279 | ||
280 | <P> | |
281 | <div class="verbatim"><pre> | |
282 | Extension(..., | |
283 | define_macros=[('NDEBUG', '1'), | |
284 | ('HAVE_STRFTIME', None)], | |
285 | undef_macros=['HAVE_FOO', 'HAVE_BAR']) | |
286 | </pre></div> | |
287 | ||
288 | <P> | |
289 | is the equivalent of having this at the top of every C source file: | |
290 | ||
291 | <P> | |
292 | <div class="verbatim"><pre> | |
293 | #define NDEBUG 1 | |
294 | #define HAVE_STRFTIME | |
295 | #undef HAVE_FOO | |
296 | #undef HAVE_BAR | |
297 | </pre></div> | |
298 | ||
299 | <P> | |
300 | ||
301 | <H2><A NAME="SECTION002340000000000000000"> | |
302 | 2.3.4 Library options</A> | |
303 | </H2> | |
304 | ||
305 | <P> | |
306 | You can also specify the libraries to link against when building your | |
307 | extension, and the directories to search for those libraries. The | |
308 | <code>libraries</code> option is a list of libraries to link against, | |
309 | <code>library_dirs</code> is a list of directories to search for libraries at | |
310 | link-time, and <code>runtime_library_dirs</code> is a list of directories to | |
311 | search for shared (dynamically loaded) libraries at run-time. | |
312 | ||
313 | <P> | |
314 | For example, if you need to link against libraries known to be in the | |
315 | standard library search path on target systems | |
316 | ||
317 | <P> | |
318 | <div class="verbatim"><pre> | |
319 | Extension(..., | |
320 | libraries=['gdbm', 'readline']) | |
321 | </pre></div> | |
322 | ||
323 | <P> | |
324 | If you need to link with libraries in a non-standard location, you'll | |
325 | have to include the location in <code>library_dirs</code>: | |
326 | ||
327 | <P> | |
328 | <div class="verbatim"><pre> | |
329 | Extension(..., | |
330 | library_dirs=['/usr/X11R6/lib'], | |
331 | libraries=['X11', 'Xt']) | |
332 | </pre></div> | |
333 | ||
334 | <P> | |
335 | (Again, this sort of non-portable construct should be avoided if you | |
336 | intend to distribute your code.) | |
337 | ||
338 | <P> | |
339 | <b class="du-xxx">Should mention clib libraries here or somewhere else!</b> | |
340 | ||
341 | <P> | |
342 | ||
343 | <H2><A NAME="SECTION002350000000000000000"> | |
344 | 2.3.5 Other options</A> | |
345 | </H2> | |
346 | ||
347 | <P> | |
348 | There are still some other options which can be used to handle special | |
349 | cases. | |
350 | ||
351 | <P> | |
352 | The <span class="du-option">extra_objects</span> option is a list of object files to be passed | |
353 | to the linker. These files must not have extensions, as the default | |
354 | extension for the compiler is used. | |
355 | ||
356 | <P> | |
357 | <span class="du-option">extra_compile_args</span> and <span class="du-option">extra_link_args</span> can be used | |
358 | to specify additional command line options for the respective compiler and | |
359 | linker command lines. | |
360 | ||
361 | <P> | |
362 | <span class="du-option">export_symbols</span> is only useful on Windows. It can contain a list | |
363 | of symbols (functions or variables) to be exported. This option | |
364 | is not needed when building compiled extensions: Distutils | |
365 | will automatically add <code>initmodule</code> | |
366 | to the list of exported symbols. | |
367 | ||
368 | <P> | |
369 | ||
370 | <DIV CLASS="navigation"> | |
371 | <div class='online-navigation'> | |
372 | <p></p><hr /> | |
373 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
374 | <tr> | |
375 | <td class='online-navigation'><a rel="prev" title="2.2 Listing individual modules" | |
376 | href="listing-modules.html"><img src='../icons/previous.png' | |
377 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
378 | <td class='online-navigation'><a rel="parent" title="2. Writing the Setup" | |
379 | href="setup-script.html"><img src='../icons/up.png' | |
380 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
381 | <td class='online-navigation'><a rel="next" title="2.4 Installing Scripts" | |
382 | href="node10.html"><img src='../icons/next.png' | |
383 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
384 | <td align="center" width="100%">Distributing Python Modules</td> | |
385 | <td class='online-navigation'><img src='../icons/blank.png' | |
386 | border='0' height='32' alt='' width='32' /></td> | |
387 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
388 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
389 | <td class='online-navigation'><a rel="index" title="Index" | |
390 | href="genindex.html"><img src='../icons/index.png' | |
391 | border='0' height='32' alt='Index' width='32' /></A></td> | |
392 | </tr></table> | |
393 | <div class='online-navigation'> | |
394 | <b class="navlabel">Previous:</b> | |
395 | <a class="sectref" rel="prev" href="listing-modules.html">2.2 Listing individual modules</A> | |
396 | <b class="navlabel">Up:</b> | |
397 | <a class="sectref" rel="parent" href="setup-script.html">2. Writing the Setup</A> | |
398 | <b class="navlabel">Next:</b> | |
399 | <a class="sectref" rel="next" href="node10.html">2.4 Installing Scripts</A> | |
400 | </div> | |
401 | </div> | |
402 | <hr /> | |
403 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
404 | </DIV> | |
405 | <!--End of Navigation Panel--> | |
406 | <ADDRESS> | |
407 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
408 | </ADDRESS> | |
409 | </BODY> | |
410 | </HTML> |