/Doc/distutils/apiref.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 2004 lines · 1352 code · 652 blank · 0 comment · 0 complexity · a6bfe97b71144243c2f2905f8d1f6e0d MD5 · raw file

Large files are truncated click here to view the full file

  1. .. _api-reference:
  2. *************
  3. API Reference
  4. *************
  5. :mod:`distutils.core` --- Core Distutils functionality
  6. ======================================================
  7. .. module:: distutils.core
  8. :synopsis: The core Distutils functionality
  9. The :mod:`distutils.core` module is the only module that needs to be installed
  10. to use the Distutils. It provides the :func:`setup` (which is called from the
  11. setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
  12. :class:`distutils.cmd.Command` class.
  13. .. function:: setup(arguments)
  14. The basic do-everything function that does most everything you could ever ask
  15. for from a Distutils method. See XXXXX
  16. The setup function takes a large number of arguments. These are laid out in the
  17. following table.
  18. +--------------------+--------------------------------+-------------------------------------------------------------+
  19. | argument name | value | type |
  20. +====================+================================+=============================================================+
  21. | *name* | The name of the package | a string |
  22. +--------------------+--------------------------------+-------------------------------------------------------------+
  23. | *version* | The version number of the | See :mod:`distutils.version` |
  24. | | package | |
  25. +--------------------+--------------------------------+-------------------------------------------------------------+
  26. | *description* | A single line describing the | a string |
  27. | | package | |
  28. +--------------------+--------------------------------+-------------------------------------------------------------+
  29. | *long_description* | Longer description of the | a string |
  30. | | package | |
  31. +--------------------+--------------------------------+-------------------------------------------------------------+
  32. | *author* | The name of the package author | a string |
  33. +--------------------+--------------------------------+-------------------------------------------------------------+
  34. | *author_email* | The email address of the | a string |
  35. | | package author | |
  36. +--------------------+--------------------------------+-------------------------------------------------------------+
  37. | *maintainer* | The name of the current | a string |
  38. | | maintainer, if different from | |
  39. | | the author | |
  40. +--------------------+--------------------------------+-------------------------------------------------------------+
  41. | *maintainer_email* | The email address of the | |
  42. | | current maintainer, if | |
  43. | | different from the author | |
  44. +--------------------+--------------------------------+-------------------------------------------------------------+
  45. | *url* | A URL for the package | a URL |
  46. | | (homepage) | |
  47. +--------------------+--------------------------------+-------------------------------------------------------------+
  48. | *download_url* | A URL to download the package | a URL |
  49. +--------------------+--------------------------------+-------------------------------------------------------------+
  50. | *packages* | A list of Python packages that | a list of strings |
  51. | | distutils will manipulate | |
  52. +--------------------+--------------------------------+-------------------------------------------------------------+
  53. | *py_modules* | A list of Python modules that | a list of strings |
  54. | | distutils will manipulate | |
  55. +--------------------+--------------------------------+-------------------------------------------------------------+
  56. | *scripts* | A list of standalone script | a list of strings |
  57. | | files to be built and | |
  58. | | installed | |
  59. +--------------------+--------------------------------+-------------------------------------------------------------+
  60. | *ext_modules* | A list of Python extensions to | A list of instances of |
  61. | | be built | :class:`distutils.core.Extension` |
  62. +--------------------+--------------------------------+-------------------------------------------------------------+
  63. | *classifiers* | A list of categories for the | The list of available |
  64. | | package | categorizations is at |
  65. | | | http://pypi.python.org/pypi?:action=list_classifiers. |
  66. +--------------------+--------------------------------+-------------------------------------------------------------+
  67. | *distclass* | the :class:`Distribution` | A subclass of |
  68. | | class to use | :class:`distutils.core.Distribution` |
  69. +--------------------+--------------------------------+-------------------------------------------------------------+
  70. | *script_name* | The name of the setup.py | a string |
  71. | | script - defaults to | |
  72. | | ``sys.argv[0]`` | |
  73. +--------------------+--------------------------------+-------------------------------------------------------------+
  74. | *script_args* | Arguments to supply to the | a list of strings |
  75. | | setup script | |
  76. +--------------------+--------------------------------+-------------------------------------------------------------+
  77. | *options* | default options for the setup | a string |
  78. | | script | |
  79. +--------------------+--------------------------------+-------------------------------------------------------------+
  80. | *license* | The license for the package | a string |
  81. +--------------------+--------------------------------+-------------------------------------------------------------+
  82. | *keywords* | Descriptive meta-data, see | |
  83. | | :pep:`314` | |
  84. +--------------------+--------------------------------+-------------------------------------------------------------+
  85. | *platforms* | | |
  86. +--------------------+--------------------------------+-------------------------------------------------------------+
  87. | *cmdclass* | A mapping of command names to | a dictionary |
  88. | | :class:`Command` subclasses | |
  89. +--------------------+--------------------------------+-------------------------------------------------------------+
  90. | *data_files* | A list of data files to | a list |
  91. | | install | |
  92. +--------------------+--------------------------------+-------------------------------------------------------------+
  93. | *package_dir* | A mapping of package to | a dictionary |
  94. | | directory names | |
  95. +--------------------+--------------------------------+-------------------------------------------------------------+
  96. .. function:: run_setup(script_name[, script_args=None, stop_after='run'])
  97. Run a setup script in a somewhat controlled environment, and return the
  98. :class:`distutils.dist.Distribution` instance that drives things. This is
  99. useful if you need to find out the distribution meta-data (passed as keyword
  100. args from *script* to :func:`setup`), or the contents of the config files or
  101. command-line.
  102. *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]``
  103. will be replaced with *script* for the duration of the call. *script_args* is a
  104. list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
  105. for the duration of the call.
  106. *stop_after* tells :func:`setup` when to stop processing; possible values:
  107. +---------------+---------------------------------------------+
  108. | value | description |
  109. +===============+=============================================+
  110. | *init* | Stop after the :class:`Distribution` |
  111. | | instance has been created and populated |
  112. | | with the keyword arguments to :func:`setup` |
  113. +---------------+---------------------------------------------+
  114. | *config* | Stop after config files have been parsed |
  115. | | (and their data stored in the |
  116. | | :class:`Distribution` instance) |
  117. +---------------+---------------------------------------------+
  118. | *commandline* | Stop after the command-line |
  119. | | (``sys.argv[1:]`` or *script_args*) have |
  120. | | been parsed (and the data stored in the |
  121. | | :class:`Distribution` instance.) |
  122. +---------------+---------------------------------------------+
  123. | *run* | Stop after all commands have been run (the |
  124. | | same as if :func:`setup` had been called |
  125. | | in the usual way). This is the default |
  126. | | value. |
  127. +---------------+---------------------------------------------+
  128. In addition, the :mod:`distutils.core` module exposed a number of classes that
  129. live elsewhere.
  130. * :class:`Extension` from :mod:`distutils.extension`
  131. * :class:`Command` from :mod:`distutils.cmd`
  132. * :class:`Distribution` from :mod:`distutils.dist`
  133. A short description of each of these follows, but see the relevant module for
  134. the full reference.
  135. .. class:: Extension
  136. The Extension class describes a single C or C++extension module in a setup
  137. script. It accepts the following keyword arguments in its constructor
  138. +------------------------+--------------------------------+---------------------------+
  139. | argument name | value | type |
  140. +========================+================================+===========================+
  141. | *name* | the full name of the | string |
  142. | | extension, including any | |
  143. | | packages --- ie. *not* a | |
  144. | | filename or pathname, but | |
  145. | | Python dotted name | |
  146. +------------------------+--------------------------------+---------------------------+
  147. | *sources* | list of source filenames, | string |
  148. | | relative to the distribution | |
  149. | | root (where the setup script | |
  150. | | lives), in Unix form (slash- | |
  151. | | separated) for portability. | |
  152. | | Source files may be C, C++, | |
  153. | | SWIG (.i), platform-specific | |
  154. | | resource files, or whatever | |
  155. | | else is recognized by the | |
  156. | | :command:`build_ext` command | |
  157. | | as source for a Python | |
  158. | | extension. | |
  159. +------------------------+--------------------------------+---------------------------+
  160. | *include_dirs* | list of directories to search | string |
  161. | | for C/C++ header files (in | |
  162. | | Unix form for portability) | |
  163. +------------------------+--------------------------------+---------------------------+
  164. | *define_macros* | list of macros to define; each | (string, string) tuple or |
  165. | | macro is defined using a | (name, ``None``) |
  166. | | 2-tuple ``(name, value)``, | |
  167. | | where *value* is | |
  168. | | either the string to define it | |
  169. | | to or ``None`` to define it | |
  170. | | without a particular value | |
  171. | | (equivalent of ``#define FOO`` | |
  172. | | in source or :option:`-DFOO` | |
  173. | | on Unix C compiler command | |
  174. | | line) | |
  175. +------------------------+--------------------------------+---------------------------+
  176. | *undef_macros* | list of macros to undefine | string |
  177. | | explicitly | |
  178. +------------------------+--------------------------------+---------------------------+
  179. | *library_dirs* | list of directories to search | string |
  180. | | for C/C++ libraries at link | |
  181. | | time | |
  182. +------------------------+--------------------------------+---------------------------+
  183. | *libraries* | list of library names (not | string |
  184. | | filenames or paths) to link | |
  185. | | against | |
  186. +------------------------+--------------------------------+---------------------------+
  187. | *runtime_library_dirs* | list of directories to search | string |
  188. | | for C/C++ libraries at run | |
  189. | | time (for shared extensions, | |
  190. | | this is when the extension is | |
  191. | | loaded) | |
  192. +------------------------+--------------------------------+---------------------------+
  193. | *extra_objects* | list of extra files to link | string |
  194. | | with (eg. object files not | |
  195. | | implied by 'sources', static | |
  196. | | library that must be | |
  197. | | explicitly specified, binary | |
  198. | | resource files, etc.) | |
  199. +------------------------+--------------------------------+---------------------------+
  200. | *extra_compile_args* | any extra platform- and | string |
  201. | | compiler-specific information | |
  202. | | to use when compiling the | |
  203. | | source files in 'sources'. For | |
  204. | | platforms and compilers where | |
  205. | | a command line makes sense, | |
  206. | | this is typically a list of | |
  207. | | command-line arguments, but | |
  208. | | for other platforms it could | |
  209. | | be anything. | |
  210. +------------------------+--------------------------------+---------------------------+
  211. | *extra_link_args* | any extra platform- and | string |
  212. | | compiler-specific information | |
  213. | | to use when linking object | |
  214. | | files together to create the | |
  215. | | extension (or to create a new | |
  216. | | static Python interpreter). | |
  217. | | Similar interpretation as for | |
  218. | | 'extra_compile_args'. | |
  219. +------------------------+--------------------------------+---------------------------+
  220. | *export_symbols* | list of symbols to be exported | string |
  221. | | from a shared extension. Not | |
  222. | | used on all platforms, and not | |
  223. | | generally necessary for Python | |
  224. | | extensions, which typically | |
  225. | | export exactly one symbol: | |
  226. | | ``init`` + extension_name. | |
  227. +------------------------+--------------------------------+---------------------------+
  228. | *depends* | list of files that the | string |
  229. | | extension depends on | |
  230. +------------------------+--------------------------------+---------------------------+
  231. | *language* | extension language (i.e. | string |
  232. | | ``'c'``, ``'c++'``, | |
  233. | | ``'objc'``). Will be detected | |
  234. | | from the source extensions if | |
  235. | | not provided. | |
  236. +------------------------+--------------------------------+---------------------------+
  237. .. class:: Distribution
  238. A :class:`Distribution` describes how to build, install and package up a Python
  239. software package.
  240. See the :func:`setup` function for a list of keyword arguments accepted by the
  241. Distribution constructor. :func:`setup` creates a Distribution instance.
  242. .. class:: Command
  243. A :class:`Command` class (or rather, an instance of one of its subclasses)
  244. implement a single distutils command.
  245. :mod:`distutils.ccompiler` --- CCompiler base class
  246. ===================================================
  247. .. module:: distutils.ccompiler
  248. :synopsis: Abstract CCompiler class
  249. This module provides the abstract base class for the :class:`CCompiler`
  250. classes. A :class:`CCompiler` instance can be used for all the compile and
  251. link steps needed to build a single project. Methods are provided to set
  252. options for the compiler --- macro definitions, include directories, link path,
  253. libraries and the like.
  254. This module provides the following functions.
  255. .. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
  256. Generate linker options for searching library directories and linking with
  257. specific libraries. *libraries* and *library_dirs* are, respectively, lists of
  258. library names (not filenames!) and search directories. Returns a list of
  259. command-line options suitable for use with some compiler (depending on the two
  260. format strings passed in).
  261. .. function:: gen_preprocess_options(macros, include_dirs)
  262. Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as
  263. used by at least two types of compilers: the typical Unix compiler and Visual
  264. C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
  265. means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define
  266. (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of
  267. directory names to be added to the header file search path (:option:`-I`).
  268. Returns a list of command-line options suitable for either Unix compilers or
  269. Visual C++.
  270. .. function:: get_default_compiler(osname, platform)
  271. Determine the default compiler to use for the given platform.
  272. *osname* should be one of the standard Python OS names (i.e. the ones returned
  273. by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
  274. the platform in question.
  275. The default values are ``os.name`` and ``sys.platform`` in case the parameters
  276. are not given.
  277. .. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
  278. Factory function to generate an instance of some CCompiler subclass for the
  279. supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
  280. ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for
  281. that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
  282. default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
  283. class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly
  284. possible to ask for a Unix compiler object under Windows, and a Microsoft
  285. compiler object under Unix---if you supply a value for *compiler*, *plat* is
  286. ignored.
  287. .. % Is the posix/nt only thing still true? Mac OS X seems to work, and
  288. .. % returns a UnixCCompiler instance. How to document this... hmm.
  289. .. function:: show_compilers()
  290. Print list of available compilers (used by the :option:`--help-compiler` options
  291. to :command:`build`, :command:`build_ext`, :command:`build_clib`).
  292. .. class:: CCompiler([verbose=0, dry_run=0, force=0])
  293. The abstract base class :class:`CCompiler` defines the interface that must be
  294. implemented by real compiler classes. The class also has some utility methods
  295. used by several compiler classes.
  296. The basic idea behind a compiler abstraction class is that each instance can be
  297. used for all the compile/link steps in building a single project. Thus,
  298. attributes common to all of those compile and link steps --- include
  299. directories, macros to define, libraries to link against, etc. --- are
  300. attributes of the compiler instance. To allow for variability in how individual
  301. files are treated, most of those attributes may be varied on a per-compilation
  302. or per-link basis.
  303. The constructor for each subclass creates an instance of the Compiler object.
  304. Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
  305. steps) and *force* (rebuild everything, regardless of dependencies). All of
  306. these flags default to ``0`` (off). Note that you probably don't want to
  307. instantiate :class:`CCompiler` or one of its subclasses directly - use the
  308. :func:`distutils.CCompiler.new_compiler` factory function instead.
  309. The following methods allow you to manually alter compiler options for the
  310. instance of the Compiler class.
  311. .. method:: CCompiler.add_include_dir(dir)
  312. Add *dir* to the list of directories that will be searched for header files.
  313. The compiler is instructed to search directories in the order in which they are
  314. supplied by successive calls to :meth:`add_include_dir`.
  315. .. method:: CCompiler.set_include_dirs(dirs)
  316. Set the list of directories that will be searched to *dirs* (a list of strings).
  317. Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
  318. :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
  319. This does not affect any list of standard include directories that the compiler
  320. may search by default.
  321. .. method:: CCompiler.add_library(libname)
  322. Add *libname* to the list of libraries that will be included in all links driven
  323. by this compiler object. Note that *libname* should \*not\* be the name of a
  324. file containing a library, but the name of the library itself: the actual
  325. filename will be inferred by the linker, the compiler, or the compiler class
  326. (depending on the platform).
  327. The linker will be instructed to link against libraries in the order they were
  328. supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly
  329. valid to duplicate library names; the linker will be instructed to link against
  330. libraries as many times as they are mentioned.
  331. .. method:: CCompiler.set_libraries(libnames)
  332. Set the list of libraries to be included in all links driven by this compiler
  333. object to *libnames* (a list of strings). This does not affect any standard
  334. system libraries that the linker may include by default.
  335. .. method:: CCompiler.add_library_dir(dir)
  336. Add *dir* to the list of directories that will be searched for libraries
  337. specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be
  338. instructed to search for libraries in the order they are supplied to
  339. :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
  340. .. method:: CCompiler.set_library_dirs(dirs)
  341. Set the list of library search directories to *dirs* (a list of strings). This
  342. does not affect any standard library search path that the linker may search by
  343. default.
  344. .. method:: CCompiler.add_runtime_library_dir(dir)
  345. Add *dir* to the list of directories that will be searched for shared libraries
  346. at runtime.
  347. .. method:: CCompiler.set_runtime_library_dirs(dirs)
  348. Set the list of directories to search for shared libraries at runtime to *dirs*
  349. (a list of strings). This does not affect any standard search path that the
  350. runtime linker may search by default.
  351. .. method:: CCompiler.define_macro(name[, value=None])
  352. Define a preprocessor macro for all compilations driven by this compiler object.
  353. The optional parameter *value* should be a string; if it is not supplied, then
  354. the macro will be defined without an explicit value and the exact outcome
  355. depends on the compiler used (XXX true? does ANSI say anything about this?)
  356. .. method:: CCompiler.undefine_macro(name)
  357. Undefine a preprocessor macro for all compilations driven by this compiler
  358. object. If the same macro is defined by :meth:`define_macro` and
  359. undefined by :meth:`undefine_macro` the last call takes precedence
  360. (including multiple redefinitions or undefinitions). If the macro is
  361. redefined/undefined on a per-compilation basis (ie. in the call to
  362. :meth:`compile`), then that takes precedence.
  363. .. method:: CCompiler.add_link_object(object)
  364. Add *object* to the list of object files (or analogues, such as explicitly named
  365. library files or the output of "resource compilers") to be included in every
  366. link driven by this compiler object.
  367. .. method:: CCompiler.set_link_objects(objects)
  368. Set the list of object files (or analogues) to be included in every link to
  369. *objects*. This does not affect any standard object files that the linker may
  370. include by default (such as system libraries).
  371. The following methods implement methods for autodetection of compiler options,
  372. providing some functionality similar to GNU :program:`autoconf`.
  373. .. method:: CCompiler.detect_language(sources)
  374. Detect the language of a given file, or list of files. Uses the instance
  375. attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a
  376. list) to do the job.
  377. .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
  378. Search the specified list of directories for a static or shared library file
  379. *lib* and return the full path to that file. If *debug* is true, look for a
  380. debugging version (if that makes sense on the current platform). Return
  381. ``None`` if *lib* wasn't found in any of the specified directories.
  382. .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
  383. Return a boolean indicating whether *funcname* is supported on the current
  384. platform. The optional arguments can be used to augment the compilation
  385. environment by providing additional include files and paths and libraries and
  386. paths.
  387. .. method:: CCompiler.library_dir_option(dir)
  388. Return the compiler option to add *dir* to the list of directories searched for
  389. libraries.
  390. .. method:: CCompiler.library_option(lib)
  391. Return the compiler option to add *dir* to the list of libraries linked into the
  392. shared library or executable.
  393. .. method:: CCompiler.runtime_library_dir_option(dir)
  394. Return the compiler option to add *dir* to the list of directories searched for
  395. runtime libraries.
  396. .. method:: CCompiler.set_executables(**args)
  397. Define the executables (and options for them) that will be run to perform the
  398. various stages of compilation. The exact set of executables that may be
  399. specified here depends on the compiler class (via the 'executables' class
  400. attribute), but most will have:
  401. +--------------+------------------------------------------+
  402. | attribute | description |
  403. +==============+==========================================+
  404. | *compiler* | the C/C++ compiler |
  405. +--------------+------------------------------------------+
  406. | *linker_so* | linker used to create shared objects and |
  407. | | libraries |
  408. +--------------+------------------------------------------+
  409. | *linker_exe* | linker used to create binary executables |
  410. +--------------+------------------------------------------+
  411. | *archiver* | static library creator |
  412. +--------------+------------------------------------------+
  413. On platforms with a command-line (Unix, DOS/Windows), each of these is a string
  414. that will be split into executable name and (optional) list of arguments.
  415. (Splitting the string is done similarly to how Unix shells operate: words are
  416. delimited by spaces, but quotes and backslashes can override this. See
  417. :func:`distutils.util.split_quoted`.)
  418. The following methods invoke stages in the build process.
  419. .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
  420. Compile one or more source files. Generates object files (e.g. transforms a
  421. :file:`.c` file to a :file:`.o` file.)
  422. *sources* must be a list of filenames, most likely C/C++ files, but in reality
  423. anything that can be handled by a particular compiler and compiler class (eg.
  424. :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of
  425. object filenames, one per source filename in *sources*. Depending on the
  426. implementation, not all source files will necessarily be compiled, but all
  427. corresponding object filenames will be returned.
  428. If *output_dir* is given, object files will be put under it, while retaining
  429. their original path component. That is, :file:`foo/bar.c` normally compiles to
  430. :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
  431. it would compile to :file:`build/foo/bar.o`.
  432. *macros*, if given, must be a list of macro definitions. A macro definition is
  433. either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
  434. a macro; if the value is ``None``, the macro is defined without an explicit
  435. value. The 1-tuple case undefines a macro. Later
  436. definitions/redefinitions/undefinitions take precedence.
  437. *include_dirs*, if given, must be a list of strings, the directories to add to
  438. the default include file search path for this compilation only.
  439. *debug* is a boolean; if true, the compiler will be instructed to output debug
  440. symbols in (or alongside) the object file(s).
  441. *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
  442. that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
  443. likely lists of strings: extra command-line arguments to prepend/append to the
  444. compiler command line. On other platforms, consult the implementation class
  445. documentation. In any event, they are intended as an escape hatch for those
  446. occasions when the abstract compiler framework doesn't cut the mustard.
  447. *depends*, if given, is a list of filenames that all targets depend on. If a
  448. source file is older than any file in depends, then the source file will be
  449. recompiled. This supports dependency tracking, but only at a coarse
  450. granularity.
  451. Raises :exc:`CompileError` on failure.
  452. .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
  453. Link a bunch of stuff together to create a static library file. The "bunch of
  454. stuff" consists of the list of object files supplied as *objects*, the extra
  455. object files supplied to :meth:`add_link_object` and/or
  456. :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
  457. :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
  458. *output_libname* should be a library name, not a filename; the filename will be
  459. inferred from the library name. *output_dir* is the directory where the library
  460. file will be put. XXX defaults to what?
  461. *debug* is a boolean; if true, debugging information will be included in the
  462. library (note that on most platforms, it is the compile step where this matters:
  463. the *debug* flag is included here just for consistency).
  464. *target_lang* is the target language for which the given objects are being
  465. compiled. This allows specific linkage time treatment of certain languages.
  466. Raises :exc:`LibError` on failure.
  467. .. 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])
  468. Link a bunch of stuff together to create an executable or shared library file.
  469. The "bunch of stuff" consists of the list of object files supplied as *objects*.
  470. *output_filename* should be a filename. If *output_dir* is supplied,
  471. *output_filename* is relative to it (i.e. *output_filename* can provide
  472. directory components if needed).
  473. *libraries* is a list of libraries to link against. These are library names,
  474. not filenames, since they're translated into filenames in a platform-specific
  475. way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
  476. DOS/Windows). However, they can include a directory component, which means the
  477. linker will look in that specific directory rather than searching all the normal
  478. locations.
  479. *library_dirs*, if supplied, should be a list of directories to search for
  480. libraries that were specified as bare library names (ie. no directory
  481. component). These are on top of the system default and those supplied to
  482. :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs*
  483. is a list of directories that will be embedded into the shared library and used
  484. to search for other shared libraries that \*it\* depends on at run-time. (This
  485. may only be relevant on Unix.)
  486. *export_symbols* is a list of symbols that the shared library will export.
  487. (This appears to be relevant only on Windows.)
  488. *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
  489. slight distinction that it actually matters on most platforms (as opposed to
  490. :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
  491. sake).
  492. *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
  493. course that they supply command-line arguments for the particular linker being
  494. used).
  495. *target_lang* is the target language for which the given objects are being
  496. compiled. This allows specific linkage time treatment of certain languages.
  497. Raises :exc:`LinkError` on failure.
  498. .. 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])
  499. Link an executable. *output_progname* is the name of the file executable, while
  500. *objects* are a list of object filenames to link in. Other arguments are as for
  501. the :meth:`link` method.
  502. .. 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])
  503. Link a shared library. *output_libname* is the name of the output library,
  504. while *objects* is a list of object filenames to link in. Other arguments are
  505. as for the :meth:`link` method.
  506. .. 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])
  507. Link a shared object. *output_filename* is the name of the shared object that
  508. will be created, while *objects* is a list of object filenames to link in.
  509. Other arguments are as for the :meth:`link` method.
  510. .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
  511. Preprocess a single C/C++ source file, named in *source*. Output will be written
  512. to file named *output_file*, or *stdout* if *output_file* not supplied.
  513. *macros* is a list of macro definitions as for :meth:`compile`, which will
  514. augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
  515. *include_dirs* is a list of directory names that will be added to the default
  516. list, in the same way as :meth:`add_include_dir`.
  517. Raises :exc:`PreprocessError` on failure.
  518. The following utility methods are defined by the :class:`CCompiler` class, for
  519. use by the various concrete subclasses.
  520. .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
  521. Returns the filename of the executable for the given *basename*. Typically for
  522. non-Windows platforms this is the same as the basename, while Windows will get
  523. a :file:`.exe` added.
  524. .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
  525. Returns the filename for the given library name on the current platform. On Unix
  526. a library with *lib_type* of ``'static'`` will typically be of the form
  527. :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
  528. :file:`liblibname.so`.
  529. .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
  530. Returns the name of the object files for the given source files.
  531. *source_filenames* should be a list of filenames.
  532. .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
  533. Returns the name of a shared object file for the given file name *basename*.
  534. .. method:: CCompiler.execute(func, args[, msg=None, level=1])
  535. Invokes :func:`distutils.util.execute` This method invokes a Python function
  536. *func* with the given arguments *args*, after logging and taking into account
  537. the *dry_run* flag. XXX see also.
  538. .. method:: CCompiler.spawn(cmd)
  539. Invokes :func:`distutils.util.spawn`. This invokes an external process to run
  540. the given command. XXX see also.
  541. .. method:: CCompiler.mkpath(name[, mode=511])
  542. Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any
  543. missing ancestor directories. XXX see also.
  544. .. method:: CCompiler.move_file(src, dst)
  545. Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see
  546. also.
  547. .. method:: CCompiler.announce(msg[, level=1])
  548. Write a message using :func:`distutils.log.debug`. XXX see also.
  549. .. method:: CCompiler.warn(msg)
  550. Write a warning message *msg* to standard error.
  551. .. method:: CCompiler.debug_print(msg)
  552. If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to
  553. standard output, otherwise do nothing.
  554. .. % \subsection{Compiler-specific modules}
  555. .. %
  556. .. % The following modules implement concrete subclasses of the abstract
  557. .. % \class{CCompiler} class. They should not be instantiated directly, but should
  558. .. % be created using \function{distutils.ccompiler.new_compiler()} factory
  559. .. % function.
  560. :mod:`distutils.unixccompiler` --- Unix C Compiler
  561. ==================================================
  562. .. module:: distutils.unixccompiler
  563. :synopsis: UNIX C Compiler
  564. This module provides the :class:`UnixCCompiler` class, a subclass of
  565. :class:`CCompiler` that handles the typical Unix-style command-line C compiler:
  566. * macros defined with :option:`-Dname[=value]`
  567. * macros undefined with :option:`-Uname`
  568. * include search directories specified with :option:`-Idir`
  569. * libraries specified with :option:`-llib`
  570. * library search directories specified with :option:`-Ldir`
  571. * compile handled by :program:`cc` (or similar) executable with :option:`-c`
  572. option: compiles :file:`.c` to :file:`.o`
  573. * link static library handled by :program:`ar` command (possibly with
  574. :program:`ranlib`)
  575. * link shared library handled by :program:`cc` :option:`-shared`
  576. :mod:`distutils.msvccompiler` --- Microsoft Compiler
  577. ====================================================
  578. .. module:: distutils.msvccompiler
  579. :synopsis: Microsoft Compiler
  580. This module provides :class:`MSVCCompiler`, an implementation of the abstract
  581. :class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
  582. modules need to be compiled with the same compiler that was used to compile
  583. Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
  584. 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
  585. binaries are created using the Platform SDK.
  586. :class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
  587. its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
  588. and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
  589. been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
  590. had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
  591. that the distutils user has made an explicit choice to override the compiler
  592. selection by :class:`MSVCCompiler`.
  593. :mod:`distutils.bcppcompiler` --- Borland Compiler
  594. ==================================================
  595. .. module:: distutils.bcppcompiler
  596. This module provides :class:`BorlandCCompiler`, an subclass of the abstract
  597. :class:`CCompiler` class for the Borland C++ compiler.
  598. :mod:`distutils.cygwincompiler` --- Cygwin Compiler
  599. ===================================================
  600. .. module:: distutils.cygwinccompiler
  601. This module provides the :class:`CygwinCCompiler` class, a subclass of
  602. :class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
  603. Windows. It also contains the Mingw32CCompiler class which handles the mingw32
  604. port of GCC (same as cygwin in no-cygwin mode).
  605. :mod:`distutils.emxccompiler` --- OS/2 EMX Compiler
  606. ===================================================
  607. .. module:: distutils.emxccompiler
  608. :synopsis: OS/2 EMX Compiler support
  609. This module provides the EMXCCompiler class, a subclass of
  610. :class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.
  611. :mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support
  612. ==================================================================
  613. .. module:: distutils.mwerkscompiler
  614. :synopsis: Metrowerks CodeWarrior support
  615. Contains :class:`MWerksCompiler`, an implementation of the abstract
  616. :class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X
  617. Macintosh. Needs work to support CW on Windows or Mac OS X.
  618. .. % \subsection{Utility modules}
  619. .. %
  620. .. % The following modules all provide general utility functions. They haven't
  621. .. % all been documented yet.
  622. :mod:`distutils.archive_util` --- Archiving utilities
  623. ======================================================
  624. .. module:: distutils.archive_util
  625. :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
  626. This module provides a few functions for creating archive files, such as
  627. tarballs or zipfiles.
  628. .. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
  629. Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of
  630. the file to create, minus any format-specific extension; *format* is the
  631. archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is
  632. a directory that will be the root directory of the archive; ie. we typically
  633. ``chdir`` into *root_dir* before creating the archive. *base_dir* is the
  634. directory where we start archiving from; ie. *base_dir* will be the common
  635. prefix of all files and directories in the archive. *root_dir* and *base_dir*
  636. both default to the current directory. Returns the name of the archive file.
  637. .. XXX This should be changed to support bz2 files.
  638. .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
  639. 'Create an (optional compressed) archive as a tar file from all files in and
  640. under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``,
  641. ``'bzip2'``, or ``None``. Both :program:`tar` and the compressi