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