Commit | Line | Data |
---|---|---|
920dae64 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="module-distutils.unixccompiler.html" /> | |
12 | <link rel="prev" href="module-distutils.core.html" /> | |
13 | <link rel="parent" href="api-reference.html" /> | |
14 | <link rel="next" href="module-distutils.unixccompiler.html" /> | |
15 | <meta name='aesop' content='information' /> | |
16 | <title>10.2 distutils.ccompiler -- CCompiler base class</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="10.1 distutils.core " | |
24 | href="module-distutils.core.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="10. API Reference" | |
27 | href="api-reference.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="10.3 distutils.unixccompiler " | |
30 | href="module-distutils.unixccompiler.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="module-distutils.core.html">10.1 distutils.core </A> | |
44 | <b class="navlabel">Up:</b> | |
45 | <a class="sectref" rel="parent" href="api-reference.html">10. API Reference</A> | |
46 | <b class="navlabel">Next:</b> | |
47 | <a class="sectref" rel="next" href="module-distutils.unixccompiler.html">10.3 distutils.unixccompiler </A> | |
48 | </div> | |
49 | <hr /></div> | |
50 | </DIV> | |
51 | <!--End of Navigation Panel--> | |
52 | ||
53 | <H1><A NAME="SECTION0010200000000000000000"> | |
54 | 10.2 <tt class="module">distutils.ccompiler</tt> -- CCompiler base class</A> | |
55 | </H1> | |
56 | <A NAME="module-distutils.ccompiler"></A> | |
57 | ||
58 | <P> | |
59 | This module provides the abstract base class for the <tt class="class">CCompiler</tt> | |
60 | classes. A <tt class="class">CCompiler</tt> instance can be used for all the compile | |
61 | and link steps needed to build a single project. Methods are provided to | |
62 | set options for the compiler -- macro definitions, include directories, | |
63 | link path, libraries and the like. | |
64 | ||
65 | <P> | |
66 | This module provides the following functions. | |
67 | ||
68 | <P> | |
69 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
70 | <td><nobr><b><tt id='l2h-12' xml:id='l2h-12' class="function">gen_lib_options</tt></b>(</nobr></td> | |
71 | <td><var>compiler, library_dirs, runtime_library_dirs, libraries</var>)</td></tr></table></dt> | |
72 | <dd> | |
73 | Generate linker options for searching library directories and | |
74 | linking with specific libraries. <var>libraries</var> and <var>library_dirs</var> are, | |
75 | respectively, lists of library names (not filenames!) and search | |
76 | directories. Returns a list of command-line options suitable for use | |
77 | with some compiler (depending on the two format strings passed in). | |
78 | </dl> | |
79 | ||
80 | <P> | |
81 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
82 | <td><nobr><b><tt id='l2h-13' xml:id='l2h-13' class="function">gen_preprocess_options</tt></b>(</nobr></td> | |
83 | <td><var>macros, include_dirs</var>)</td></tr></table></dt> | |
84 | <dd> | |
85 | Generate C pre-processor options (<b class="programopt">-D</b>, <b class="programopt">-U</b>, | |
86 | <b class="programopt">-I</b>) as used by at least | |
87 | two types of compilers: the typical <span class="Unix">Unix</span> compiler and Visual C++. | |
88 | <var>macros</var> is the usual thing, a list of 1- or 2-tuples, where | |
89 | <code>(<var>name</var>,)</code> means undefine (<b class="programopt">-U</b>) macro <var>name</var>, | |
90 | and <code>(<var>name</var>, <var>value</var>)</code> means define (<b class="programopt">-D</b>) | |
91 | macro <var>name</var> to <var>value</var>. <var>include_dirs</var> is just a list of | |
92 | directory names to be added to the header file search path (<b class="programopt">-I</b>). | |
93 | Returns a list of command-line options suitable for either <span class="Unix">Unix</span> compilers | |
94 | or Visual C++. | |
95 | </dl> | |
96 | ||
97 | <P> | |
98 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
99 | <td><nobr><b><tt id='l2h-14' xml:id='l2h-14' class="function">get_default_compiler</tt></b>(</nobr></td> | |
100 | <td><var>osname, platform</var>)</td></tr></table></dt> | |
101 | <dd> | |
102 | Determine the default compiler to use for the given platform. | |
103 | ||
104 | <P> | |
105 | <var>osname</var> should be one of the standard Python OS names (i.e. the | |
106 | ones returned by <code>os.name</code>) and <var>platform</var> the common value | |
107 | returned by <code>sys.platform</code> for the platform in question. | |
108 | ||
109 | <P> | |
110 | The default values are <code>os.name</code> and <code>sys.platform</code> in case the | |
111 | parameters are not given. | |
112 | </dl> | |
113 | ||
114 | <P> | |
115 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
116 | <td><nobr><b><tt id='l2h-15' xml:id='l2h-15' class="function">new_compiler</tt></b>(</nobr></td> | |
117 | <td><var>plat=<code>None</code>, compiler=<code>None</code>, verbose=<code>0</code>, dry_run=<code>0</code>, force=<code>0</code></var>)</td></tr></table></dt> | |
118 | <dd> | |
119 | Factory function to generate an instance of some CCompiler subclass | |
120 | for the supplied platform/compiler combination. <var>plat</var> defaults | |
121 | to <code>os.name</code> (eg. <code>'posix'</code>, <code>'nt'</code>), and <var>compiler</var> | |
122 | defaults to the default compiler for that platform. Currently only | |
123 | <code>'posix'</code> and <code>'nt'</code> are supported, and the default | |
124 | compilers are ``traditional <span class="Unix">Unix</span> interface'' (<tt class="class">UnixCCompiler</tt> | |
125 | class) and Visual C++(<tt class="class">MSVCCompiler</tt> class). Note that it's | |
126 | perfectly possible to ask for a <span class="Unix">Unix</span> compiler object under Windows, | |
127 | and a Microsoft compiler object under <span class="Unix">Unix</span>--if you supply a value | |
128 | for <var>compiler</var>, <var>plat</var> is ignored. | |
129 | </dl> | |
130 | ||
131 | <P> | |
132 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
133 | <td><nobr><b><tt id='l2h-16' xml:id='l2h-16' class="function">show_compilers</tt></b>(</nobr></td> | |
134 | <td><var></var>)</td></tr></table></dt> | |
135 | <dd> | |
136 | Print list of available compilers (used by the | |
137 | <b class="programopt">--help-compiler</b> options to <code class="du-command">build</code>, | |
138 | <code class="du-command">build_ext</code>, <code class="du-command">build_clib</code>). | |
139 | </dl> | |
140 | ||
141 | <P> | |
142 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
143 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-17' xml:id='l2h-17' class="class">CCompiler</tt></b>(</nobr></td> | |
144 | <td><var></var><big>[</big><var>verbose=<code>0</code>, dry_run=<code>0</code>, force=<code>0</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
145 | <dd> | |
146 | ||
147 | <P> | |
148 | The abstract base class <tt class="class">CCompiler</tt> defines the interface that | |
149 | must be implemented by real compiler classes. The class also has | |
150 | some utility methods used by several compiler classes. | |
151 | ||
152 | <P> | |
153 | The basic idea behind a compiler abstraction class is that each | |
154 | instance can be used for all the compile/link steps in building a | |
155 | single project. Thus, attributes common to all of those compile and | |
156 | link steps -- include directories, macros to define, libraries to link | |
157 | against, etc. -- are attributes of the compiler instance. To allow for | |
158 | variability in how individual files are treated, most of those | |
159 | attributes may be varied on a per-compilation or per-link basis. | |
160 | ||
161 | <P> | |
162 | The constructor for each subclass creates an instance of the Compiler | |
163 | object. Flags are <var>verbose</var> (show verbose output), <var>dry_run</var> | |
164 | (don't actually execute the steps) and <var>force</var> (rebuild | |
165 | everything, regardless of dependencies). All of these flags default to | |
166 | <code>0</code> (off). Note that you probably don't want to instantiate | |
167 | <tt class="class">CCompiler</tt> or one of its subclasses directly - use the | |
168 | <tt class="function">distutils.CCompiler.new_compiler()</tt> factory function | |
169 | instead. | |
170 | ||
171 | <P> | |
172 | The following methods allow you to manually alter compiler options for | |
173 | the instance of the Compiler class. | |
174 | ||
175 | <P> | |
176 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
177 | <td><nobr><b><tt id='l2h-18' xml:id='l2h-18' class="method">add_include_dir</tt></b>(</nobr></td> | |
178 | <td><var>dir</var>)</td></tr></table></dt> | |
179 | <dd> | |
180 | Add <var>dir</var> to the list of directories that will be searched for | |
181 | header files. The compiler is instructed to search directories in | |
182 | the order in which they are supplied by successive calls to | |
183 | <tt class="method">add_include_dir()</tt>. | |
184 | </dl> | |
185 | ||
186 | <P> | |
187 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
188 | <td><nobr><b><tt id='l2h-19' xml:id='l2h-19' class="method">set_include_dirs</tt></b>(</nobr></td> | |
189 | <td><var>dirs</var>)</td></tr></table></dt> | |
190 | <dd> | |
191 | Set the list of directories that will be searched to <var>dirs</var> (a | |
192 | list of strings). Overrides any preceding calls to | |
193 | <tt class="method">add_include_dir()</tt>; subsequent calls to | |
194 | <tt class="method">add_include_dir()</tt> add to the list passed to | |
195 | <tt class="method">set_include_dirs()</tt>. This does not affect any list of | |
196 | standard include directories that the compiler may search by default. | |
197 | </dl> | |
198 | ||
199 | <P> | |
200 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
201 | <td><nobr><b><tt id='l2h-20' xml:id='l2h-20' class="method">add_library</tt></b>(</nobr></td> | |
202 | <td><var>libname</var>)</td></tr></table></dt> | |
203 | <dd> | |
204 | ||
205 | <P> | |
206 | Add <var>libname</var> to the list of libraries that will be included in | |
207 | all links driven by this compiler object. Note that <var>libname</var> | |
208 | should *not* be the name of a file containing a library, but the | |
209 | name of the library itself: the actual filename will be inferred by | |
210 | the linker, the compiler, or the compiler class (depending on the | |
211 | platform). | |
212 | ||
213 | <P> | |
214 | The linker will be instructed to link against libraries in the | |
215 | order they were supplied to <tt class="method">add_library()</tt> and/or | |
216 | <tt class="method">set_libraries()</tt>. It is perfectly valid to duplicate library | |
217 | names; the linker will be instructed to link against libraries as | |
218 | many times as they are mentioned. | |
219 | </dl> | |
220 | ||
221 | <P> | |
222 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
223 | <td><nobr><b><tt id='l2h-21' xml:id='l2h-21' class="method">set_libraries</tt></b>(</nobr></td> | |
224 | <td><var>libnames</var>)</td></tr></table></dt> | |
225 | <dd> | |
226 | Set the list of libraries to be included in all links driven by | |
227 | this compiler object to <var>libnames</var> (a list of strings). This does | |
228 | not affect any standard system libraries that the linker may | |
229 | include by default. | |
230 | </dl> | |
231 | ||
232 | <P> | |
233 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
234 | <td><nobr><b><tt id='l2h-22' xml:id='l2h-22' class="method">add_library_dir</tt></b>(</nobr></td> | |
235 | <td><var>dir</var>)</td></tr></table></dt> | |
236 | <dd> | |
237 | Add <var>dir</var> to the list of directories that will be searched for | |
238 | libraries specified to <tt class="method">add_library()</tt> and | |
239 | <tt class="method">set_libraries()</tt>. The linker will be instructed to search for | |
240 | libraries in the order they are supplied to <tt class="method">add_library_dir()</tt> | |
241 | and/or <tt class="method">set_library_dirs()</tt>. | |
242 | </dl> | |
243 | ||
244 | <P> | |
245 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
246 | <td><nobr><b><tt id='l2h-23' xml:id='l2h-23' class="method">set_library_dirs</tt></b>(</nobr></td> | |
247 | <td><var>dirs</var>)</td></tr></table></dt> | |
248 | <dd> | |
249 | Set the list of library search directories to <var>dirs</var> (a list of | |
250 | strings). This does not affect any standard library search path | |
251 | that the linker may search by default. | |
252 | </dl> | |
253 | ||
254 | <P> | |
255 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
256 | <td><nobr><b><tt id='l2h-24' xml:id='l2h-24' class="method">add_runtime_library_dir</tt></b>(</nobr></td> | |
257 | <td><var>dir</var>)</td></tr></table></dt> | |
258 | <dd> | |
259 | Add <var>dir</var> to the list of directories that will be searched for | |
260 | shared libraries at runtime. | |
261 | </dl> | |
262 | ||
263 | <P> | |
264 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
265 | <td><nobr><b><tt id='l2h-25' xml:id='l2h-25' class="method">set_runtime_library_dirs</tt></b>(</nobr></td> | |
266 | <td><var>dirs</var>)</td></tr></table></dt> | |
267 | <dd> | |
268 | Set the list of directories to search for shared libraries at | |
269 | runtime to <var>dirs</var> (a list of strings). This does not affect any | |
270 | standard search path that the runtime linker may search by | |
271 | default. | |
272 | </dl> | |
273 | ||
274 | <P> | |
275 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
276 | <td><nobr><b><tt id='l2h-26' xml:id='l2h-26' class="method">define_macro</tt></b>(</nobr></td> | |
277 | <td><var>name</var><big>[</big><var>, value=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
278 | <dd> | |
279 | Define a preprocessor macro for all compilations driven by this | |
280 | compiler object. The optional parameter <var>value</var> should be a | |
281 | string; if it is not supplied, then the macro will be defined | |
282 | without an explicit value and the exact outcome depends on the | |
283 | compiler used (XXX true? does ANSI say anything about this?) | |
284 | </dl> | |
285 | ||
286 | <P> | |
287 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
288 | <td><nobr><b><tt id='l2h-27' xml:id='l2h-27' class="method">undefine_macro</tt></b>(</nobr></td> | |
289 | <td><var>name</var>)</td></tr></table></dt> | |
290 | <dd> | |
291 | Undefine a preprocessor macro for all compilations driven by | |
292 | this compiler object. If the same macro is defined by | |
293 | <tt class="method">define_macro()</tt> and undefined by <tt class="method">undefine_macro()</tt> | |
294 | the last call takes precedence (including multiple redefinitions or | |
295 | undefinitions). If the macro is redefined/undefined on a | |
296 | per-compilation basis (ie. in the call to <tt class="method">compile()</tt>), then that | |
297 | takes precedence. | |
298 | </dl> | |
299 | ||
300 | <P> | |
301 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
302 | <td><nobr><b><tt id='l2h-28' xml:id='l2h-28' class="method">add_link_object</tt></b>(</nobr></td> | |
303 | <td><var>object</var>)</td></tr></table></dt> | |
304 | <dd> | |
305 | Add <var>object</var> to the list of object files (or analogues, such as | |
306 | explicitly named library files or the output of ``resource | |
307 | compilers'') to be included in every link driven by this compiler | |
308 | object. | |
309 | </dl> | |
310 | ||
311 | <P> | |
312 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
313 | <td><nobr><b><tt id='l2h-29' xml:id='l2h-29' class="method">set_link_objects</tt></b>(</nobr></td> | |
314 | <td><var>objects</var>)</td></tr></table></dt> | |
315 | <dd> | |
316 | Set the list of object files (or analogues) to be included in | |
317 | every link to <var>objects</var>. This does not affect any standard object | |
318 | files that the linker may include by default (such as system | |
319 | libraries). | |
320 | </dl> | |
321 | ||
322 | <P> | |
323 | The following methods implement methods for autodetection of compiler | |
324 | options, providing some functionality similar to GNU <b class="program">autoconf</b>. | |
325 | ||
326 | <P> | |
327 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
328 | <td><nobr><b><tt id='l2h-30' xml:id='l2h-30' class="method">detect_language</tt></b>(</nobr></td> | |
329 | <td><var>sources</var>)</td></tr></table></dt> | |
330 | <dd> | |
331 | Detect the language of a given file, or list of files. Uses the | |
332 | instance attributes <tt class="member">language_map</tt> (a dictionary), and | |
333 | <tt class="member">language_order</tt> (a list) to do the job. | |
334 | </dl> | |
335 | ||
336 | <P> | |
337 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
338 | <td><nobr><b><tt id='l2h-31' xml:id='l2h-31' class="method">find_library_file</tt></b>(</nobr></td> | |
339 | <td><var>dirs, lib</var><big>[</big><var>, debug=<code>0</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
340 | <dd> | |
341 | Search the specified list of directories for a static or shared | |
342 | library file <var>lib</var> and return the full path to that file. If | |
343 | <var>debug</var> is true, look for a debugging version (if that makes sense on | |
344 | the current platform). Return <code>None</code> if <var>lib</var> wasn't found in any of | |
345 | the specified directories. | |
346 | </dl> | |
347 | ||
348 | <P> | |
349 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
350 | <td><nobr><b><tt id='l2h-32' xml:id='l2h-32' class="method">has_function</tt></b>(</nobr></td> | |
351 | <td><var>funcname </var><big>[</big><var>, includes=<code>None</code>, include_dirs=<code>None</code>, libraries=<code>None</code>, library_dirs=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
352 | <dd> | |
353 | Return a boolean indicating whether <var>funcname</var> is supported on | |
354 | the current platform. The optional arguments can be used to | |
355 | augment the compilation environment by providing additional include | |
356 | files and paths and libraries and paths. | |
357 | </dl> | |
358 | ||
359 | <P> | |
360 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
361 | <td><nobr><b><tt id='l2h-33' xml:id='l2h-33' class="method">library_dir_option</tt></b>(</nobr></td> | |
362 | <td><var>dir</var>)</td></tr></table></dt> | |
363 | <dd> | |
364 | Return the compiler option to add <var>dir</var> to the list of | |
365 | directories searched for libraries. | |
366 | </dl> | |
367 | ||
368 | <P> | |
369 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
370 | <td><nobr><b><tt id='l2h-34' xml:id='l2h-34' class="method">library_option</tt></b>(</nobr></td> | |
371 | <td><var>lib</var>)</td></tr></table></dt> | |
372 | <dd> | |
373 | Return the compiler option to add <var>dir</var> to the list of libraries | |
374 | linked into the shared library or executable. | |
375 | </dl> | |
376 | ||
377 | <P> | |
378 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
379 | <td><nobr><b><tt id='l2h-35' xml:id='l2h-35' class="method">runtime_library_dir_option</tt></b>(</nobr></td> | |
380 | <td><var>dir</var>)</td></tr></table></dt> | |
381 | <dd> | |
382 | Return the compiler option to add <var>dir</var> to the list of | |
383 | directories searched for runtime libraries. | |
384 | </dl> | |
385 | ||
386 | <P> | |
387 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
388 | <td><nobr><b><tt id='l2h-36' xml:id='l2h-36' class="method">set_executables</tt></b>(</nobr></td> | |
389 | <td><var>**args</var>)</td></tr></table></dt> | |
390 | <dd> | |
391 | Define the executables (and options for them) that will be run | |
392 | to perform the various stages of compilation. The exact set of | |
393 | executables that may be specified here depends on the compiler | |
394 | class (via the 'executables' class attribute), but most will have: | |
395 | ||
396 | <P> | |
397 | <div class="center"><table class="realtable"> | |
398 | <thead> | |
399 | <tr> | |
400 | <th class="left" >attribute</th> | |
401 | <th class="left" >description</th> | |
402 | </tr> | |
403 | </thead> | |
404 | <tbody> | |
405 | <tr><td class="left" valign="baseline"><attribute>compiler</attribute></td> | |
406 | <td class="left" >the C/C++ compiler</td></tr> | |
407 | <tr><td class="left" valign="baseline"><attribute>linker_so</attribute></td> | |
408 | <td class="left" >linker used to create shared objects and libraries</td></tr> | |
409 | <tr><td class="left" valign="baseline"><attribute>linker_exe</attribute></td> | |
410 | <td class="left" >linker used to create binary executables</td></tr> | |
411 | <tr><td class="left" valign="baseline"><attribute>archiver</attribute></td> | |
412 | <td class="left" >static library creator</td></tr></tbody> | |
413 | </table></div> | |
414 | ||
415 | <P> | |
416 | On platforms with a command-line (<span class="Unix">Unix</span>, DOS/Windows), each of these | |
417 | is a string that will be split into executable name and (optional) | |
418 | list of arguments. (Splitting the string is done similarly to how | |
419 | <span class="Unix">Unix</span> shells operate: words are delimited by spaces, but quotes and | |
420 | backslashes can override this. See | |
421 | <tt class="function">distutils.util.split_quoted()</tt>.) | |
422 | </dl> | |
423 | ||
424 | <P> | |
425 | The following methods invoke stages in the build process. | |
426 | ||
427 | <P> | |
428 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
429 | <td><nobr><b><tt id='l2h-37' xml:id='l2h-37' class="method">compile</tt></b>(</nobr></td> | |
430 | <td><var>sources</var><big>[</big><var>, output_dir=<code>None</code>, macros=<code>None</code>, include_dirs=<code>None</code>, debug=<code>0</code>, extra_preargs=<code>None</code>, extra_postargs=<code>None</code>, depends=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
431 | <dd> | |
432 | Compile one or more source files. Generates object files (e.g. | |
433 | transforms a <span class="file">.c</span> file to a <span class="file">.o</span> file.) | |
434 | ||
435 | <P> | |
436 | <var>sources</var> must be a list of filenames, most likely C/C++ | |
437 | files, but in reality anything that can be handled by a | |
438 | particular compiler and compiler class (eg. <tt class="class">MSVCCompiler</tt> can | |
439 | handle resource files in <var>sources</var>). Return a list of object | |
440 | filenames, one per source filename in <var>sources</var>. Depending on | |
441 | the implementation, not all source files will necessarily be | |
442 | compiled, but all corresponding object filenames will be | |
443 | returned. | |
444 | ||
445 | <P> | |
446 | If <var>output_dir</var> is given, object files will be put under it, while | |
447 | retaining their original path component. That is, <span class="file">foo/bar.c</span> | |
448 | normally compiles to <span class="file">foo/bar.o</span> (for a <span class="Unix">Unix</span> implementation); if | |
449 | <var>output_dir</var> is <var>build</var>, then it would compile to | |
450 | <span class="file">build/foo/bar.o</span>. | |
451 | ||
452 | <P> | |
453 | <var>macros</var>, if given, must be a list of macro definitions. A macro | |
454 | definition is either a <code>(<var>name</var>, <var>value</var>)</code> 2-tuple or a | |
455 | <code>(<var>name</var>,)</code> 1-tuple. | |
456 | The former defines a macro; if the value is <code>None</code>, the macro is | |
457 | defined without an explicit value. The 1-tuple case undefines a | |
458 | macro. Later definitions/redefinitions/undefinitions take | |
459 | precedence. | |
460 | ||
461 | <P> | |
462 | <var>include_dirs</var>, if given, must be a list of strings, the | |
463 | directories to add to the default include file search path for this | |
464 | compilation only. | |
465 | ||
466 | <P> | |
467 | <var>debug</var> is a boolean; if true, the compiler will be instructed to | |
468 | output debug symbols in (or alongside) the object file(s). | |
469 | ||
470 | <P> | |
471 | <var>extra_preargs</var> and <var>extra_postargs</var> are implementation-dependent. | |
472 | On platforms that have the notion of a command-line (e.g. <span class="Unix">Unix</span>, | |
473 | DOS/Windows), they are most likely lists of strings: extra | |
474 | command-line arguments to prepend/append to the compiler command | |
475 | line. On other platforms, consult the implementation class | |
476 | documentation. In any event, they are intended as an escape hatch | |
477 | for those occasions when the abstract compiler framework doesn't | |
478 | cut the mustard. | |
479 | ||
480 | <P> | |
481 | <var>depends</var>, if given, is a list of filenames that all targets | |
482 | depend on. If a source file is older than any file in | |
483 | depends, then the source file will be recompiled. This | |
484 | supports dependency tracking, but only at a coarse | |
485 | granularity. | |
486 | ||
487 | <P> | |
488 | Raises <tt class="exception">CompileError</tt> on failure. | |
489 | </dl> | |
490 | ||
491 | <P> | |
492 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
493 | <td><nobr><b><tt id='l2h-38' xml:id='l2h-38' class="method">create_static_lib</tt></b>(</nobr></td> | |
494 | <td><var>objects, output_libname</var><big>[</big><var>, output_dir=<code>None</code>, debug=<code>0</code>, target_lang=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
495 | <dd> | |
496 | Link a bunch of stuff together to create a static library file. | |
497 | The ``bunch of stuff'' consists of the list of object files supplied | |
498 | as <var>objects</var>, the extra object files supplied to | |
499 | <tt class="method">add_link_object()</tt> and/or <tt class="method">set_link_objects()</tt>, the libraries | |
500 | supplied to <tt class="method">add_library()</tt> and/or <tt class="method">set_libraries()</tt>, and the | |
501 | libraries supplied as <var>libraries</var> (if any). | |
502 | ||
503 | <P> | |
504 | <var>output_libname</var> should be a library name, not a filename; the | |
505 | filename will be inferred from the library name. <var>output_dir</var> is | |
506 | the directory where the library file will be put. XXX defaults to what? | |
507 | ||
508 | <P> | |
509 | <var>debug</var> is a boolean; if true, debugging information will be | |
510 | included in the library (note that on most platforms, it is the | |
511 | compile step where this matters: the <var>debug</var> flag is included here | |
512 | just for consistency). | |
513 | ||
514 | <P> | |
515 | <var>target_lang</var> is the target language for which the given objects | |
516 | are being compiled. This allows specific linkage time treatment of | |
517 | certain languages. | |
518 | ||
519 | <P> | |
520 | Raises <tt class="exception">LibError</tt> on failure. | |
521 | </dl> | |
522 | ||
523 | <P> | |
524 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
525 | <td><nobr><b><tt id='l2h-39' xml:id='l2h-39' class="method">link</tt></b>(</nobr></td> | |
526 | <td><var>target_desc, objects, output_filename</var><big>[</big><var>, output_dir=<code>None</code>, libraries=<code>None</code>, library_dirs=<code>None</code>, runtime_library_dirs=<code>None</code>, export_symbols=<code>None</code>, debug=<code>0</code>, extra_preargs=<code>None</code>, extra_postargs=<code>None</code>, build_temp=<code>None</code>, target_lang=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
527 | <dd> | |
528 | Link a bunch of stuff together to create an executable or | |
529 | shared library file. | |
530 | ||
531 | <P> | |
532 | The ``bunch of stuff'' consists of the list of object files supplied | |
533 | as <var>objects</var>. <var>output_filename</var> should be a filename. If | |
534 | <var>output_dir</var> is supplied, <var>output_filename</var> is relative to it | |
535 | (i.e. <var>output_filename</var> can provide directory components if | |
536 | needed). | |
537 | ||
538 | <P> | |
539 | <var>libraries</var> is a list of libraries to link against. These are | |
540 | library names, not filenames, since they're translated into | |
541 | filenames in a platform-specific way (eg. <var>foo</var> becomes <span class="file">libfoo.a</span> | |
542 | on <span class="Unix">Unix</span> and <span class="file">foo.lib</span> on DOS/Windows). However, they can include a | |
543 | directory component, which means the linker will look in that | |
544 | specific directory rather than searching all the normal locations. | |
545 | ||
546 | <P> | |
547 | <var>library_dirs</var>, if supplied, should be a list of directories to | |
548 | search for libraries that were specified as bare library names | |
549 | (ie. no directory component). These are on top of the system | |
550 | default and those supplied to <tt class="method">add_library_dir()</tt> and/or | |
551 | <tt class="method">set_library_dirs()</tt>. <var>runtime_library_dirs</var> is a list of | |
552 | directories that will be embedded into the shared library and used | |
553 | to search for other shared libraries that *it* depends on at | |
554 | run-time. (This may only be relevant on <span class="Unix">Unix</span>.) | |
555 | ||
556 | <P> | |
557 | <var>export_symbols</var> is a list of symbols that the shared library will | |
558 | export. (This appears to be relevant only on Windows.) | |
559 | ||
560 | <P> | |
561 | <var>debug</var> is as for <tt class="method">compile()</tt> and <tt class="method">create_static_lib()</tt>, | |
562 | with the slight distinction that it actually matters on most platforms (as | |
563 | opposed to <tt class="method">create_static_lib()</tt>, which includes a <var>debug</var> flag | |
564 | mostly for form's sake). | |
565 | ||
566 | <P> | |
567 | <var>extra_preargs</var> and <var>extra_postargs</var> are as for <tt class="method">compile()</tt> | |
568 | (except of course that they supply command-line arguments for the | |
569 | particular linker being used). | |
570 | ||
571 | <P> | |
572 | <var>target_lang</var> is the target language for which the given objects | |
573 | are being compiled. This allows specific linkage time treatment of | |
574 | certain languages. | |
575 | ||
576 | <P> | |
577 | Raises <tt class="exception">LinkError</tt> on failure. | |
578 | </dl> | |
579 | ||
580 | <P> | |
581 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
582 | <td><nobr><b><tt id='l2h-40' xml:id='l2h-40' class="method">link_executable</tt></b>(</nobr></td> | |
583 | <td><var>objects, output_progname</var><big>[</big><var>, output_dir=<code>None</code>, libraries=<code>None</code>, library_dirs=<code>None</code>, runtime_library_dirs=<code>None</code>, debug=<code>0</code>, extra_preargs=<code>None</code>, extra_postargs=<code>None</code>, target_lang=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
584 | <dd> | |
585 | Link an executable. | |
586 | <var>output_progname</var> is the name of the file executable, | |
587 | while <var>objects</var> are a list of object filenames to link in. Other arguments | |
588 | are as for the <tt class="method">link</tt> method. | |
589 | </dl> | |
590 | ||
591 | <P> | |
592 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
593 | <td><nobr><b><tt id='l2h-41' xml:id='l2h-41' class="method">link_shared_lib</tt></b>(</nobr></td> | |
594 | <td><var>objects, output_libname</var><big>[</big><var>, output_dir=<code>None</code>, libraries=<code>None</code>, library_dirs=<code>None</code>, runtime_library_dirs=<code>None</code>, export_symbols=<code>None</code>, debug=<code>0</code>, extra_preargs=<code>None</code>, extra_postargs=<code>None</code>, build_temp=<code>None</code>, target_lang=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
595 | <dd> | |
596 | Link a shared library. <var>output_libname</var> is the name of the output | |
597 | library, while <var>objects</var> is a list of object filenames to link in. | |
598 | Other arguments are as for the <tt class="method">link</tt> method. | |
599 | </dl> | |
600 | ||
601 | <P> | |
602 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
603 | <td><nobr><b><tt id='l2h-42' xml:id='l2h-42' class="method">link_shared_object</tt></b>(</nobr></td> | |
604 | <td><var>objects, output_filename</var><big>[</big><var>, output_dir=<code>None</code>, libraries=<code>None</code>, library_dirs=<code>None</code>, runtime_library_dirs=<code>None</code>, export_symbols=<code>None</code>, debug=<code>0</code>, extra_preargs=<code>None</code>, extra_postargs=<code>None</code>, build_temp=<code>None</code>, target_lang=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
605 | <dd> | |
606 | Link a shared object. <var>output_filename</var> is the name of the shared object | |
607 | that will be created, while <var>objects</var> is a list of object filenames | |
608 | to link in. Other arguments are as for the <tt class="method">link</tt> method. | |
609 | </dl> | |
610 | ||
611 | <P> | |
612 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
613 | <td><nobr><b><tt id='l2h-43' xml:id='l2h-43' class="method">preprocess</tt></b>(</nobr></td> | |
614 | <td><var>source</var><big>[</big><var>, output_file=<code>None</code>, macros=<code>None</code>, include_dirs=<code>None</code>, extra_preargs=<code>None</code>, extra_postargs=<code>None</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
615 | <dd> | |
616 | Preprocess a single C/C++ source file, named in <var>source</var>. | |
617 | Output will be written to file named <var>output_file</var>, or <var>stdout</var> if | |
618 | <var>output_file</var> not supplied. <var>macros</var> is a list of macro | |
619 | definitions as for <tt class="method">compile()</tt>, which will augment the macros set | |
620 | with <tt class="method">define_macro()</tt> and <tt class="method">undefine_macro()</tt>. | |
621 | <var>include_dirs</var> is a list of directory names that will be added to the | |
622 | default list, in the same way as <tt class="method">add_include_dir()</tt>. | |
623 | ||
624 | <P> | |
625 | Raises <tt class="exception">PreprocessError</tt> on failure. | |
626 | </dl> | |
627 | ||
628 | <P> | |
629 | The following utility methods are defined by the <tt class="class">CCompiler</tt> class, | |
630 | for use by the various concrete subclasses. | |
631 | ||
632 | <P> | |
633 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
634 | <td><nobr><b><tt id='l2h-44' xml:id='l2h-44' class="method">executable_filename</tt></b>(</nobr></td> | |
635 | <td><var>basename</var><big>[</big><var>, strip_dir=<code>0</code>, output_dir=<code>''</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
636 | <dd> | |
637 | Returns the filename of the executable for the given <var>basename</var>. | |
638 | Typically for non-Windows platforms this is the same as the basename, | |
639 | while Windows will get a <span class="file">.exe</span> added. | |
640 | </dl> | |
641 | ||
642 | <P> | |
643 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
644 | <td><nobr><b><tt id='l2h-45' xml:id='l2h-45' class="method">library_filename</tt></b>(</nobr></td> | |
645 | <td><var>libname</var><big>[</big><var>, lib_type=<code>'static'</code>, strip_dir=<code>0</code>, output_dir=<code>''</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
646 | <dd> | |
647 | Returns the filename for the given library name on the current platform. | |
648 | On <span class="Unix">Unix</span> a library with <var>lib_type</var> of <code>'static'</code> will typically | |
649 | be of the form <span class="file">liblibname.a</span>, while a <var>lib_type</var> of <code>'dynamic'</code> | |
650 | will be of the form <span class="file">liblibname.so</span>. | |
651 | </dl> | |
652 | ||
653 | <P> | |
654 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
655 | <td><nobr><b><tt id='l2h-46' xml:id='l2h-46' class="method">object_filenames</tt></b>(</nobr></td> | |
656 | <td><var>source_filenames</var><big>[</big><var>, strip_dir=<code>0</code>, output_dir=<code>''</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
657 | <dd> | |
658 | Returns the name of the object files for the given source files. | |
659 | <var>source_filenames</var> should be a list of filenames. | |
660 | </dl> | |
661 | ||
662 | <P> | |
663 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
664 | <td><nobr><b><tt id='l2h-47' xml:id='l2h-47' class="method">shared_object_filename</tt></b>(</nobr></td> | |
665 | <td><var>basename</var><big>[</big><var>, strip_dir=<code>0</code>, output_dir=<code>''</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
666 | <dd> | |
667 | Returns the name of a shared object file for the given file name <var>basename</var>. | |
668 | </dl> | |
669 | ||
670 | <P> | |
671 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
672 | <td><nobr><b><tt id='l2h-48' xml:id='l2h-48' class="method">execute</tt></b>(</nobr></td> | |
673 | <td><var>func, args</var><big>[</big><var>, msg=<code>None</code>, level=<code>1</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
674 | <dd> | |
675 | Invokes <tt class="function">distutils.util.execute()</tt> This method invokes a | |
676 | Python function <var>func</var> with the given arguments <var>args</var>, after | |
677 | logging and taking into account the <var>dry_run</var> flag. XXX see also. | |
678 | </dl> | |
679 | ||
680 | <P> | |
681 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
682 | <td><nobr><b><tt id='l2h-49' xml:id='l2h-49' class="method">spawn</tt></b>(</nobr></td> | |
683 | <td><var>cmd</var>)</td></tr></table></dt> | |
684 | <dd> | |
685 | Invokes <tt class="function">distutils.util.spawn()</tt>. This invokes an external | |
686 | process to run the given command. XXX see also. | |
687 | </dl> | |
688 | ||
689 | <P> | |
690 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
691 | <td><nobr><b><tt id='l2h-50' xml:id='l2h-50' class="method">mkpath</tt></b>(</nobr></td> | |
692 | <td><var>name</var><big>[</big><var>, mode=<code>511</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
693 | <dd> | |
694 | ||
695 | <P> | |
696 | Invokes <tt class="function">distutils.dir_util.mkpath()</tt>. This creates a directory | |
697 | and any missing ancestor directories. XXX see also. | |
698 | </dl> | |
699 | ||
700 | <P> | |
701 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
702 | <td><nobr><b><tt id='l2h-51' xml:id='l2h-51' class="method">move_file</tt></b>(</nobr></td> | |
703 | <td><var>src, dst</var>)</td></tr></table></dt> | |
704 | <dd> | |
705 | Invokes <tt class="method">distutils.file_util.move_file()</tt>. Renames <var>src</var> to | |
706 | <var>dst</var>. XXX see also. | |
707 | </dl> | |
708 | ||
709 | <P> | |
710 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
711 | <td><nobr><b><tt id='l2h-52' xml:id='l2h-52' class="method">announce</tt></b>(</nobr></td> | |
712 | <td><var>msg</var><big>[</big><var>, level=<code>1</code></var><big>]</big><var></var>)</td></tr></table></dt> | |
713 | <dd> | |
714 | Write a message using <tt class="function">distutils.log.debug()</tt>. XXX see also. | |
715 | </dl> | |
716 | ||
717 | <P> | |
718 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
719 | <td><nobr><b><tt id='l2h-53' xml:id='l2h-53' class="method">warn</tt></b>(</nobr></td> | |
720 | <td><var>msg</var>)</td></tr></table></dt> | |
721 | <dd> | |
722 | Write a warning message <var>msg</var> to standard error. | |
723 | </dl> | |
724 | ||
725 | <P> | |
726 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
727 | <td><nobr><b><tt id='l2h-54' xml:id='l2h-54' class="method">debug_print</tt></b>(</nobr></td> | |
728 | <td><var>msg</var>)</td></tr></table></dt> | |
729 | <dd> | |
730 | If the <var>debug</var> flag is set on this <tt class="class">CCompiler</tt> instance, print | |
731 | <var>msg</var> to standard output, otherwise do nothing. | |
732 | </dl> | |
733 | ||
734 | <P> | |
735 | </dl> | |
736 | ||
737 | <P> | |
738 | ||
739 | <DIV CLASS="navigation"> | |
740 | <div class='online-navigation'> | |
741 | <p></p><hr /> | |
742 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
743 | <tr> | |
744 | <td class='online-navigation'><a rel="prev" title="10.1 distutils.core " | |
745 | href="module-distutils.core.html"><img src='../icons/previous.png' | |
746 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
747 | <td class='online-navigation'><a rel="parent" title="10. API Reference" | |
748 | href="api-reference.html"><img src='../icons/up.png' | |
749 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
750 | <td class='online-navigation'><a rel="next" title="10.3 distutils.unixccompiler " | |
751 | href="module-distutils.unixccompiler.html"><img src='../icons/next.png' | |
752 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
753 | <td align="center" width="100%">Distributing Python Modules</td> | |
754 | <td class='online-navigation'><img src='../icons/blank.png' | |
755 | border='0' height='32' alt='' width='32' /></td> | |
756 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
757 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
758 | <td class='online-navigation'><a rel="index" title="Index" | |
759 | href="genindex.html"><img src='../icons/index.png' | |
760 | border='0' height='32' alt='Index' width='32' /></A></td> | |
761 | </tr></table> | |
762 | <div class='online-navigation'> | |
763 | <b class="navlabel">Previous:</b> | |
764 | <a class="sectref" rel="prev" href="module-distutils.core.html">10.1 distutils.core </A> | |
765 | <b class="navlabel">Up:</b> | |
766 | <a class="sectref" rel="parent" href="api-reference.html">10. API Reference</A> | |
767 | <b class="navlabel">Next:</b> | |
768 | <a class="sectref" rel="next" href="module-distutils.unixccompiler.html">10.3 distutils.unixccompiler </A> | |
769 | </div> | |
770 | </div> | |
771 | <hr /> | |
772 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
773 | </DIV> | |
774 | <!--End of Navigation Panel--> | |
775 | <ADDRESS> | |
776 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
777 | </ADDRESS> | |
778 | </BODY> | |
779 | </HTML> |