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="inst.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="inst.html" title='Installing Python Modules' /> | |
8 | <link rel='last' href='about.html' title='About this document...' /> | |
9 | <link rel='help' href='about.html' title='About this document...' /> | |
10 | <link rel="next" href="about.html" /> | |
11 | <link rel="prev" href="config-syntax.html" /> | |
12 | <link rel="parent" href="inst.html" /> | |
13 | <link rel="next" href="about.html" /> | |
14 | <meta name='aesop' content='information' /> | |
15 | <title>6 Building Extensions: Tips and Tricks</title> | |
16 | </head> | |
17 | <body> | |
18 | <DIV CLASS="navigation"> | |
19 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
20 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
21 | <tr> | |
22 | <td class='online-navigation'><a rel="prev" title="5 Distutils Configuration Files" | |
23 | href="config-syntax.html"><img src='../icons/previous.png' | |
24 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
25 | <td class='online-navigation'><a rel="parent" title="Installing Python Modules" | |
26 | href="inst.html"><img src='../icons/up.png' | |
27 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
28 | <td class='online-navigation'><a rel="next" title="About this document ..." | |
29 | href="about.html"><img src='../icons/next.png' | |
30 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
31 | <td align="center" width="100%">Installing Python Modules</td> | |
32 | <td class='online-navigation'><img src='../icons/blank.png' | |
33 | border='0' height='32' alt='' width='32' /></td> | |
34 | <td class='online-navigation'><img src='../icons/blank.png' | |
35 | border='0' height='32' alt='' width='32' /></td> | |
36 | <td class='online-navigation'><img src='../icons/blank.png' | |
37 | border='0' height='32' alt='' width='32' /></td> | |
38 | </tr></table> | |
39 | <div class='online-navigation'> | |
40 | <b class="navlabel">Previous:</b> | |
41 | <a class="sectref" rel="prev" href="config-syntax.html">5 Distutils Configuration Files</A> | |
42 | <b class="navlabel">Up:</b> | |
43 | <a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A> | |
44 | <b class="navlabel">Next:</b> | |
45 | <a class="sectref" rel="next" href="about.html">About this document ...</A> | |
46 | </div> | |
47 | <hr /></div> | |
48 | </DIV> | |
49 | <!--End of Navigation Panel--> | |
50 | <div class='online-navigation'> | |
51 | <!--Table of Child-Links--> | |
52 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> | |
53 | ||
54 | <UL CLASS="ChildLinks"> | |
55 | <LI><A href="tweak-flags.html#SECTION000610000000000000000">6.1 Tweaking compiler/linker flags</a> | |
56 | <LI><A href="tweak-flags.html#SECTION000620000000000000000">6.2 Using non-Microsoft compilers on Windows</a> | |
57 | <UL> | |
58 | <LI><A href="tweak-flags.html#SECTION000621000000000000000">6.2.1 Borland C++</a> | |
59 | <LI><A href="tweak-flags.html#SECTION000622000000000000000">6.2.2 GNU C / Cygwin / MinGW</a> | |
60 | </ul></ul> | |
61 | <!--End of Table of Child-Links--> | |
62 | </div> | |
63 | <HR> | |
64 | ||
65 | <H1><A NAME="SECTION000600000000000000000"></A> | |
66 | <A NAME="building-ext"></A> | |
67 | <BR> | |
68 | 6 Building Extensions: Tips and Tricks | |
69 | </H1> | |
70 | ||
71 | <P> | |
72 | Whenever possible, the Distutils try to use the configuration | |
73 | information made available by the Python interpreter used to run the | |
74 | <span class="file">setup.py</span> script. For example, the same compiler and linker | |
75 | flags used to compile Python will also be used for compiling | |
76 | extensions. Usually this will work well, but in complicated | |
77 | situations this might be inappropriate. This section discusses how to | |
78 | override the usual Distutils behaviour. | |
79 | ||
80 | <P> | |
81 | ||
82 | <H2><A NAME="SECTION000610000000000000000"></A> | |
83 | <A NAME="tweak-flags"></A> | |
84 | <BR> | |
85 | 6.1 Tweaking compiler/linker flags | |
86 | </H2> | |
87 | ||
88 | <P> | |
89 | Compiling a Python extension written in C or C++ will sometimes | |
90 | require specifying custom flags for the compiler and linker in order | |
91 | to use a particular library or produce a special kind of object code. | |
92 | This is especially true if the extension hasn't been tested on your | |
93 | platform, or if you're trying to cross-compile Python. | |
94 | ||
95 | <P> | |
96 | In the most general case, the extension author might have foreseen | |
97 | that compiling the extensions would be complicated, and provided a | |
98 | <span class="file">Setup</span> file for you to edit. This will likely only be done if | |
99 | the module distribution contains many separate extension modules, or | |
100 | if they often require elaborate sets of compiler flags in order to work. | |
101 | ||
102 | <P> | |
103 | A <span class="file">Setup</span> file, if present, is parsed in order to get a list of | |
104 | extensions to build. Each line in a <span class="file">Setup</span> describes a single | |
105 | module. Lines have the following structure: | |
106 | ||
107 | <P> | |
108 | <div class="verbatim"><pre><TT> | |
109 | <var>module</var> ... [<var>sourcefile</var> ...] [<var>cpparg</var> ...] [<var>library</var> ...] | |
110 | </TT></pre></div> | |
111 | ||
112 | <P> | |
113 | Let's examine each of the fields in turn. | |
114 | ||
115 | <P> | |
116 | ||
117 | <UL> | |
118 | <LI><var>module</var> is the name of the extension module to be built, | |
119 | and should be a valid Python identifier. You can't just change | |
120 | this in order to rename a module (edits to the source code would | |
121 | also be needed), so this should be left alone. | |
122 | ||
123 | <P> | |
124 | </LI> | |
125 | <LI><var>sourcefile</var> is anything that's likely to be a source code | |
126 | file, at least judging by the filename. Filenames ending in | |
127 | <span class="file">.c</span> are assumed to be written in C, filenames ending in | |
128 | <span class="file">.C</span>, <span class="file">.cc</span>, and <span class="file">.c++</span> are assumed to be | |
129 | C++, and filenames ending in <span class="file">.m</span> or <span class="file">.mm</span> are | |
130 | assumed to be in Objective C. | |
131 | ||
132 | <P> | |
133 | </LI> | |
134 | <LI><var>cpparg</var> is an argument for the C preprocessor, | |
135 | and is anything starting with <b class="programopt">-I</b>, <b class="programopt">-D</b>, | |
136 | <b class="programopt">-U</b> or <b class="programopt">-C</b>. | |
137 | ||
138 | <P> | |
139 | </LI> | |
140 | <LI><var>library</var> is anything ending in <span class="file">.a</span> or beginning with | |
141 | <b class="programopt">-l</b> or <b class="programopt">-L</b>. | |
142 | </LI> | |
143 | </UL> | |
144 | ||
145 | <P> | |
146 | If a particular platform requires a special library on your platform, | |
147 | you can add it by editing the <span class="file">Setup</span> file and running | |
148 | <code>python setup.py build</code>. For example, if the module defined by the line | |
149 | ||
150 | <P> | |
151 | <div class="verbatim"><pre> | |
152 | foo foomodule.c | |
153 | </pre></div> | |
154 | ||
155 | <P> | |
156 | must be linked with the math library <span class="file">libm.a</span> on your platform, | |
157 | simply add <b class="programopt">-lm</b> to the line: | |
158 | ||
159 | <P> | |
160 | <div class="verbatim"><pre> | |
161 | foo foomodule.c -lm | |
162 | </pre></div> | |
163 | ||
164 | <P> | |
165 | Arbitrary switches intended for the compiler or the linker can be | |
166 | supplied with the <b class="programopt">-Xcompiler</b> <var>arg</var> and | |
167 | <b class="programopt">-Xlinker</b> <var>arg</var> options: | |
168 | ||
169 | <P> | |
170 | <div class="verbatim"><pre> | |
171 | foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm | |
172 | </pre></div> | |
173 | ||
174 | <P> | |
175 | The next option after <b class="programopt">-Xcompiler</b> and | |
176 | <b class="programopt">-Xlinker</b> will be appended to the proper command line, so | |
177 | in the above example the compiler will be passed the <b class="programopt">-o32</b> | |
178 | option, and the linker will be passed <b class="programopt">-shared</b>. If a | |
179 | compiler option requires an argument, you'll have to supply multiple | |
180 | <b class="programopt">-Xcompiler</b> options; for example, to pass <code>-x c++</code> the | |
181 | <span class="file">Setup</span> file would have to contain | |
182 | <code>-Xcompiler -x -Xcompiler c++</code>. | |
183 | ||
184 | <P> | |
185 | Compiler flags can also be supplied through setting the | |
186 | <a class="envvar" id='l2h-7' xml:id='l2h-7'>CFLAGS</a> environment variable. If set, the contents of | |
187 | <a class="envvar" id='l2h-8' xml:id='l2h-8'>CFLAGS</a> will be added to the compiler flags specified in the | |
188 | <span class="file">Setup</span> file. | |
189 | ||
190 | <P> | |
191 | ||
192 | <H2><A NAME="SECTION000620000000000000000"></A><A NAME="non-ms-compilers"></A> | |
193 | <BR> | |
194 | 6.2 Using non-Microsoft compilers on Windows | |
195 | </H2> | |
196 | ||
197 | <P> | |
198 | ||
199 | <H3><A NAME="SECTION000621000000000000000"> | |
200 | 6.2.1 Borland C++</A> | |
201 | </H3> | |
202 | ||
203 | <P> | |
204 | This subsection describes the necessary steps to use Distutils with the | |
205 | Borland C++ compiler version 5.5. | |
206 | ||
207 | <P> | |
208 | First you have to know that Borland's object file format (OMF) is | |
209 | different from the format used by the Python version you can download | |
210 | from the Python or ActiveState Web site. (Python is built with | |
211 | Microsoft Visual C++, which uses COFF as the object file format.) | |
212 | For this reason you have to convert Python's library | |
213 | <span class="file">python24.lib</span> into the Borland format. You can do this as | |
214 | follows: | |
215 | ||
216 | <P> | |
217 | <div class="verbatim"><pre> | |
218 | coff2omf python24.lib python24_bcpp.lib | |
219 | </pre></div> | |
220 | ||
221 | <P> | |
222 | The <span class="file">coff2omf</span> program comes with the Borland compiler. The file | |
223 | <span class="file">python24.lib</span> is in the <span class="file">Libs</span> directory of your Python | |
224 | installation. If your extension uses other libraries (zlib,...) you | |
225 | have to convert them too. | |
226 | ||
227 | <P> | |
228 | The converted files have to reside in the same directories as the | |
229 | normal libraries. | |
230 | ||
231 | <P> | |
232 | How does Distutils manage to use these libraries with their changed | |
233 | names? If the extension needs a library (eg. <span class="file">foo</span>) Distutils | |
234 | checks first if it finds a library with suffix <span class="file">_bcpp</span> | |
235 | (eg. <span class="file">foo_bcpp.lib</span>) and then uses this library. In the case it | |
236 | doesn't find such a special library it uses the default name | |
237 | (<span class="file">foo.lib</span>.)<A NAME="tex2html1" | |
238 | HREF="#foot489"><SUP>1</SUP></A> | |
239 | <P> | |
240 | To let Distutils compile your extension with Borland C++ you now have | |
241 | to type: | |
242 | ||
243 | <P> | |
244 | <div class="verbatim"><pre> | |
245 | python setup.py build --compiler=bcpp | |
246 | </pre></div> | |
247 | ||
248 | <P> | |
249 | If you want to use the Borland C++ compiler as the default, you | |
250 | could specify this in your personal or system-wide configuration file | |
251 | for Distutils (see section <A href="config-syntax.html#config-files">5</A>.) | |
252 | ||
253 | <P> | |
254 | <div class="seealso"> | |
255 | <p class="heading">See Also:</p> | |
256 | ||
257 | <dl compact="compact" class="seetitle"> | |
258 | <dt><em class="citetitle"><a href="http://www.borland.com/bcppbuilder/freecompiler/" | |
259 | >C++Builder Compiler</a></em></dt> | |
260 | <dd>Information about the free C++ compiler from Borland, | |
261 | including links to the download pages.</dd> | |
262 | </dl> | |
263 | ||
264 | <P> | |
265 | <dl compact="compact" class="seetitle"> | |
266 | <dt><em class="citetitle"><a href="http://www.cyberus.ca/~g_will/pyExtenDL.shtml" | |
267 | >Creating Python Extensions Using Borland's Free Compiler</a></em></dt> | |
268 | <dd>Document describing how to use Borland's free command-line C++ | |
269 | compiler to build Python.</dd> | |
270 | </dl> | |
271 | </div> | |
272 | ||
273 | <P> | |
274 | ||
275 | <H3><A NAME="SECTION000622000000000000000"> | |
276 | 6.2.2 GNU C / Cygwin / MinGW</A> | |
277 | </H3> | |
278 | ||
279 | <P> | |
280 | This section describes the necessary steps to use Distutils with the | |
281 | GNU C/C++ compilers in their Cygwin and MinGW | |
282 | distributions.<A NAME="tex2html2" | |
283 | HREF="#foot575"><SUP>2</SUP></A>For a Python interpreter that was built with Cygwin, everything should | |
284 | work without any of these following steps. | |
285 | ||
286 | <P> | |
287 | These compilers require some special libraries. | |
288 | This task is more complex than for Borland's C++, because there is no | |
289 | program to convert the library. | |
290 | ||
291 | <P> | |
292 | First you have to create a list of symbols which the Python DLL exports. | |
293 | (You can find a good program for this task at | |
294 | <a class="url" href="http://starship.python.net/crew/kernr/mingw32/Notes.html">http://starship.python.net/crew/kernr/mingw32/Notes.html</a>, see at | |
295 | PExports 0.42h there.) | |
296 | ||
297 | <P> | |
298 | <div class="verbatim"><pre> | |
299 | pexports python24.dll >python24.def | |
300 | </pre></div> | |
301 | ||
302 | <P> | |
303 | Then you can create from these information an import library for gcc. | |
304 | ||
305 | <P> | |
306 | <div class="verbatim"><pre> | |
307 | dlltool --dllname python24.dll --def python24.def --output-lib libpython24.a | |
308 | </pre></div> | |
309 | ||
310 | <P> | |
311 | The resulting library has to be placed in the same directory as | |
312 | <span class="file">python24.lib</span>. (Should be the <span class="file">libs</span> directory under your | |
313 | Python installation directory.) | |
314 | ||
315 | <P> | |
316 | If your extension uses other libraries (zlib,...) you might | |
317 | have to convert them too. | |
318 | The converted files have to reside in the same directories as the normal | |
319 | libraries do. | |
320 | ||
321 | <P> | |
322 | To let Distutils compile your extension with Cygwin you now have to type | |
323 | ||
324 | <P> | |
325 | <div class="verbatim"><pre> | |
326 | python setup.py build --compiler=cygwin | |
327 | </pre></div> | |
328 | ||
329 | <P> | |
330 | and for Cygwin in no-cygwin mode<A NAME="tex2html3" | |
331 | HREF="#foot576"><SUP>3</SUP></A> or for MinGW type: | |
332 | ||
333 | <P> | |
334 | <div class="verbatim"><pre> | |
335 | python setup.py build --compiler=mingw32 | |
336 | </pre></div> | |
337 | ||
338 | <P> | |
339 | If you want to use any of these options/compilers as default, you should | |
340 | consider to write it in your personal or system-wide configuration file | |
341 | for Distutils (see section <A href="config-syntax.html#config-files">5</A>.) | |
342 | ||
343 | <P> | |
344 | <div class="seealso"> | |
345 | <p class="heading">See Also:</p> | |
346 | ||
347 | <dl compact="compact" class="seetitle"> | |
348 | <dt><em class="citetitle"><a href="http://www.zope.org/Members/als/tips/win32_mingw_modules" | |
349 | >Building Python modules on MS Windows platform with MinGW</a></em></dt> | |
350 | <dd>Information about building the required libraries for the MinGW | |
351 | environment.</dd> | |
352 | </dl> | |
353 | ||
354 | <P> | |
355 | <dl compact="compact" class="seeurl"> | |
356 | <dt><a href="http://pyopengl.sourceforge.net/ftp/win32-stuff/" | |
357 | class="url">http://pyopengl.sourceforge.net/ftp/win32-stuff/</a></dt> | |
358 | <dd>Converted import libraries in Cygwin/MinGW and Borland format, | |
359 | and a script to create the registry entries needed for Distutils | |
360 | to locate the built Python.</dd> | |
361 | </dl> | |
362 | </div> | |
363 | ||
364 | <P> | |
365 | <BR><HR><H4>Footnotes</H4> | |
366 | <DL> | |
367 | <DT><A NAME="foot489">...foo.lib.)</A><A | |
368 | href="tweak-flags.html#tex2html1"><SUP>1</SUP></A></DT> | |
369 | <DD>This also means you could replace all | |
370 | existing COFF-libraries with OMF-libraries of the same name. | |
371 | ||
372 | </DD> | |
373 | <DT><A NAME="foot575">... | |
374 | distributions.</A><A | |
375 | href="tweak-flags.html#tex2html2"><SUP>2</SUP></A></DT> | |
376 | <DD>Check | |
377 | <a class="url" href="http://sources.redhat.com/cygwin/">http://sources.redhat.com/cygwin/</a> and | |
378 | <a class="url" href="http://www.mingw.org/">http://www.mingw.org/</a> for more information | |
379 | ||
380 | </DD> | |
381 | <DT><A NAME="foot576">... mode</A><A | |
382 | href="tweak-flags.html#tex2html3"><SUP>3</SUP></A></DT> | |
383 | <DD>Then you have no | |
384 | POSIX emulation available, but you also don't need | |
385 | <span class="file">cygwin1.dll</span>. | |
386 | ||
387 | </DD> | |
388 | </DL> | |
389 | <DIV CLASS="navigation"> | |
390 | <div class='online-navigation'> | |
391 | <p></p><hr /> | |
392 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
393 | <tr> | |
394 | <td class='online-navigation'><a rel="prev" title="5 Distutils Configuration Files" | |
395 | href="config-syntax.html"><img src='../icons/previous.png' | |
396 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
397 | <td class='online-navigation'><a rel="parent" title="Installing Python Modules" | |
398 | href="inst.html"><img src='../icons/up.png' | |
399 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
400 | <td class='online-navigation'><a rel="next" title="About this document ..." | |
401 | href="about.html"><img src='../icons/next.png' | |
402 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
403 | <td align="center" width="100%">Installing Python Modules</td> | |
404 | <td class='online-navigation'><img src='../icons/blank.png' | |
405 | border='0' height='32' alt='' width='32' /></td> | |
406 | <td class='online-navigation'><img src='../icons/blank.png' | |
407 | border='0' height='32' alt='' width='32' /></td> | |
408 | <td class='online-navigation'><img src='../icons/blank.png' | |
409 | border='0' height='32' alt='' width='32' /></td> | |
410 | </tr></table> | |
411 | <div class='online-navigation'> | |
412 | <b class="navlabel">Previous:</b> | |
413 | <a class="sectref" rel="prev" href="config-syntax.html">5 Distutils Configuration Files</A> | |
414 | <b class="navlabel">Up:</b> | |
415 | <a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A> | |
416 | <b class="navlabel">Next:</b> | |
417 | <a class="sectref" rel="next" href="about.html">About this document ...</A> | |
418 | </div> | |
419 | </div> | |
420 | <hr /> | |
421 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
422 | </DIV> | |
423 | <!--End of Navigation Panel--> | |
424 | <ADDRESS> | |
425 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
426 | </ADDRESS> | |
427 | </BODY> | |
428 | </HTML> |