blob: f23c5516d5cafb746f97199fbecb0f9f868a679c [file] [log] [blame]
Éric Araujo3a9f58f2011-06-01 20:42:49 +02001:mod:`packaging.compiler` --- Compiler classes
2==============================================
3
4.. module:: packaging.compiler
5 :synopsis: Compiler classes to build C/C++ extensions or libraries.
6
7
8This subpackage contains an abstract base class representing a compiler and
9concrete implementations for common compilers. The compiler classes should not
10be instantiated directly, but created using the :func:`new_compiler` factory
11function. Compiler types provided by Packaging are listed in
12:ref:`packaging-standard-compilers`.
13
14
15Public functions
16----------------
17
Éric Araujo4d155462011-11-15 11:43:20 +010018.. function:: new_compiler(plat=None, compiler=None, dry_run=False, force=False)
Éric Araujo3a9f58f2011-06-01 20:42:49 +020019
20 Factory function to generate an instance of some
21 :class:`~.ccompiler.CCompiler` subclass for the requested platform or
22 compiler type.
23
24 If no argument is given for *plat* and *compiler*, the default compiler type
25 for the platform (:attr:`os.name`) will be used: ``'unix'`` for Unix and
26 Mac OS X, ``'msvc'`` for Windows.
27
28 If *plat* is given, it must be one of ``'posix'``, ``'darwin'`` or ``'nt'``.
29 An invalid value will not raise an exception but use the default compiler
30 type for the current platform.
31
32 .. XXX errors should never pass silently; this behavior is particularly
33 harmful when a compiler type is given as first argument
34
35 If *compiler* is given, *plat* will be ignored, allowing you to get for
36 example a ``'unix'`` compiler object under Windows or an ``'msvc'`` compiler
37 under Unix. However, not all compiler types can be instantiated on every
38 platform.
39
40
41.. function:: customize_compiler(compiler)
42
43 Do any platform-specific customization of a CCompiler instance. Mainly
44 needed on Unix to plug in the information that varies across Unices and is
45 stored in CPython's Makefile.
46
47
48.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
49
50 Generate linker options for searching library directories and linking with
51 specific libraries. *libraries* and *library_dirs* are, respectively, lists
52 of library names (not filenames!) and search directories. Returns a list of
53 command-line options suitable for use with some compiler (depending on the
54 two format strings passed in).
55
56
57.. function:: gen_preprocess_options(macros, include_dirs)
58
59 Generate C preprocessor options (:option:`-D`, :option:`-U`, :option:`-I`) as
60 used by at least two types of compilers: the typical Unix compiler and Visual
61 C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
62 means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means
63 define (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list
64 of directory names to be added to the header file search path (:option:`-I`).
65 Returns a list of command-line options suitable for either Unix compilers or
66 Visual C++.
67
68
69.. function:: get_default_compiler(osname, platform)
70
71 Determine the default compiler to use for the given platform.
72
73 *osname* should be one of the standard Python OS names (i.e. the ones
74 returned by ``os.name``) and *platform* the common value returned by
75 ``sys.platform`` for the platform in question.
76
77 The default values are ``os.name`` and ``sys.platform``.
78
79
80.. function:: set_compiler(location)
81
82 Add or change a compiler
83
84
85.. function:: show_compilers()
86
87 Print list of available compilers (used by the :option:`--help-compiler`
88 options to :command:`build`, :command:`build_ext`, :command:`build_clib`).
89
90
91.. _packaging-standard-compilers:
92
93Standard compilers
94------------------
95
96Concrete subclasses of :class:`~.ccompiler.CCompiler` are provided in submodules
97of the :mod:`packaging.compiler` package. You do not need to import them, using
98:func:`new_compiler` is the public API to use. This table documents the
99standard compilers; be aware that they can be replaced by other classes on your
100platform.
101
102=============== ======================================================== =======
103name description notes
104=============== ======================================================== =======
105``'unix'`` typical Unix-style command-line C compiler [#]_
106``'msvc'`` Microsoft compiler [#]_
107``'bcpp'`` Borland C++ compiler
108``'cygwin'`` Cygwin compiler (Windows port of GCC)
109``'mingw32'`` Mingw32 port of GCC (same as Cygwin in no-Cygwin mode)
110=============== ======================================================== =======
111
112
113.. [#] The Unix compiler class assumes this behavior:
114
115 * macros defined with :option:`-Dname[=value]`
116
117 * macros undefined with :option:`-Uname`
118
119 * include search directories specified with :option:`-Idir`
120
121 * libraries specified with :option:`-llib`
122
123 * library search directories specified with :option:`-Ldir`
124
125 * compile handled by :program:`cc` (or similar) executable with
126 :option:`-c` option: compiles :file:`.c` to :file:`.o`
127
128 * link static library handled by :program:`ar` command (possibly with
129 :program:`ranlib`)
130
131 * link shared library handled by :program:`cc` :option:`-shared`
132
133
134.. [#] On Windows, extension modules typically need to be compiled with the same
135 compiler that was used to compile CPython (for example Microsoft Visual
136 Studio .NET 2003 for CPython 2.4 and 2.5). The AMD64 and Itanium
137 binaries are created using the Platform SDK.
138
139 Under the hood, there are actually two different subclasses of
140 :class:`~.ccompiler.CCompiler` defined: one is compatible with MSVC 2005
141 and 2008, the other works with older versions. This should not be a
142 concern for regular use of the functions in this module.
143
144 Packaging will normally choose the right compiler, linker etc. on its
145 own. To override this choice, the environment variables
146 *DISTUTILS_USE_SDK* and *MSSdk* must be both set. *MSSdk* indicates that
147 the current environment has been setup by the SDK's ``SetEnv.Cmd``
148 script, or that the environment variables had been registered when the
149 SDK was installed; *DISTUTILS_USE_SDK* indicates that the user has made
150 an explicit choice to override the compiler selection done by Packaging.
151
152 .. TODO document the envvars in Doc/using and the man page
153
154
155:mod:`packaging.compiler.ccompiler` --- CCompiler base class
156============================================================
157
158.. module:: packaging.compiler.ccompiler
159 :synopsis: Abstract CCompiler class.
160
161
162This module provides the abstract base class for the :class:`CCompiler`
163classes. A :class:`CCompiler` instance can be used for all the compile and
164link steps needed to build a single project. Methods are provided to set
165options for the compiler --- macro definitions, include directories, link path,
166libraries and the like.
167
Éric Araujo4d155462011-11-15 11:43:20 +0100168.. class:: CCompiler(dry_run=False, force=False)
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200169
170 The abstract base class :class:`CCompiler` defines the interface that must be
171 implemented by real compiler classes. The class also has some utility
172 methods used by several compiler classes.
173
174 The basic idea behind a compiler abstraction class is that each instance can
175 be used for all the compile/link steps in building a single project. Thus,
176 attributes common to all of those compile and link steps --- include
177 directories, macros to define, libraries to link against, etc. --- are
178 attributes of the compiler instance. To allow for variability in how
179 individual files are treated, most of those attributes may be varied on a
180 per-compilation or per-link basis.
181
182 The constructor for each subclass creates an instance of the Compiler object.
Éric Araujo4d155462011-11-15 11:43:20 +0100183 Flags are *dry_run* (don't actually execute
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200184 the steps) and *force* (rebuild everything, regardless of dependencies). All
Éric Araujo4d155462011-11-15 11:43:20 +0100185 of these flags default to ``False`` (off). Note that you probably don't want to
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200186 instantiate :class:`CCompiler` or one of its subclasses directly - use the
Éric Araujo4d155462011-11-15 11:43:20 +0100187 :func:`new_compiler` factory function instead.
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200188
189 The following methods allow you to manually alter compiler options for the
190 instance of the Compiler class.
191
192
193 .. method:: CCompiler.add_include_dir(dir)
194
195 Add *dir* to the list of directories that will be searched for header
196 files. The compiler is instructed to search directories in the order in
197 which they are supplied by successive calls to :meth:`add_include_dir`.
198
199
200 .. method:: CCompiler.set_include_dirs(dirs)
201
202 Set the list of directories that will be searched to *dirs* (a list of
203 strings). Overrides any preceding calls to :meth:`add_include_dir`;
204 subsequent calls to :meth:`add_include_dir` add to the list passed to
205 :meth:`set_include_dirs`. This does not affect any list of standard
206 include directories that the compiler may search by default.
207
208
209 .. method:: CCompiler.add_library(libname)
210
211 Add *libname* to the list of libraries that will be included in all links
212 driven by this compiler object. Note that *libname* should *not* be the
213 name of a file containing a library, but the name of the library itself:
214 the actual filename will be inferred by the linker, the compiler, or the
215 compiler class (depending on the platform).
216
217 The linker will be instructed to link against libraries in the order they
218 were supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is
219 perfectly valid to duplicate library names; the linker will be instructed
220 to link against libraries as many times as they are mentioned.
221
222
223 .. method:: CCompiler.set_libraries(libnames)
224
225 Set the list of libraries to be included in all links driven by this
226 compiler object to *libnames* (a list of strings). This does not affect
227 any standard system libraries that the linker may include by default.
228
229
230 .. method:: CCompiler.add_library_dir(dir)
231
232 Add *dir* to the list of directories that will be searched for libraries
233 specified to :meth:`add_library` and :meth:`set_libraries`. The linker
234 will be instructed to search for libraries in the order they are supplied
235 to :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
236
237
238 .. method:: CCompiler.set_library_dirs(dirs)
239
240 Set the list of library search directories to *dirs* (a list of strings).
241 This does not affect any standard library search path that the linker may
242 search by default.
243
244
245 .. method:: CCompiler.add_runtime_library_dir(dir)
246
247 Add *dir* to the list of directories that will be searched for shared
248 libraries at runtime.
249
250
251 .. method:: CCompiler.set_runtime_library_dirs(dirs)
252
253 Set the list of directories to search for shared libraries at runtime to
254 *dirs* (a list of strings). This does not affect any standard search path
255 that the runtime linker may search by default.
256
257
258 .. method:: CCompiler.define_macro(name[, value=None])
259
260 Define a preprocessor macro for all compilations driven by this compiler
261 object. The optional parameter *value* should be a string; if it is not
262 supplied, then the macro will be defined without an explicit value and the
263 exact outcome depends on the compiler used (XXX true? does ANSI say
264 anything about this?)
265
266
267 .. method:: CCompiler.undefine_macro(name)
268
269 Undefine a preprocessor macro for all compilations driven by this compiler
270 object. If the same macro is defined by :meth:`define_macro` and
271 undefined by :meth:`undefine_macro` the last call takes precedence
272 (including multiple redefinitions or undefinitions). If the macro is
273 redefined/undefined on a per-compilation basis (i.e. in the call to
274 :meth:`compile`), then that takes precedence.
275
276
277 .. method:: CCompiler.add_link_object(object)
278
279 Add *object* to the list of object files (or analogues, such as explicitly
280 named library files or the output of "resource compilers") to be included
281 in every link driven by this compiler object.
282
283
284 .. method:: CCompiler.set_link_objects(objects)
285
286 Set the list of object files (or analogues) to be included in every link
287 to *objects*. This does not affect any standard object files that the
288 linker may include by default (such as system libraries).
289
290 The following methods implement methods for autodetection of compiler
291 options, providing some functionality similar to GNU :program:`autoconf`.
292
293
294 .. method:: CCompiler.detect_language(sources)
295
296 Detect the language of a given file, or list of files. Uses the instance
297 attributes :attr:`language_map` (a dictionary), and :attr:`language_order`
298 (a list) to do the job.
299
300
301 .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
302
303 Search the specified list of directories for a static or shared library file
304 *lib* and return the full path to that file. If *debug* is true, look for a
305 debugging version (if that makes sense on the current platform). Return
306 ``None`` if *lib* wasn't found in any of the specified directories.
307
308
309 .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
310
311 Return a boolean indicating whether *funcname* is supported on the current
312 platform. The optional arguments can be used to augment the compilation
313 environment by providing additional include files and paths and libraries and
314 paths.
315
316
317 .. method:: CCompiler.library_dir_option(dir)
318
319 Return the compiler option to add *dir* to the list of directories searched for
320 libraries.
321
322
323 .. method:: CCompiler.library_option(lib)
324
325 Return the compiler option to add *dir* to the list of libraries linked into the
326 shared library or executable.
327
328
329 .. method:: CCompiler.runtime_library_dir_option(dir)
330
331 Return the compiler option to add *dir* to the list of directories searched for
332 runtime libraries.
333
334
335 .. method:: CCompiler.set_executables(**args)
336
337 Define the executables (and options for them) that will be run to perform the
338 various stages of compilation. The exact set of executables that may be
339 specified here depends on the compiler class (via the 'executables' class
340 attribute), but most will have:
341
342 +--------------+------------------------------------------+
343 | attribute | description |
344 +==============+==========================================+
345 | *compiler* | the C/C++ compiler |
346 +--------------+------------------------------------------+
347 | *linker_so* | linker used to create shared objects and |
348 | | libraries |
349 +--------------+------------------------------------------+
350 | *linker_exe* | linker used to create binary executables |
351 +--------------+------------------------------------------+
352 | *archiver* | static library creator |
353 +--------------+------------------------------------------+
354
355 On platforms with a command line (Unix, DOS/Windows), each of these is a string
356 that will be split into executable name and (optional) list of arguments.
357 (Splitting the string is done similarly to how Unix shells operate: words are
358 delimited by spaces, but quotes and backslashes can override this. See
359 :func:`packaging.util.split_quoted`.)
360
361 The following methods invoke stages in the build process.
362
363
364 .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
365
366 Compile one or more source files. Generates object files (e.g. transforms a
367 :file:`.c` file to a :file:`.o` file.)
368
369 *sources* must be a list of filenames, most likely C/C++ files, but in reality
370 anything that can be handled by a particular compiler and compiler class (e.g.
Georg Brandld3b41c62011-07-09 11:48:50 +0200371 an ``'msvc'`` compiler can handle resource files in *sources*). Return a list of
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200372 object filenames, one per source filename in *sources*. Depending on the
373 implementation, not all source files will necessarily be compiled, but all
374 corresponding object filenames will be returned.
375
376 If *output_dir* is given, object files will be put under it, while retaining
377 their original path component. That is, :file:`foo/bar.c` normally compiles to
378 :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
379 it would compile to :file:`build/foo/bar.o`.
380
381 *macros*, if given, must be a list of macro definitions. A macro definition is
382 either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
383 a macro; if the value is ``None``, the macro is defined without an explicit
384 value. The 1-tuple case undefines a macro. Later
385 definitions/redefinitions/undefinitions take precedence.
386
387 *include_dirs*, if given, must be a list of strings, the directories to add to
388 the default include file search path for this compilation only.
389
390 *debug* is a boolean; if true, the compiler will be instructed to output debug
391 symbols in (or alongside) the object file(s).
392
393 *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
394 that have the notion of a command line (e.g. Unix, DOS/Windows), they are most
395 likely lists of strings: extra command-line arguments to prepend/append to the
396 compiler command line. On other platforms, consult the implementation class
397 documentation. In any event, they are intended as an escape hatch for those
398 occasions when the abstract compiler framework doesn't cut the mustard.
399
400 *depends*, if given, is a list of filenames that all targets depend on. If a
401 source file is older than any file in depends, then the source file will be
402 recompiled. This supports dependency tracking, but only at a coarse
403 granularity.
404
405 Raises :exc:`CompileError` on failure.
406
407
408 .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
409
410 Link a bunch of stuff together to create a static library file. The "bunch of
411 stuff" consists of the list of object files supplied as *objects*, the extra
412 object files supplied to :meth:`add_link_object` and/or
413 :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
414 :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
415
416 *output_libname* should be a library name, not a filename; the filename will be
417 inferred from the library name. *output_dir* is the directory where the library
418 file will be put. XXX defaults to what?
419
420 *debug* is a boolean; if true, debugging information will be included in the
421 library (note that on most platforms, it is the compile step where this matters:
422 the *debug* flag is included here just for consistency).
423
424 *target_lang* is the target language for which the given objects are being
425 compiled. This allows specific linkage time treatment of certain languages.
426
427 Raises :exc:`LibError` on failure.
428
429
430 .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
431
432 Link a bunch of stuff together to create an executable or shared library file.
433
434 The "bunch of stuff" consists of the list of object files supplied as *objects*.
435 *output_filename* should be a filename. If *output_dir* is supplied,
436 *output_filename* is relative to it (i.e. *output_filename* can provide
437 directory components if needed).
438
439 *libraries* is a list of libraries to link against. These are library names,
440 not filenames, since they're translated into filenames in a platform-specific
441 way (e.g. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
442 DOS/Windows). However, they can include a directory component, which means the
443 linker will look in that specific directory rather than searching all the normal
444 locations.
445
446 *library_dirs*, if supplied, should be a list of directories to search for
447 libraries that were specified as bare library names (i.e. no directory
448 component). These are on top of the system default and those supplied to
449 :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs*
450 is a list of directories that will be embedded into the shared library and used
451 to search for other shared libraries that \*it\* depends on at run-time. (This
452 may only be relevant on Unix.)
453
454 *export_symbols* is a list of symbols that the shared library will export.
455 (This appears to be relevant only on Windows.)
456
457 *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
458 slight distinction that it actually matters on most platforms (as opposed to
459 :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
460 sake).
461
462 *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
463 course that they supply command-line arguments for the particular linker being
464 used).
465
466 *target_lang* is the target language for which the given objects are being
467 compiled. This allows specific linkage time treatment of certain languages.
468
469 Raises :exc:`LinkError` on failure.
470
471
472 .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
473
474 Link an executable. *output_progname* is the name of the file executable, while
475 *objects* are a list of object filenames to link in. Other arguments are as for
476 the :meth:`link` method.
477
478
479 .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
480
481 Link a shared library. *output_libname* is the name of the output library,
482 while *objects* is a list of object filenames to link in. Other arguments are
483 as for the :meth:`link` method.
484
485
486 .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
487
488 Link a shared object. *output_filename* is the name of the shared object that
489 will be created, while *objects* is a list of object filenames to link in.
490 Other arguments are as for the :meth:`link` method.
491
492
493 .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
494
495 Preprocess a single C/C++ source file, named in *source*. Output will be written
496 to file named *output_file*, or *stdout* if *output_file* not supplied.
497 *macros* is a list of macro definitions as for :meth:`compile`, which will
498 augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
499 *include_dirs* is a list of directory names that will be added to the default
500 list, in the same way as :meth:`add_include_dir`.
501
502 Raises :exc:`PreprocessError` on failure.
503
504 The following utility methods are defined by the :class:`CCompiler` class, for
505 use by the various concrete subclasses.
506
507
508 .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
509
510 Returns the filename of the executable for the given *basename*. Typically for
511 non-Windows platforms this is the same as the basename, while Windows will get
512 a :file:`.exe` added.
513
514
515 .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
516
517 Returns the filename for the given library name on the current platform. On Unix
518 a library with *lib_type* of ``'static'`` will typically be of the form
519 :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
520 :file:`liblibname.so`.
521
522
523 .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
524
525 Returns the name of the object files for the given source files.
526 *source_filenames* should be a list of filenames.
527
528
529 .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
530
531 Returns the name of a shared object file for the given file name *basename*.
532
533
534 .. method:: CCompiler.execute(func, args[, msg=None, level=1])
535
536 Invokes :func:`packaging.util.execute` This method invokes a Python function
537 *func* with the given arguments *args*, after logging and taking into account
538 the *dry_run* flag. XXX see also.
539
540
541 .. method:: CCompiler.spawn(cmd)
542
543 Invokes :func:`packaging.util.spawn`. This invokes an external process to run
544 the given command. XXX see also.
545
546
547 .. method:: CCompiler.mkpath(name[, mode=511])
548
549 Invokes :func:`packaging.dir_util.mkpath`. This creates a directory and any
550 missing ancestor directories. XXX see also.
551
552
553 .. method:: CCompiler.move_file(src, dst)
554
555 Invokes :meth:`packaging.file_util.move_file`. Renames *src* to *dst*. XXX see
556 also.
557
558
559:mod:`packaging.compiler.extension` --- The Extension class
560===========================================================
561
562.. module:: packaging.compiler.extension
563 :synopsis: Class used to represent C/C++ extension modules.
564
565
566This module provides the :class:`Extension` class, used to represent C/C++
567extension modules.
568
569.. class:: Extension
570
571 The Extension class describes a single C or C++ extension module. It accepts
Éric Araujoc7f9f2b2011-06-09 08:18:17 +0200572 the following keyword arguments in its constructor:
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200573
574 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200575 | argument name | value | type |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200576 +========================+================================+===========================+
577 | *name* | the full name of the | string |
578 | | extension, including any | |
579 | | packages --- i.e. *not* a | |
580 | | filename or pathname, but | |
581 | | Python dotted name | |
582 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200583 | *sources* | list of source filenames, | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200584 | | relative to the distribution | |
585 | | root (where the setup script | |
586 | | lives), in Unix form (slash- | |
587 | | separated) for portability. | |
588 | | Source files may be C, C++, | |
589 | | SWIG (.i), platform-specific | |
590 | | resource files, or whatever | |
591 | | else is recognized by the | |
592 | | :command:`build_ext` command | |
593 | | as source for a Python | |
594 | | extension. | |
595 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200596 | *include_dirs* | list of directories to search | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200597 | | for C/C++ header files (in | |
598 | | Unix form for portability) | |
599 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200600 | *define_macros* | list of macros to define; each | list of tuples |
601 | | macro is defined using a | |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200602 | | 2-tuple ``(name, value)``, | |
603 | | where *value* is | |
604 | | either the string to define it | |
605 | | to or ``None`` to define it | |
606 | | without a particular value | |
607 | | (equivalent of ``#define FOO`` | |
608 | | in source or :option:`-DFOO` | |
609 | | on Unix C compiler command | |
610 | | line) | |
611 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200612 | *undef_macros* | list of macros to undefine | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200613 | | explicitly | |
614 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200615 | *library_dirs* | list of directories to search | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200616 | | for C/C++ libraries at link | |
617 | | time | |
618 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200619 | *libraries* | list of library names (not | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200620 | | filenames or paths) to link | |
621 | | against | |
622 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200623 | *runtime_library_dirs* | list of directories to search | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200624 | | for C/C++ libraries at run | |
625 | | time (for shared extensions, | |
626 | | this is when the extension is | |
627 | | loaded) | |
628 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200629 | *extra_objects* | list of extra files to link | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200630 | | with (e.g. object files not | |
631 | | implied by 'sources', static | |
632 | | library that must be | |
633 | | explicitly specified, binary | |
634 | | resource files, etc.) | |
635 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200636 | *extra_compile_args* | any extra platform- and | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200637 | | compiler-specific information | |
638 | | to use when compiling the | |
639 | | source files in 'sources'. For | |
640 | | platforms and compilers where | |
641 | | a command line makes sense, | |
642 | | this is typically a list of | |
643 | | command-line arguments, but | |
644 | | for other platforms it could | |
645 | | be anything. | |
646 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200647 | *extra_link_args* | any extra platform- and | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200648 | | compiler-specific information | |
649 | | to use when linking object | |
650 | | files together to create the | |
651 | | extension (or to create a new | |
652 | | static Python interpreter). | |
653 | | Similar interpretation as for | |
654 | | 'extra_compile_args'. | |
655 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200656 | *export_symbols* | list of symbols to be exported | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200657 | | from a shared extension. Not | |
658 | | used on all platforms, and not | |
659 | | generally necessary for Python | |
660 | | extensions, which typically | |
661 | | export exactly one symbol: | |
662 | | ``init`` + extension_name. | |
663 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200664 | *depends* | list of files that the | list of strings |
Éric Araujo3a9f58f2011-06-01 20:42:49 +0200665 | | extension depends on | |
666 +------------------------+--------------------------------+---------------------------+
667 | *language* | extension language (i.e. | string |
668 | | ``'c'``, ``'c++'``, | |
669 | | ``'objc'``). Will be detected | |
670 | | from the source extensions if | |
671 | | not provided. | |
672 +------------------------+--------------------------------+---------------------------+
Éric Araujob008d3d2011-08-26 01:23:20 +0200673 | *optional* | specifies that a build failure | boolean |
674 | | in the extension should not | |
675 | | abort the build process, but | |
676 | | simply skip the extension. | |
677 +------------------------+--------------------------------+---------------------------+
Éric Araujo4d4b19e2011-10-21 07:34:00 +0200678
679To distribute extension modules that live in a package (e.g. ``package.ext``),
Éric Araujodf7b6652011-10-22 01:44:36 +0200680you need to create a :file:`{package}/__init__.py` file to let Python recognize
681and import your module.