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. 25 26 The setup function takes a large number of arguments. These are laid out in the 27 following table. 28 29 .. tabularcolumns:: |l|L|L| 30 31 +--------------------+--------------------------------+-------------------------------------------------------------+ 32 | argument name | value | type | 33 +====================+================================+=============================================================+ 34 | *name* | The name of the package | a string | 35 +--------------------+--------------------------------+-------------------------------------------------------------+ 36 | *version* | The version number of the | a string | 37 | | package; see | | 38 | | :mod:`distutils.version` | | 39 +--------------------+--------------------------------+-------------------------------------------------------------+ 40 | *description* | A single line describing the | a string | 41 | | package | | 42 +--------------------+--------------------------------+-------------------------------------------------------------+ 43 | *long_description* | Longer description of the | a string | 44 | | package | | 45 +--------------------+--------------------------------+-------------------------------------------------------------+ 46 | *author* | The name of the package author | a string | 47 +--------------------+--------------------------------+-------------------------------------------------------------+ 48 | *author_email* | The email address of the | a string | 49 | | package author | | 50 +--------------------+--------------------------------+-------------------------------------------------------------+ 51 | *maintainer* | The name of the current | a string | 52 | | maintainer, if different from | | 53 | | the author. Note that if | | 54 | | the maintainer is provided, | | 55 | | distutils will use it as the | | 56 | | author in :file:`PKG-INFO` | | 57 +--------------------+--------------------------------+-------------------------------------------------------------+ 58 | *maintainer_email* | The email address of the | a string | 59 | | current maintainer, if | | 60 | | different from the author | | 61 +--------------------+--------------------------------+-------------------------------------------------------------+ 62 | *url* | A URL for the package | a string | 63 | | (homepage) | | 64 +--------------------+--------------------------------+-------------------------------------------------------------+ 65 | *download_url* | A URL to download the package | a string | 66 +--------------------+--------------------------------+-------------------------------------------------------------+ 67 | *packages* | A list of Python packages that | a list of strings | 68 | | distutils will manipulate | | 69 +--------------------+--------------------------------+-------------------------------------------------------------+ 70 | *py_modules* | A list of Python modules that | a list of strings | 71 | | distutils will manipulate | | 72 +--------------------+--------------------------------+-------------------------------------------------------------+ 73 | *scripts* | A list of standalone script | a list of strings | 74 | | files to be built and | | 75 | | installed | | 76 +--------------------+--------------------------------+-------------------------------------------------------------+ 77 | *ext_modules* | A list of Python extensions to | a list of instances of | 78 | | be built | :class:`distutils.core.Extension` | 79 +--------------------+--------------------------------+-------------------------------------------------------------+ 80 | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI | 81 | | package | <https://pypi.python.org/pypi?:action=list_classifiers>`_. | 82 +--------------------+--------------------------------+-------------------------------------------------------------+ 83 | *distclass* | the :class:`Distribution` | a subclass of | 84 | | class to use | :class:`distutils.core.Distribution` | 85 +--------------------+--------------------------------+-------------------------------------------------------------+ 86 | *script_name* | The name of the setup.py | a string | 87 | | script - defaults to | | 88 | | ``sys.argv[0]`` | | 89 +--------------------+--------------------------------+-------------------------------------------------------------+ 90 | *script_args* | Arguments to supply to the | a list of strings | 91 | | setup script | | 92 +--------------------+--------------------------------+-------------------------------------------------------------+ 93 | *options* | default options for the setup | a dictionary | 94 | | script | | 95 +--------------------+--------------------------------+-------------------------------------------------------------+ 96 | *license* | The license for the package | a string | 97 +--------------------+--------------------------------+-------------------------------------------------------------+ 98 | *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string | 99 | | :pep:`314` | | 100 +--------------------+--------------------------------+-------------------------------------------------------------+ 101 | *platforms* | | a list of strings or a comma-separated string | 102 +--------------------+--------------------------------+-------------------------------------------------------------+ 103 | *cmdclass* | A mapping of command names to | a dictionary | 104 | | :class:`Command` subclasses | | 105 +--------------------+--------------------------------+-------------------------------------------------------------+ 106 | *data_files* | A list of data files to | a list | 107 | | install | | 108 +--------------------+--------------------------------+-------------------------------------------------------------+ 109 | *package_dir* | A mapping of package to | a dictionary | 110 | | directory names | | 111 +--------------------+--------------------------------+-------------------------------------------------------------+ 112 113 114 115.. function:: run_setup(script_name[, script_args=None, stop_after='run']) 116 117 Run a setup script in a somewhat controlled environment, and return the 118 :class:`distutils.dist.Distribution` instance that drives things. This is 119 useful if you need to find out the distribution meta-data (passed as keyword 120 args from *script* to :func:`setup`), or the contents of the config files or 121 command-line. 122 123 *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]`` 124 will be replaced with *script* for the duration of the call. *script_args* is a 125 list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args* 126 for the duration of the call. 127 128 *stop_after* tells :func:`setup` when to stop processing; possible values: 129 130 .. tabularcolumns:: |l|L| 131 132 +---------------+---------------------------------------------+ 133 | value | description | 134 +===============+=============================================+ 135 | *init* | Stop after the :class:`Distribution` | 136 | | instance has been created and populated | 137 | | with the keyword arguments to :func:`setup` | 138 +---------------+---------------------------------------------+ 139 | *config* | Stop after config files have been parsed | 140 | | (and their data stored in the | 141 | | :class:`Distribution` instance) | 142 +---------------+---------------------------------------------+ 143 | *commandline* | Stop after the command-line | 144 | | (``sys.argv[1:]`` or *script_args*) have | 145 | | been parsed (and the data stored in the | 146 | | :class:`Distribution` instance.) | 147 +---------------+---------------------------------------------+ 148 | *run* | Stop after all commands have been run (the | 149 | | same as if :func:`setup` had been called | 150 | | in the usual way). This is the default | 151 | | value. | 152 +---------------+---------------------------------------------+ 153 154In addition, the :mod:`distutils.core` module exposed a number of classes that 155live elsewhere. 156 157* :class:`~distutils.extension.Extension` from :mod:`distutils.extension` 158 159* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` 160 161* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` 162 163A short description of each of these follows, but see the relevant module for 164the full reference. 165 166 167.. class:: Extension 168 169 The Extension class describes a single C or C++ extension module in a setup 170 script. It accepts the following keyword arguments in its constructor 171 172 .. tabularcolumns:: |l|L|l| 173 174 +------------------------+--------------------------------+---------------------------+ 175 | argument name | value | type | 176 +========================+================================+===========================+ 177 | *name* | the full name of the | a string | 178 | | extension, including any | | 179 | | packages --- ie. *not* a | | 180 | | filename or pathname, but | | 181 | | Python dotted name | | 182 +------------------------+--------------------------------+---------------------------+ 183 | *sources* | list of source filenames, | a list of strings | 184 | | relative to the distribution | | 185 | | root (where the setup script | | 186 | | lives), in Unix form (slash- | | 187 | | separated) for portability. | | 188 | | Source files may be C, C++, | | 189 | | SWIG (.i), platform-specific | | 190 | | resource files, or whatever | | 191 | | else is recognized by the | | 192 | | :command:`build_ext` command | | 193 | | as source for a Python | | 194 | | extension. | | 195 +------------------------+--------------------------------+---------------------------+ 196 | *include_dirs* | list of directories to search | a list of strings | 197 | | for C/C++ header files (in | | 198 | | Unix form for portability) | | 199 +------------------------+--------------------------------+---------------------------+ 200 | *define_macros* | list of macros to define; each | a list of tuples | 201 | | macro is defined using a | | 202 | | 2-tuple ``(name, value)``, | | 203 | | where *value* is | | 204 | | either the string to define it | | 205 | | to or ``None`` to define it | | 206 | | without a particular value | | 207 | | (equivalent of ``#define FOO`` | | 208 | | in source or :option:`!-DFOO` | | 209 | | on Unix C compiler command | | 210 | | line) | | 211 +------------------------+--------------------------------+---------------------------+ 212 | *undef_macros* | list of macros to undefine | a list of strings | 213 | | explicitly | | 214 +------------------------+--------------------------------+---------------------------+ 215 | *library_dirs* | list of directories to search | a list of strings | 216 | | for C/C++ libraries at link | | 217 | | time | | 218 +------------------------+--------------------------------+---------------------------+ 219 | *libraries* | list of library names (not | a list of strings | 220 | | filenames or paths) to link | | 221 | | against | | 222 +------------------------+--------------------------------+---------------------------+ 223 | *runtime_library_dirs* | list of directories to search | a list of strings | 224 | | for C/C++ libraries at run | | 225 | | time (for shared extensions, | | 226 | | this is when the extension is | | 227 | | loaded) | | 228 +------------------------+--------------------------------+---------------------------+ 229 | *extra_objects* | list of extra files to link | a list of strings | 230 | | with (eg. object files not | | 231 | | implied by 'sources', static | | 232 | | library that must be | | 233 | | explicitly specified, binary | | 234 | | resource files, etc.) | | 235 +------------------------+--------------------------------+---------------------------+ 236 | *extra_compile_args* | any extra platform- and | a list of strings | 237 | | compiler-specific information | | 238 | | to use when compiling the | | 239 | | source files in 'sources'. For | | 240 | | platforms and compilers where | | 241 | | a command line makes sense, | | 242 | | this is typically a list of | | 243 | | command-line arguments, but | | 244 | | for other platforms it could | | 245 | | be anything. | | 246 +------------------------+--------------------------------+---------------------------+ 247 | *extra_link_args* | any extra platform- and | a list of strings | 248 | | compiler-specific information | | 249 | | to use when linking object | | 250 | | files together to create the | | 251 | | extension (or to create a new | | 252 | | static Python interpreter). | | 253 | | Similar interpretation as for | | 254 | | 'extra_compile_args'. | | 255 +------------------------+--------------------------------+---------------------------+ 256 | *export_symbols* | list of symbols to be exported | a list of strings | 257 | | from a shared extension. Not | | 258 | | used on all platforms, and not | | 259 | | generally necessary for Python | | 260 | | extensions, which typically | | 261 | | export exactly one symbol: | | 262 | | ``init`` + extension_name. | | 263 +------------------------+--------------------------------+---------------------------+ 264 | *depends* | list of files that the | a list of strings | 265 | | extension depends on | | 266 +------------------------+--------------------------------+---------------------------+ 267 | *language* | extension language (i.e. | a string | 268 | | ``'c'``, ``'c++'``, | | 269 | | ``'objc'``). Will be detected | | 270 | | from the source extensions if | | 271 | | not provided. | | 272 +------------------------+--------------------------------+---------------------------+ 273 274 275.. class:: Distribution 276 277 A :class:`Distribution` describes how to build, install and package up a Python 278 software package. 279 280 See the :func:`setup` function for a list of keyword arguments accepted by the 281 Distribution constructor. :func:`setup` creates a Distribution instance. 282 283 284.. class:: Command 285 286 A :class:`Command` class (or rather, an instance of one of its subclasses) 287 implement a single distutils command. 288 289 290:mod:`distutils.ccompiler` --- CCompiler base class 291=================================================== 292 293.. module:: distutils.ccompiler 294 :synopsis: Abstract CCompiler class 295 296 297This module provides the abstract base class for the :class:`CCompiler` 298classes. A :class:`CCompiler` instance can be used for all the compile and 299link steps needed to build a single project. Methods are provided to set 300options for the compiler --- macro definitions, include directories, link path, 301libraries and the like. 302 303This module provides the following functions. 304 305 306.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries) 307 308 Generate linker options for searching library directories and linking with 309 specific libraries. *libraries* and *library_dirs* are, respectively, lists of 310 library names (not filenames!) and search directories. Returns a list of 311 command-line options suitable for use with some compiler (depending on the two 312 format strings passed in). 313 314 315.. function:: gen_preprocess_options(macros, include_dirs) 316 317 Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as 318 used by at least two types of compilers: the typical Unix compiler and Visual 319 C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)`` 320 means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define 321 (:option:`!-D`) macro *name* to *value*. *include_dirs* is just a list of 322 directory names to be added to the header file search path (:option:`!-I`). 323 Returns a list of command-line options suitable for either Unix compilers or 324 Visual C++. 325 326 327.. function:: get_default_compiler(osname, platform) 328 329 Determine the default compiler to use for the given platform. 330 331 *osname* should be one of the standard Python OS names (i.e. the ones returned 332 by ``os.name``) and *platform* the common value returned by ``sys.platform`` for 333 the platform in question. 334 335 The default values are ``os.name`` and ``sys.platform`` in case the parameters 336 are not given. 337 338 339.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0) 340 341 Factory function to generate an instance of some CCompiler subclass for the 342 supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg. 343 ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for 344 that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the 345 default compilers are "traditional Unix interface" (:class:`UnixCCompiler` 346 class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly 347 possible to ask for a Unix compiler object under Windows, and a Microsoft 348 compiler object under Unix---if you supply a value for *compiler*, *plat* is 349 ignored. 350 351 .. % Is the posix/nt only thing still true? Mac OS X seems to work, and 352 .. % returns a UnixCCompiler instance. How to document this... hmm. 353 354 355.. function:: show_compilers() 356 357 Print list of available compilers (used by the :option:`!--help-compiler` options 358 to :command:`build`, :command:`build_ext`, :command:`build_clib`). 359 360 361.. class:: CCompiler([verbose=0, dry_run=0, force=0]) 362 363 The abstract base class :class:`CCompiler` defines the interface that must be 364 implemented by real compiler classes. The class also has some utility methods 365 used by several compiler classes. 366 367 The basic idea behind a compiler abstraction class is that each instance can be 368 used for all the compile/link steps in building a single project. Thus, 369 attributes common to all of those compile and link steps --- include 370 directories, macros to define, libraries to link against, etc. --- are 371 attributes of the compiler instance. To allow for variability in how individual 372 files are treated, most of those attributes may be varied on a per-compilation 373 or per-link basis. 374 375 The constructor for each subclass creates an instance of the Compiler object. 376 Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the 377 steps) and *force* (rebuild everything, regardless of dependencies). All of 378 these flags default to ``0`` (off). Note that you probably don't want to 379 instantiate :class:`CCompiler` or one of its subclasses directly - use the 380 :func:`distutils.CCompiler.new_compiler` factory function instead. 381 382 The following methods allow you to manually alter compiler options for the 383 instance of the Compiler class. 384 385 386 .. method:: CCompiler.add_include_dir(dir) 387 388 Add *dir* to the list of directories that will be searched for header files. 389 The compiler is instructed to search directories in the order in which they are 390 supplied by successive calls to :meth:`add_include_dir`. 391 392 393 .. method:: CCompiler.set_include_dirs(dirs) 394 395 Set the list of directories that will be searched to *dirs* (a list of strings). 396 Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to 397 :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`. 398 This does not affect any list of standard include directories that the compiler 399 may search by default. 400 401 402 .. method:: CCompiler.add_library(libname) 403 404 Add *libname* to the list of libraries that will be included in all links driven 405 by this compiler object. Note that *libname* should \*not\* be the name of a 406 file containing a library, but the name of the library itself: the actual 407 filename will be inferred by the linker, the compiler, or the compiler class 408 (depending on the platform). 409 410 The linker will be instructed to link against libraries in the order they were 411 supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly 412 valid to duplicate library names; the linker will be instructed to link against 413 libraries as many times as they are mentioned. 414 415 416 .. method:: CCompiler.set_libraries(libnames) 417 418 Set the list of libraries to be included in all links driven by this compiler 419 object to *libnames* (a list of strings). This does not affect any standard 420 system libraries that the linker may include by default. 421 422 423 .. method:: CCompiler.add_library_dir(dir) 424 425 Add *dir* to the list of directories that will be searched for libraries 426 specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be 427 instructed to search for libraries in the order they are supplied to 428 :meth:`add_library_dir` and/or :meth:`set_library_dirs`. 429 430 431 .. method:: CCompiler.set_library_dirs(dirs) 432 433 Set the list of library search directories to *dirs* (a list of strings). This 434 does not affect any standard library search path that the linker may search by 435 default. 436 437 438 .. method:: CCompiler.add_runtime_library_dir(dir) 439 440 Add *dir* to the list of directories that will be searched for shared libraries 441 at runtime. 442 443 444 .. method:: CCompiler.set_runtime_library_dirs(dirs) 445 446 Set the list of directories to search for shared libraries at runtime to *dirs* 447 (a list of strings). This does not affect any standard search path that the 448 runtime linker may search by default. 449 450 451 .. method:: CCompiler.define_macro(name[, value=None]) 452 453 Define a preprocessor macro for all compilations driven by this compiler object. 454 The optional parameter *value* should be a string; if it is not supplied, then 455 the macro will be defined without an explicit value and the exact outcome 456 depends on the compiler used. 457 458 .. XXX true? does ANSI say anything about this? 459 460 461 .. method:: CCompiler.undefine_macro(name) 462 463 Undefine a preprocessor macro for all compilations driven by this compiler 464 object. If the same macro is defined by :meth:`define_macro` and 465 undefined by :meth:`undefine_macro` the last call takes precedence 466 (including multiple redefinitions or undefinitions). If the macro is 467 redefined/undefined on a per-compilation basis (ie. in the call to 468 :meth:`compile`), then that takes precedence. 469 470 471 .. method:: CCompiler.add_link_object(object) 472 473 Add *object* to the list of object files (or analogues, such as explicitly named 474 library files or the output of "resource compilers") to be included in every 475 link driven by this compiler object. 476 477 478 .. method:: CCompiler.set_link_objects(objects) 479 480 Set the list of object files (or analogues) to be included in every link to 481 *objects*. This does not affect any standard object files that the linker may 482 include by default (such as system libraries). 483 484 The following methods implement methods for autodetection of compiler options, 485 providing some functionality similar to GNU :program:`autoconf`. 486 487 488 .. method:: CCompiler.detect_language(sources) 489 490 Detect the language of a given file, or list of files. Uses the instance 491 attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a 492 list) to do the job. 493 494 495 .. method:: CCompiler.find_library_file(dirs, lib[, debug=0]) 496 497 Search the specified list of directories for a static or shared library file 498 *lib* and return the full path to that file. If *debug* is true, look for a 499 debugging version (if that makes sense on the current platform). Return 500 ``None`` if *lib* wasn't found in any of the specified directories. 501 502 503 .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None]) 504 505 Return a boolean indicating whether *funcname* is supported on the current 506 platform. The optional arguments can be used to augment the compilation 507 environment by providing additional include files and paths and libraries and 508 paths. 509 510 511 .. method:: CCompiler.library_dir_option(dir) 512 513 Return the compiler option to add *dir* to the list of directories searched for 514 libraries. 515 516 517 .. method:: CCompiler.library_option(lib) 518 519 Return the compiler option to add *lib* to the list of libraries linked into the 520 shared library or executable. 521 522 523 .. method:: CCompiler.runtime_library_dir_option(dir) 524 525 Return the compiler option to add *dir* to the list of directories searched for 526 runtime libraries. 527 528 529 .. method:: CCompiler.set_executables(**args) 530 531 Define the executables (and options for them) that will be run to perform the 532 various stages of compilation. The exact set of executables that may be 533 specified here depends on the compiler class (via the 'executables' class 534 attribute), but most will have: 535 536 +--------------+------------------------------------------+ 537 | attribute | description | 538 +==============+==========================================+ 539 | *compiler* | the C/C++ compiler | 540 +--------------+------------------------------------------+ 541 | *linker_so* | linker used to create shared objects and | 542 | | libraries | 543 +--------------+------------------------------------------+ 544 | *linker_exe* | linker used to create binary executables | 545 +--------------+------------------------------------------+ 546 | *archiver* | static library creator | 547 +--------------+------------------------------------------+ 548 549 On platforms with a command-line (Unix, DOS/Windows), each of these is a string 550 that will be split into executable name and (optional) list of arguments. 551 (Splitting the string is done similarly to how Unix shells operate: words are 552 delimited by spaces, but quotes and backslashes can override this. See 553 :func:`distutils.util.split_quoted`.) 554 555 The following methods invoke stages in the build process. 556 557 558 .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None]) 559 560 Compile one or more source files. Generates object files (e.g. transforms a 561 :file:`.c` file to a :file:`.o` file.) 562 563 *sources* must be a list of filenames, most likely C/C++ files, but in reality 564 anything that can be handled by a particular compiler and compiler class (eg. 565 :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of 566 object filenames, one per source filename in *sources*. Depending on the 567 implementation, not all source files will necessarily be compiled, but all 568 corresponding object filenames will be returned. 569 570 If *output_dir* is given, object files will be put under it, while retaining 571 their original path component. That is, :file:`foo/bar.c` normally compiles to 572 :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then 573 it would compile to :file:`build/foo/bar.o`. 574 575 *macros*, if given, must be a list of macro definitions. A macro definition is 576 either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines 577 a macro; if the value is ``None``, the macro is defined without an explicit 578 value. The 1-tuple case undefines a macro. Later 579 definitions/redefinitions/undefinitions take precedence. 580 581 *include_dirs*, if given, must be a list of strings, the directories to add to 582 the default include file search path for this compilation only. 583 584 *debug* is a boolean; if true, the compiler will be instructed to output debug 585 symbols in (or alongside) the object file(s). 586 587 *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms 588 that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most 589 likely lists of strings: extra command-line arguments to prepend/append to the 590 compiler command line. On other platforms, consult the implementation class 591 documentation. In any event, they are intended as an escape hatch for those 592 occasions when the abstract compiler framework doesn't cut the mustard. 593 594 *depends*, if given, is a list of filenames that all targets depend on. If a 595 source file is older than any file in depends, then the source file will be 596 recompiled. This supports dependency tracking, but only at a coarse 597 granularity. 598 599 Raises :exc:`CompileError` on failure. 600 601 602 .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None]) 603 604 Link a bunch of stuff together to create a static library file. The "bunch of 605 stuff" consists of the list of object files supplied as *objects*, the extra 606 object files supplied to :meth:`add_link_object` and/or 607 :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or 608 :meth:`set_libraries`, and the libraries supplied as *libraries* (if any). 609 610 *output_libname* should be a library name, not a filename; the filename will be 611 inferred from the library name. *output_dir* is the directory where the library 612 file will be put. 613 614 .. XXX defaults to what? 615 616 *debug* is a boolean; if true, debugging information will be included in the 617 library (note that on most platforms, it is the compile step where this matters: 618 the *debug* flag is included here just for consistency). 619 620 *target_lang* is the target language for which the given objects are being 621 compiled. This allows specific linkage time treatment of certain languages. 622 623 Raises :exc:`LibError` on failure. 624 625 626 .. 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]) 627 628 Link a bunch of stuff together to create an executable or shared library file. 629 630 The "bunch of stuff" consists of the list of object files supplied as *objects*. 631 *output_filename* should be a filename. If *output_dir* is supplied, 632 *output_filename* is relative to it (i.e. *output_filename* can provide 633 directory components if needed). 634 635 *libraries* is a list of libraries to link against. These are library names, 636 not filenames, since they're translated into filenames in a platform-specific 637 way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on 638 DOS/Windows). However, they can include a directory component, which means the 639 linker will look in that specific directory rather than searching all the normal 640 locations. 641 642 *library_dirs*, if supplied, should be a list of directories to search for 643 libraries that were specified as bare library names (ie. no directory 644 component). These are on top of the system default and those supplied to 645 :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs* 646 is a list of directories that will be embedded into the shared library and used 647 to search for other shared libraries that \*it\* depends on at run-time. (This 648 may only be relevant on Unix.) 649 650 *export_symbols* is a list of symbols that the shared library will export. 651 (This appears to be relevant only on Windows.) 652 653 *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the 654 slight distinction that it actually matters on most platforms (as opposed to 655 :meth:`create_static_lib`, which includes a *debug* flag mostly for form's 656 sake). 657 658 *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of 659 course that they supply command-line arguments for the particular linker being 660 used). 661 662 *target_lang* is the target language for which the given objects are being 663 compiled. This allows specific linkage time treatment of certain languages. 664 665 Raises :exc:`LinkError` on failure. 666 667 668 .. 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]) 669 670 Link an executable. *output_progname* is the name of the file executable, while 671 *objects* are a list of object filenames to link in. Other arguments are as for 672 the :meth:`link` method. 673 674 675 .. 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]) 676 677 Link a shared library. *output_libname* is the name of the output library, 678 while *objects* is a list of object filenames to link in. Other arguments are 679 as for the :meth:`link` method. 680 681 682 .. 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]) 683 684 Link a shared object. *output_filename* is the name of the shared object that 685 will be created, while *objects* is a list of object filenames to link in. 686 Other arguments are as for the :meth:`link` method. 687 688 689 .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None]) 690 691 Preprocess a single C/C++ source file, named in *source*. Output will be written 692 to file named *output_file*, or *stdout* if *output_file* not supplied. 693 *macros* is a list of macro definitions as for :meth:`compile`, which will 694 augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`. 695 *include_dirs* is a list of directory names that will be added to the default 696 list, in the same way as :meth:`add_include_dir`. 697 698 Raises :exc:`PreprocessError` on failure. 699 700 The following utility methods are defined by the :class:`CCompiler` class, for 701 use by the various concrete subclasses. 702 703 704 .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir='']) 705 706 Returns the filename of the executable for the given *basename*. Typically for 707 non-Windows platforms this is the same as the basename, while Windows will get 708 a :file:`.exe` added. 709 710 711 .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir='']) 712 713 Returns the filename for the given library name on the current platform. On Unix 714 a library with *lib_type* of ``'static'`` will typically be of the form 715 :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form 716 :file:`liblibname.so`. 717 718 719 .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir='']) 720 721 Returns the name of the object files for the given source files. 722 *source_filenames* should be a list of filenames. 723 724 725 .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir='']) 726 727 Returns the name of a shared object file for the given file name *basename*. 728 729 730 .. method:: CCompiler.execute(func, args[, msg=None, level=1]) 731 732 Invokes :func:`distutils.util.execute`. This method invokes a Python function 733 *func* with the given arguments *args*, after logging and taking into account 734 the *dry_run* flag. 735 736 737 .. method:: CCompiler.spawn(cmd) 738 739 Invokes :func:`distutils.util.spawn`. This invokes an external process to run 740 the given command. 741 742 743 .. method:: CCompiler.mkpath(name[, mode=511]) 744 745 Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any 746 missing ancestor directories. 747 748 749 .. method:: CCompiler.move_file(src, dst) 750 751 Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. 752 753 754 .. method:: CCompiler.announce(msg[, level=1]) 755 756 Write a message using :func:`distutils.log.debug`. 757 758 759 .. method:: CCompiler.warn(msg) 760 761 Write a warning message *msg* to standard error. 762 763 764 .. method:: CCompiler.debug_print(msg) 765 766 If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to 767 standard output, otherwise do nothing. 768 769.. % \subsection{Compiler-specific modules} 770.. % 771.. % The following modules implement concrete subclasses of the abstract 772.. % \class{CCompiler} class. They should not be instantiated directly, but should 773.. % be created using \function{distutils.ccompiler.new_compiler()} factory 774.. % function. 775 776 777:mod:`distutils.unixccompiler` --- Unix C Compiler 778================================================== 779 780.. module:: distutils.unixccompiler 781 :synopsis: UNIX C Compiler 782 783 784This module provides the :class:`UnixCCompiler` class, a subclass of 785:class:`CCompiler` that handles the typical Unix-style command-line C compiler: 786 787* macros defined with :option:`!-Dname[=value]` 788 789* macros undefined with :option:`!-Uname` 790 791* include search directories specified with :option:`!-Idir` 792 793* libraries specified with :option:`!-llib` 794 795* library search directories specified with :option:`!-Ldir` 796 797* compile handled by :program:`cc` (or similar) executable with :option:`!-c` 798 option: compiles :file:`.c` to :file:`.o` 799 800* link static library handled by :program:`ar` command (possibly with 801 :program:`ranlib`) 802 803* link shared library handled by :program:`cc` :option:`!-shared` 804 805 806:mod:`distutils.msvccompiler` --- Microsoft Compiler 807==================================================== 808 809.. module:: distutils.msvccompiler 810 :synopsis: Microsoft Compiler 811 812 813This module provides :class:`MSVCCompiler`, an implementation of the abstract 814:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension 815modules need to be compiled with the same compiler that was used to compile 816Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python 8172.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium 818binaries are created using the Platform SDK. 819 820:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on 821its own. To override this choice, the environment variables *DISTUTILS_USE_SDK* 822and *MSSdk* must be both set. *MSSdk* indicates that the current environment has 823been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables 824had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates 825that the distutils user has made an explicit choice to override the compiler 826selection by :class:`MSVCCompiler`. 827 828 829:mod:`distutils.bcppcompiler` --- Borland Compiler 830================================================== 831 832.. module:: distutils.bcppcompiler 833 834 835This module provides :class:`BorlandCCompiler`, a subclass of the abstract 836:class:`CCompiler` class for the Borland C++ compiler. 837 838 839:mod:`distutils.cygwincompiler` --- Cygwin Compiler 840=================================================== 841 842.. module:: distutils.cygwinccompiler 843 844 845This module provides the :class:`CygwinCCompiler` class, a subclass of 846:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to 847Windows. It also contains the Mingw32CCompiler class which handles the mingw32 848port of GCC (same as cygwin in no-cygwin mode). 849 850 851:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler 852=================================================== 853 854.. module:: distutils.emxccompiler 855 :synopsis: OS/2 EMX Compiler support 856 857 858This module provides the EMXCCompiler class, a subclass of 859:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2. 860 861 862:mod:`distutils.archive_util` --- Archiving utilities 863====================================================== 864 865.. module:: distutils.archive_util 866 :synopsis: Utility functions for creating archive files (tarballs, zip files, ...) 867 868 869This module provides a few functions for creating archive files, such as 870tarballs or zipfiles. 871 872 873.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0]) 874 875 Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of 876 the file to create, minus any format-specific extension; *format* is the 877 archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is 878 a directory that will be the root directory of the archive; ie. we typically 879 ``chdir`` into *root_dir* before creating the archive. *base_dir* is the 880 directory where we start archiving from; ie. *base_dir* will be the common 881 prefix of all files and directories in the archive. *root_dir* and *base_dir* 882 both default to the current directory. Returns the name of the archive file. 883 884 885.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) 886 887 'Create an (optional compressed) archive as a tar file from all files in and 888 under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``, 889 ``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named 890 by *compress* must be on the default program search path, so this is probably 891 Unix-specific. The output tar file will be named :file:`base_dir.tar`, 892 possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` 893 or :file:`.Z`). Return the output filename. 894 895 896.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) 897 898 Create a zip file from all files in and under *base_dir*. The output zip file 899 will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python 900 module (if available) or the InfoZIP :file:`zip` utility (if installed and 901 found on the default search path). If neither tool is available, raises 902 :exc:`DistutilsExecError`. Returns the name of the output zip file. 903 904 905:mod:`distutils.dep_util` --- Dependency checking 906================================================= 907 908.. module:: distutils.dep_util 909 :synopsis: Utility functions for simple dependency checking 910 911 912This module provides functions for performing simple, timestamp-based 913dependency of files and groups of files; also, functions based entirely on such 914timestamp dependency analysis. 915 916 917.. function:: newer(source, target) 918 919 Return true if *source* exists and is more recently modified than *target*, or 920 if *source* exists and *target* doesn't. Return false if both exist and *target* 921 is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if 922 *source* does not exist. 923 924 925.. function:: newer_pairwise(sources, targets) 926 927 Walk two filename lists in parallel, testing if each source is newer than its 928 corresponding target. Return a pair of lists (*sources*, *targets*) where 929 source is newer than target, according to the semantics of :func:`newer`. 930 931 .. % % equivalent to a listcomp... 932 933 934.. function:: newer_group(sources, target[, missing='error']) 935 936 Return true if *target* is out-of-date with respect to any file listed in 937 *sources* In other words, if *target* exists and is newer than every file in 938 *sources*, return false; otherwise return true. *missing* controls what we do 939 when a source file is missing; the default (``'error'``) is to blow up with an 940 :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently 941 drop any missing source files; if it is ``'newer'``, any missing source files 942 make us assume that *target* is out-of-date (this is handy in "dry-run" mode: 943 it'll make you pretend to carry out commands that wouldn't work because inputs 944 are missing, but that doesn't matter because you're not actually going to run 945 the commands). 946 947 948:mod:`distutils.dir_util` --- Directory tree operations 949======================================================= 950 951.. module:: distutils.dir_util 952 :synopsis: Utility functions for operating on directories and directory trees 953 954 955This module provides functions for operating on directories and trees of 956directories. 957 958 959.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0]) 960 961 Create a directory and any missing ancestor directories. If the directory 962 already exists (or if *name* is the empty string, which means the current 963 directory, which of course exists), then do nothing. Raise 964 :exc:`DistutilsFileError` if unable to create some directory along the way (eg. 965 some sub-path exists, but is a file rather than a directory). If *verbose* is 966 true, print a one-line summary of each mkdir to stdout. Return the list of 967 directories actually created. 968 969 970.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0]) 971 972 Create all the empty directories under *base_dir* needed to put *files* there. 973 *base_dir* is just the name of a directory which doesn't necessarily exist 974 yet; *files* is a list of filenames to be interpreted relative to *base_dir*. 975 *base_dir* + the directory portion of every file in *files* will be created if 976 it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for 977 :func:`mkpath`. 978 979 980.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0]) 981 982 Copy an entire directory tree *src* to a new location *dst*. Both *src* and 983 *dst* must be directory names. If *src* is not a directory, raise 984 :exc:`DistutilsFileError`. If *dst* does not exist, it is created with 985 :func:`mkpath`. The end result of the copy is that every file in *src* is 986 copied to *dst*, and directories under *src* are recursively copied to *dst*. 987 Return the list of files that were copied or might have been copied, using their 988 output name. The return value is unaffected by *update* or *dry_run*: it is 989 simply the list of all files under *src*, with the names changed to be under 990 *dst*. 991 992 *preserve_mode* and *preserve_times* are the same as for 993 :func:`distutils.file_util.copy_file`; note that they only apply to 994 regular files, not to 995 directories. If *preserve_symlinks* is true, symlinks will be copied as 996 symlinks (on platforms that support them!); otherwise (the default), the 997 destination of the symlink will be copied. *update* and *verbose* are the same 998 as for :func:`copy_file`. 999 1000 Files in *src* that begin with :file:`.nfs` are skipped (more information on 1001 these files is available in answer D2 of the `NFS FAQ page 1002 <http://nfs.sourceforge.net/#section_d>`_. 1003 1004 .. versionchanged:: 2.7.4 1005 NFS files are ignored. 1006 1007 1008.. function:: remove_tree(directory[, verbose=0, dry_run=0]) 1009 1010 Recursively remove *directory* and all files and directories underneath it. Any 1011 errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is 1012 true). 1013 1014 1015:mod:`distutils.file_util` --- Single file operations 1016===================================================== 1017 1018.. module:: distutils.file_util 1019 :synopsis: Utility functions for operating on single files 1020 1021 1022This module contains some utility functions for operating on individual files. 1023 1024 1025.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0]) 1026 1027 Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there 1028 with the same name; otherwise, it must be a filename. (If the file exists, it 1029 will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the 1030 file's mode (type and permission bits, or whatever is analogous on the 1031 current platform) is copied. If *preserve_times* is true (the default), the 1032 last-modified and last-access times are copied as well. If *update* is true, 1033 *src* will only be copied if *dst* does not exist, or if *dst* does exist but 1034 is older than *src*. 1035 1036 *link* allows you to make hard links (using :func:`os.link`) or symbolic links 1037 (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or 1038 ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link* 1039 on systems that don't support it: :func:`copy_file` doesn't check if hard or 1040 symbolic linking is available. It uses :func:`_copy_file_contents` to copy file 1041 contents. 1042 1043 Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the 1044 output file, and *copied* is true if the file was copied (or would have been 1045 copied, if *dry_run* true). 1046 1047 .. % XXX if the destination file already exists, we clobber it if 1048 .. % copying, but blow up if linking. Hmmm. And I don't know what 1049 .. % macostools.copyfile() does. Should definitely be consistent, and 1050 .. % should probably blow up if destination exists and we would be 1051 .. % changing it (ie. it's not already a hard/soft link to src OR 1052 .. % (not update) and (src newer than dst)). 1053 1054 1055.. function:: move_file(src, dst[, verbose, dry_run]) 1056 1057 Move file *src* to *dst*. If *dst* is a directory, the file will be moved into 1058 it with the same name; otherwise, *src* is just renamed to *dst*. Returns the 1059 new full name of the file. 1060 1061 .. warning:: 1062 1063 Handles cross-device moves on Unix using :func:`copy_file`. What about 1064 other systems? 1065 1066 1067.. function:: write_file(filename, contents) 1068 1069 Create a file called *filename* and write *contents* (a sequence of strings 1070 without line terminators) to it. 1071 1072 1073:mod:`distutils.util` --- Miscellaneous other utility functions 1074=============================================================== 1075 1076.. module:: distutils.util 1077 :synopsis: Miscellaneous other utility functions 1078 1079 1080This module contains other assorted bits and pieces that don't fit into any 1081other utility module. 1082 1083 1084.. function:: get_platform() 1085 1086 Return a string that identifies the current platform. This is used mainly to 1087 distinguish platform-specific build directories and platform-specific built 1088 distributions. Typically includes the OS name and version and the architecture 1089 (as supplied by 'os.uname()'), although the exact information included depends 1090 on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only 1091 runs on SGI hardware), but for Linux the kernel version isn't particularly 1092 important. 1093 1094 Examples of returned values: 1095 1096 * ``linux-i586`` 1097 * ``linux-alpha`` 1098 * ``solaris-2.6-sun4u`` 1099 * ``irix-5.3`` 1100 * ``irix64-6.2`` 1101 1102 For non-POSIX platforms, currently just returns ``sys.platform``. 1103 1104 For Mac OS X systems the OS version reflects the minimal version on which 1105 binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` 1106 during the build of Python), not the OS version of the current system. 1107 1108 For universal binary builds on Mac OS X the architecture value reflects 1109 the universal binary status instead of the architecture of the current 1110 processor. For 32-bit universal binaries the architecture is ``fat``, 1111 for 64-bit universal binaries the architecture is ``fat64``, and 1112 for 4-way universal binaries the architecture is ``universal``. Starting 1113 from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for 1114 a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for 1115 a universal build with the i386 and x86_64 architectures 1116 1117 Examples of returned values on Mac OS X: 1118 1119 * ``macosx-10.3-ppc`` 1120 1121 * ``macosx-10.3-fat`` 1122 1123 * ``macosx-10.5-universal`` 1124 1125 * ``macosx-10.6-intel`` 1126 1127 1128.. function:: convert_path(pathname) 1129 1130 Return 'pathname' as a name that will work on the native filesystem, i.e. split 1131 it on '/' and put it back together again using the current directory separator. 1132 Needed because filenames in the setup script are always supplied in Unix style, 1133 and have to be converted to the local convention before we can actually use them 1134 in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if 1135 *pathname* either starts or ends with a slash. 1136 1137 1138.. function:: change_root(new_root, pathname) 1139 1140 Return *pathname* with *new_root* prepended. If *pathname* is relative, this is 1141 equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making 1142 *pathname* relative and then joining the two, which is tricky on DOS/Windows. 1143 1144 1145.. function:: check_environ() 1146 1147 Ensure that 'os.environ' has all the environment variables we guarantee that 1148 users can use in config files, command-line options, etc. Currently this 1149 includes: 1150 1151 * :envvar:`HOME` - user's home directory (Unix only) 1152 * :envvar:`PLAT` - description of the current platform, including hardware and 1153 OS (see :func:`get_platform`) 1154 1155 1156.. function:: subst_vars(s, local_vars) 1157 1158 Perform shell/Perl-style variable substitution on *s*. Every occurrence of 1159 ``$`` followed by a name is considered a variable, and variable is substituted 1160 by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's 1161 not in *local_vars*. *os.environ* is first checked/augmented to guarantee that 1162 it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError` 1163 for any variables not found in either *local_vars* or ``os.environ``. 1164 1165 Note that this is not a fully-fledged string interpolation function. A valid 1166 ``$variable`` can consist only of upper and lower case letters, numbers and an 1167 underscore. No { } or ( ) style quoting is available. 1168 1169 1170 1171.. function:: split_quoted(s) 1172 1173 Split a string up according to Unix shell-like rules for quotes and backslashes. 1174 In short: words are delimited by spaces, as long as those spaces are not escaped 1175 by a backslash, or inside a quoted string. Single and double quotes are 1176 equivalent, and the quote characters can be backslash-escaped. The backslash is 1177 stripped from any two-character escape sequence, leaving only the escaped 1178 character. The quote characters are stripped from any quoted string. Returns a 1179 list of words. 1180 1181 .. % Should probably be moved into the standard library. 1182 1183 1184.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0]) 1185 1186 Perform some action that affects the outside world (for instance, writing to the 1187 filesystem). Such actions are special because they are disabled by the 1188 *dry_run* flag. This method takes care of all that bureaucracy for you; all 1189 you have to do is supply the function to call and an argument tuple for it (to 1190 embody the "external action" being performed), and an optional message to print. 1191 1192 1193.. function:: strtobool(val) 1194 1195 Convert a string representation of truth to true (1) or false (0). 1196 1197 True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values 1198 are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises 1199 :exc:`ValueError` if *val* is anything else. 1200 1201 1202.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) 1203 1204 Byte-compile a collection of Python source files to either :file:`.pyc` or 1205 :file:`.pyo` files in the same directory. *py_files* is a list of files to 1206 compile; any files that don't end in :file:`.py` are silently skipped. 1207 *optimize* must be one of the following: 1208 1209 * ``0`` - don't optimize (generate :file:`.pyc`) 1210 * ``1`` - normal optimization (like ``python -O``) 1211 * ``2`` - extra optimization (like ``python -OO``) 1212 1213 If *force* is true, all files are recompiled regardless of timestamps. 1214 1215 The source filename encoded in each :term:`bytecode` file defaults to the filenames 1216 listed in *py_files*; you can modify these with *prefix* and *basedir*. 1217 *prefix* is a string that will be stripped off of each source filename, and 1218 *base_dir* is a directory name that will be prepended (after *prefix* is 1219 stripped). You can supply either or both (or neither) of *prefix* and 1220 *base_dir*, as you wish. 1221 1222 If *dry_run* is true, doesn't actually do anything that would affect the 1223 filesystem. 1224 1225 Byte-compilation is either done directly in this interpreter process with the 1226 standard :mod:`py_compile` module, or indirectly by writing a temporary script 1227 and executing it. Normally, you should let :func:`byte_compile` figure out to 1228 use direct compilation or not (see the source for details). The *direct* flag 1229 is used by the script generated in indirect mode; unless you know what you're 1230 doing, leave it set to ``None``. 1231 1232 1233.. function:: rfc822_escape(header) 1234 1235 Return a version of *header* escaped for inclusion in an :rfc:`822` header, by 1236 ensuring there are 8 spaces space after each newline. Note that it does no other 1237 modification of the string. 1238 1239 .. % this _can_ be replaced 1240 1241.. % \subsection{Distutils objects} 1242 1243 1244:mod:`distutils.dist` --- The Distribution class 1245================================================ 1246 1247.. module:: distutils.dist 1248 :synopsis: Provides the Distribution class, which represents the module distribution being 1249 built/installed/distributed 1250 1251 1252This module provides the :class:`~distutils.core.Distribution` class, which 1253represents the module distribution being built/installed/distributed. 1254 1255 1256:mod:`distutils.extension` --- The Extension class 1257================================================== 1258 1259.. module:: distutils.extension 1260 :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup 1261 scripts 1262 1263 1264This module provides the :class:`Extension` class, used to describe C/C++ 1265extension modules in setup scripts. 1266 1267.. % \subsection{Ungrouped modules} 1268.. % The following haven't been moved into a more appropriate section yet. 1269 1270 1271:mod:`distutils.debug` --- Distutils debug mode 1272=============================================== 1273 1274.. module:: distutils.debug 1275 :synopsis: Provides the debug flag for distutils 1276 1277 1278This module provides the DEBUG flag. 1279 1280 1281:mod:`distutils.errors` --- Distutils exceptions 1282================================================ 1283 1284.. module:: distutils.errors 1285 :synopsis: Provides standard distutils exceptions 1286 1287 1288Provides exceptions used by the Distutils modules. Note that Distutils modules 1289may raise standard exceptions; in particular, SystemExit is usually raised for 1290errors that are obviously the end-user's fault (eg. bad command-line arguments). 1291 1292This module is safe to use in ``from ... import *`` mode; it only exports 1293symbols whose names start with ``Distutils`` and end with ``Error``. 1294 1295 1296:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module 1297=========================================================================== 1298 1299.. module:: distutils.fancy_getopt 1300 :synopsis: Additional getopt functionality 1301 1302 1303This module provides a wrapper around the standard :mod:`getopt` module that 1304provides the following additional features: 1305 1306* short and long options are tied together 1307 1308* options have help strings, so :func:`fancy_getopt` could potentially create a 1309 complete usage summary 1310 1311* options set attributes of a passed-in object 1312 1313* boolean options can have "negative aliases" --- eg. if :option:`!--quiet` is 1314 the "negative alias" of :option:`!--verbose`, then :option:`!--quiet` on the 1315 command line sets *verbose* to false. 1316 1317 1318.. function:: fancy_getopt(options, negative_opt, object, args) 1319 1320 Wrapper function. *options* is a list of ``(long_option, short_option, 1321 help_string)`` 3-tuples as described in the constructor for 1322 :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names 1323 to option names, both the key and value should be in the *options* list. 1324 *object* is an object which will be used to store values (see the :meth:`getopt` 1325 method of the :class:`FancyGetopt` class). *args* is the argument list. Will use 1326 ``sys.argv[1:]`` if you pass ``None`` as *args*. 1327 1328 1329.. function:: wrap_text(text, width) 1330 1331 Wraps *text* to less than *width* wide. 1332 1333 1334 1335.. class:: FancyGetopt([option_table=None]) 1336 1337 The option_table is a list of 3-tuples: ``(long_option, short_option, 1338 help_string)`` 1339 1340 If an option takes an argument, its *long_option* should have ``'='`` appended; 1341 *short_option* should just be a single character, no ``':'`` in any case. 1342 *short_option* should be ``None`` if a *long_option* doesn't have a 1343 corresponding *short_option*. All option tuples must have long options. 1344 1345The :class:`FancyGetopt` class provides the following methods: 1346 1347 1348.. method:: FancyGetopt.getopt([args=None, object=None]) 1349 1350 Parse command-line options in args. Store as attributes on *object*. 1351 1352 If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is 1353 ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores 1354 option values there, and returns a tuple ``(args, object)``. If *object* is 1355 supplied, it is modified in place and :func:`getopt` just returns *args*; in 1356 both cases, the returned *args* is a modified copy of the passed-in *args* list, 1357 which is left untouched. 1358 1359 .. % and args returned are? 1360 1361 1362.. method:: FancyGetopt.get_option_order() 1363 1364 Returns the list of ``(option, value)`` tuples processed by the previous run of 1365 :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called 1366 yet. 1367 1368 1369.. method:: FancyGetopt.generate_help([header=None]) 1370 1371 Generate help text (a list of strings, one per suggested line of output) from 1372 the option table for this :class:`FancyGetopt` object. 1373 1374 If supplied, prints the supplied *header* at the top of the help. 1375 1376 1377:mod:`distutils.filelist` --- The FileList class 1378================================================ 1379 1380.. module:: distutils.filelist 1381 :synopsis: The FileList class, used for poking about the file system and 1382 building lists of files. 1383 1384 1385This module provides the :class:`FileList` class, used for poking about the 1386filesystem and building lists of files. 1387 1388 1389:mod:`distutils.log` --- Simple PEP 282-style logging 1390===================================================== 1391 1392.. module:: distutils.log 1393 :synopsis: A simple logging mechanism, 282-style 1394 1395 1396:mod:`distutils.spawn` --- Spawn a sub-process 1397============================================== 1398 1399.. module:: distutils.spawn 1400 :synopsis: Provides the spawn() function 1401 1402 1403This module provides the :func:`spawn` function, a front-end to various 1404platform-specific functions for launching another program in a sub-process. 1405Also provides :func:`find_executable` to search the path for a given executable 1406name. 1407 1408 1409:mod:`distutils.sysconfig` --- System configuration information 1410=============================================================== 1411 1412.. module:: distutils.sysconfig 1413 :synopsis: Low-level access to configuration information of the Python interpreter. 1414.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 1415.. moduleauthor:: Greg Ward <gward@python.net> 1416.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 1417 1418 1419The :mod:`distutils.sysconfig` module provides access to Python's low-level 1420configuration information. The specific configuration variables available 1421depend heavily on the platform and configuration. The specific variables depend 1422on the build process for the specific version of Python being run; the variables 1423are those found in the :file:`Makefile` and configuration header that are 1424installed with Python on Unix systems. The configuration header is called 1425:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` 1426for earlier versions of Python. 1427 1428Some additional functions are provided which perform some useful manipulations 1429for other parts of the :mod:`distutils` package. 1430 1431 1432.. data:: PREFIX 1433 1434 The result of ``os.path.normpath(sys.prefix)``. 1435 1436 1437.. data:: EXEC_PREFIX 1438 1439 The result of ``os.path.normpath(sys.exec_prefix)``. 1440 1441 1442.. function:: get_config_var(name) 1443 1444 Return the value of a single variable. This is equivalent to 1445 ``get_config_vars().get(name)``. 1446 1447 1448.. function:: get_config_vars(...) 1449 1450 Return a set of variable definitions. If there are no arguments, this returns a 1451 dictionary mapping names of configuration variables to values. If arguments are 1452 provided, they should be strings, and the return value will be a sequence giving 1453 the associated values. If a given name does not have a corresponding value, 1454 ``None`` will be included for that variable. 1455 1456 1457.. function:: get_config_h_filename() 1458 1459 Return the full path name of the configuration header. For Unix, this will be 1460 the header generated by the :program:`configure` script; for other platforms the 1461 header will have been supplied directly by the Python source distribution. The 1462 file is a platform-specific text file. 1463 1464 1465.. function:: get_makefile_filename() 1466 1467 Return the full path name of the :file:`Makefile` used to build Python. For 1468 Unix, this will be a file generated by the :program:`configure` script; the 1469 meaning for other platforms will vary. The file is a platform-specific text 1470 file, if it exists. This function is only useful on POSIX platforms. 1471 1472 1473.. function:: get_python_inc([plat_specific[, prefix]]) 1474 1475 Return the directory for either the general or platform-dependent C include 1476 files. If *plat_specific* is true, the platform-dependent include directory is 1477 returned; if false or omitted, the platform-independent directory is returned. 1478 If *prefix* is given, it is used as either the prefix instead of 1479 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if 1480 *plat_specific* is true. 1481 1482 1483.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) 1484 1485 Return the directory for either the general or platform-dependent library 1486 installation. If *plat_specific* is true, the platform-dependent include 1487 directory is returned; if false or omitted, the platform-independent directory 1488 is returned. If *prefix* is given, it is used as either the prefix instead of 1489 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if 1490 *plat_specific* is true. If *standard_lib* is true, the directory for the 1491 standard library is returned rather than the directory for the installation of 1492 third-party extensions. 1493 1494The following function is only intended for use within the :mod:`distutils` 1495package. 1496 1497 1498.. function:: customize_compiler(compiler) 1499 1500 Do any platform-specific customization of a 1501 :class:`distutils.ccompiler.CCompiler` instance. 1502 1503 This function is only needed on Unix at this time, but should be called 1504 consistently to support forward-compatibility. It inserts the information that 1505 varies across Unix flavors and is stored in Python's :file:`Makefile`. This 1506 information includes the selected compiler, compiler and linker options, and the 1507 extension used by the linker for shared objects. 1508 1509This function is even more special-purpose, and should only be used from 1510Python's own build procedures. 1511 1512 1513.. function:: set_python_build() 1514 1515 Inform the :mod:`distutils.sysconfig` module that it is being used as part of 1516 the build process for Python. This changes a lot of relative locations for 1517 files, allowing them to be located in the build area rather than in an installed 1518 Python. 1519 1520 1521:mod:`distutils.text_file` --- The TextFile class 1522================================================= 1523 1524.. module:: distutils.text_file 1525 :synopsis: provides the TextFile class, a simple interface to text files 1526 1527 1528This module provides the :class:`TextFile` class, which gives an interface to 1529text files that (optionally) takes care of stripping comments, ignoring blank 1530lines, and joining lines with backslashes. 1531 1532 1533.. class:: TextFile([filename=None, file=None, **options]) 1534 1535 This class provides a file-like object that takes care of all the things you 1536 commonly want to do when processing a text file that has some line-by-line 1537 syntax: strip comments (as long as ``#`` is your comment character), skip blank 1538 lines, join adjacent lines by escaping the newline (ie. backslash at end of 1539 line), strip leading and/or trailing whitespace. All of these are optional and 1540 independently controllable. 1541 1542 The class provides a :meth:`warn` method so you can generate warning messages 1543 that report physical line number, even if the logical line in question spans 1544 multiple physical lines. Also provides :meth:`unreadline` for implementing 1545 line-at-a-time lookahead. 1546 1547 :class:`TextFile` instances are create with either *filename*, *file*, or both. 1548 :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a 1549 string, and *file* a file object (or something that provides :meth:`readline` 1550 and :meth:`close` methods). It is recommended that you supply at least 1551 *filename*, so that :class:`TextFile` can include it in warning messages. If 1552 *file* is not supplied, :class:`TextFile` creates its own using the 1553 :func:`open` built-in function. 1554 1555 The options are all boolean, and affect the values returned by :meth:`readline` 1556 1557 .. tabularcolumns:: |l|L|l| 1558 1559 +------------------+--------------------------------+---------+ 1560 | option name | description | default | 1561 +==================+================================+=========+ 1562 | *strip_comments* | strip from ``'#'`` to end-of- | true | 1563 | | line, as well as any | | 1564 | | whitespace leading up to the | | 1565 | | ``'#'``\ ---unless it is | | 1566 | | escaped by a backslash | | 1567 +------------------+--------------------------------+---------+ 1568 | *lstrip_ws* | strip leading whitespace from | false | 1569 | | each line before returning it | | 1570 +------------------+--------------------------------+---------+ 1571 | *rstrip_ws* | strip trailing whitespace | true | 1572 | | (including line terminator!) | | 1573 | | from each line before | | 1574 | | returning it. | | 1575 +------------------+--------------------------------+---------+ 1576 | *skip_blanks* | skip lines that are empty | true | 1577 | | \*after\* stripping comments | | 1578 | | and whitespace. (If both | | 1579 | | lstrip_ws and rstrip_ws are | | 1580 | | false, then some lines may | | 1581 | | consist of solely whitespace: | | 1582 | | these will \*not\* be skipped, | | 1583 | | even if *skip_blanks* is | | 1584 | | true.) | | 1585 +------------------+--------------------------------+---------+ 1586 | *join_lines* | if a backslash is the last | false | 1587 | | non-newline character on a | | 1588 | | line after stripping comments | | 1589 | | and whitespace, join the | | 1590 | | following line to it to form | | 1591 | | one logical line; if N | | 1592 | | consecutive lines end with a | | 1593 | | backslash, then N+1 physical | | 1594 | | lines will be joined to form | | 1595 | | one logical line. | | 1596 +------------------+--------------------------------+---------+ 1597 | *collapse_join* | strip leading whitespace from | false | 1598 | | lines that are joined to their | | 1599 | | predecessor; only matters if | | 1600 | | ``(join_lines and not | | 1601 | | lstrip_ws)`` | | 1602 +------------------+--------------------------------+---------+ 1603 1604 Note that since *rstrip_ws* can strip the trailing newline, the semantics of 1605 :meth:`readline` must differ from those of the built-in file object's 1606 :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for 1607 end-of-file: an empty string might just be a blank line (or an all-whitespace 1608 line), if *rstrip_ws* is true but *skip_blanks* is not. 1609 1610 1611 .. method:: TextFile.open(filename) 1612 1613 Open a new file *filename*. This overrides any *file* or *filename* 1614 constructor arguments. 1615 1616 1617 .. method:: TextFile.close() 1618 1619 Close the current file and forget everything we know about it (including the 1620 filename and the current line number). 1621 1622 1623 .. method:: TextFile.warn(msg[,line=None]) 1624 1625 Print (to stderr) a warning message tied to the current logical line in the 1626 current file. If the current logical line in the file spans multiple physical 1627 lines, the warning refers to the whole range, such as ``"lines 3-5"``. If 1628 *line* is supplied, it overrides the current line number; it may be a list or 1629 tuple to indicate a range of physical lines, or an integer for a single 1630 physical line. 1631 1632 1633 .. method:: TextFile.readline() 1634 1635 Read and return a single logical line from the current file (or from an internal 1636 buffer if lines have previously been "unread" with :meth:`unreadline`). If the 1637 *join_lines* option is true, this may involve reading multiple physical lines 1638 concatenated into a single string. Updates the current line number, so calling 1639 :meth:`warn` after :meth:`readline` emits a warning about the physical line(s) 1640 just read. Returns ``None`` on end-of-file, since the empty string can occur 1641 if *rstrip_ws* is true but *strip_blanks* is not. 1642 1643 1644 .. method:: TextFile.readlines() 1645 1646 Read and return the list of all logical lines remaining in the current file. 1647 This updates the current line number to the last line of the file. 1648 1649 1650 .. method:: TextFile.unreadline(line) 1651 1652 Push *line* (a string) onto an internal buffer that will be checked by future 1653 :meth:`readline` calls. Handy for implementing a parser with line-at-a-time 1654 lookahead. Note that lines that are "unread" with :meth:`unreadline` are not 1655 subsequently re-cleansed (whitespace stripped, or whatever) when read with 1656 :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call 1657 to :meth:`readline`, the lines will be returned most in most recent first order. 1658 1659 1660:mod:`distutils.version` --- Version number classes 1661=================================================== 1662 1663.. module:: distutils.version 1664 :synopsis: implements classes that represent module version numbers. 1665 1666 1667.. % todo 1668.. % \section{Distutils Commands} 1669.. % 1670.. % This part of Distutils implements the various Distutils commands, such 1671.. % as \code{build}, \code{install} \&c. Each command is implemented as a 1672.. % separate module, with the command name as the name of the module. 1673 1674 1675:mod:`distutils.cmd` --- Abstract base class for Distutils commands 1676=================================================================== 1677 1678.. module:: distutils.cmd 1679 :synopsis: This module provides the abstract base class Command. This class 1680 is subclassed by the modules in the distutils.command subpackage. 1681 1682 1683This module supplies the abstract base class :class:`Command`. 1684 1685 1686.. class:: Command(dist) 1687 1688 Abstract base class for defining command classes, the "worker bees" of the 1689 Distutils. A useful analogy for command classes is to think of them as 1690 subroutines with local variables called *options*. The options are declared 1691 in :meth:`initialize_options` and defined (given their final values) in 1692 :meth:`finalize_options`, both of which must be defined by every command 1693 class. The distinction between the two is necessary because option values 1694 might come from the outside world (command line, config file, ...), and any 1695 options dependent on other options must be computed after these outside 1696 influences have been processed --- hence :meth:`finalize_options`. The body 1697 of the subroutine, where it does all its work based on the values of its 1698 options, is the :meth:`run` method, which must also be implemented by every 1699 command class. 1700 1701 The class constructor takes a single argument *dist*, a 1702 :class:`~distutils.core.Distribution` instance. 1703 1704 1705Creating a new Distutils command 1706================================ 1707 1708This section outlines the steps to create a new Distutils command. 1709 1710A new command lives in a module in the :mod:`distutils.command` package. There 1711is a sample template in that directory called :file:`command_template`. Copy 1712this file to a new module with the same name as the new command you're 1713implementing. This module should implement a class with the same name as the 1714module (and the command). So, for instance, to create the command 1715``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy 1716:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit 1717it so that it's implementing the class :class:`peel_banana`, a subclass of 1718:class:`distutils.cmd.Command`. 1719 1720Subclasses of :class:`Command` must define the following methods. 1721 1722.. method:: Command.initialize_options() 1723 1724 Set default values for all the options that this command supports. Note that 1725 these defaults may be overridden by other commands, by the setup script, by 1726 config files, or by the command-line. Thus, this is not the place to code 1727 dependencies between options; generally, :meth:`initialize_options` 1728 implementations are just a bunch of ``self.foo = None`` assignments. 1729 1730 1731.. method:: Command.finalize_options() 1732 1733 Set final values for all the options that this command supports. This is 1734 always called as late as possible, ie. after any option assignments from the 1735 command-line or from other commands have been done. Thus, this is the place 1736 to code option dependencies: if *foo* depends on *bar*, then it is safe to 1737 set *foo* from *bar* as long as *foo* still has the same value it was 1738 assigned in :meth:`initialize_options`. 1739 1740 1741.. method:: Command.run() 1742 1743 A command's raison d'etre: carry out the action it exists to perform, controlled 1744 by the options initialized in :meth:`initialize_options`, customized by other 1745 commands, the setup script, the command-line, and config files, and finalized in 1746 :meth:`finalize_options`. All terminal output and filesystem interaction should 1747 be done by :meth:`run`. 1748 1749 1750.. attribute:: Command.sub_commands 1751 1752 *sub_commands* formalizes the notion of a "family" of commands, 1753 e.g. ``install`` as the parent with sub-commands ``install_lib``, 1754 ``install_headers``, etc. The parent of a family of commands defines 1755 *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, 1756 predicate)``, with *command_name* a string and *predicate* a function, a 1757 string or ``None``. *predicate* is a method of the parent command that 1758 determines whether the corresponding command is applicable in the current 1759 situation. (E.g. ``install_headers`` is only applicable if we have any C 1760 header files to install.) If *predicate* is ``None``, that command is always 1761 applicable. 1762 1763 *sub_commands* is usually defined at the *end* of a class, because 1764 predicates can be methods of the class, so they must already have been 1765 defined. The canonical example is the :command:`install` command. 1766 1767 1768:mod:`distutils.command` --- Individual Distutils commands 1769========================================================== 1770 1771.. module:: distutils.command 1772 :synopsis: This subpackage contains one module for each standard Distutils command. 1773 1774 1775.. % \subsubsection{Individual Distutils commands} 1776.. % todo 1777 1778 1779:mod:`distutils.command.bdist` --- Build a binary installer 1780=========================================================== 1781 1782.. module:: distutils.command.bdist 1783 :synopsis: Build a binary installer for a package 1784 1785 1786.. % todo 1787 1788 1789:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers 1790============================================================================= 1791 1792.. module:: distutils.command.bdist_packager 1793 :synopsis: Abstract base class for packagers 1794 1795 1796.. % todo 1797 1798 1799:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer 1800================================================================ 1801 1802.. module:: distutils.command.bdist_dumb 1803 :synopsis: Build a "dumb" installer - a simple archive of files 1804 1805 1806.. % todo 1807 1808 1809:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package 1810================================================================================= 1811 1812.. module:: distutils.command.bdist_msi 1813 :synopsis: Build a binary distribution as a Windows MSI file 1814 1815.. class:: bdist_msi 1816 1817 Builds a `Windows Installer`_ (.msi) binary package. 1818 1819 .. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx 1820 1821 In most cases, the ``bdist_msi`` installer is a better choice than the 1822 ``bdist_wininst`` installer, because it provides better support for 1823 Win64 platforms, allows administrators to perform non-interactive 1824 installations, and allows installation through group policies. 1825 1826 1827:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM 1828=========================================================================================== 1829 1830.. module:: distutils.command.bdist_rpm 1831 :synopsis: Build a binary distribution as a Redhat RPM and SRPM 1832 1833 1834.. % todo 1835 1836 1837:mod:`distutils.command.bdist_wininst` --- Build a Windows installer 1838==================================================================== 1839 1840.. module:: distutils.command.bdist_wininst 1841 :synopsis: Build a Windows installer 1842 1843 1844.. % todo 1845 1846 1847:mod:`distutils.command.sdist` --- Build a source distribution 1848============================================================== 1849 1850.. module:: distutils.command.sdist 1851 :synopsis: Build a source distribution 1852 1853 1854.. % todo 1855 1856 1857:mod:`distutils.command.build` --- Build all files of a package 1858=============================================================== 1859 1860.. module:: distutils.command.build 1861 :synopsis: Build all files of a package 1862 1863 1864.. % todo 1865 1866 1867:mod:`distutils.command.build_clib` --- Build any C libraries in a package 1868========================================================================== 1869 1870.. module:: distutils.command.build_clib 1871 :synopsis: Build any C libraries in a package 1872 1873 1874.. % todo 1875 1876 1877:mod:`distutils.command.build_ext` --- Build any extensions in a package 1878======================================================================== 1879 1880.. module:: distutils.command.build_ext 1881 :synopsis: Build any extensions in a package 1882 1883 1884.. % todo 1885 1886 1887:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package 1888=========================================================================== 1889 1890.. module:: distutils.command.build_py 1891 :synopsis: Build the .py/.pyc files of a package 1892 1893 1894:mod:`distutils.command.build_scripts` --- Build the scripts of a package 1895========================================================================= 1896 1897.. module:: distutils.command.build_scripts 1898 :synopsis: Build the scripts of a package 1899 1900 1901.. % todo 1902 1903 1904:mod:`distutils.command.clean` --- Clean a package build area 1905============================================================= 1906 1907.. module:: distutils.command.clean 1908 :synopsis: Clean a package build area 1909 1910This command removes the temporary files created by :command:`build` 1911and its subcommands, like intermediary compiled object files. With 1912the ``--all`` option, the complete build directory will be removed. 1913 1914Extension modules built :ref:`in place <distutils-build-ext-inplace>` 1915will not be cleaned, as they are not in the build directory. 1916 1917 1918:mod:`distutils.command.config` --- Perform package configuration 1919================================================================= 1920 1921.. module:: distutils.command.config 1922 :synopsis: Perform package configuration 1923 1924 1925.. % todo 1926 1927 1928:mod:`distutils.command.install` --- Install a package 1929====================================================== 1930 1931.. module:: distutils.command.install 1932 :synopsis: Install a package 1933 1934 1935.. % todo 1936 1937 1938:mod:`distutils.command.install_data` --- Install data files from a package 1939=========================================================================== 1940 1941.. module:: distutils.command.install_data 1942 :synopsis: Install data files from a package 1943 1944 1945.. % todo 1946 1947 1948:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package 1949====================================================================================== 1950 1951.. module:: distutils.command.install_headers 1952 :synopsis: Install C/C++ header files from a package 1953 1954 1955.. % todo 1956 1957 1958:mod:`distutils.command.install_lib` --- Install library files from a package 1959============================================================================= 1960 1961.. module:: distutils.command.install_lib 1962 :synopsis: Install library files from a package 1963 1964 1965.. % todo 1966 1967 1968:mod:`distutils.command.install_scripts` --- Install script files from a package 1969================================================================================ 1970 1971.. module:: distutils.command.install_scripts 1972 :synopsis: Install script files from a package 1973 1974 1975.. % todo 1976 1977 1978:mod:`distutils.command.register` --- Register a module with the Python Package Index 1979===================================================================================== 1980 1981.. module:: distutils.command.register 1982 :synopsis: Register a module with the Python Package Index 1983 1984 1985The ``register`` command registers the package with the Python Package Index. 1986This is described in more detail in :pep:`301`. 1987 1988.. % todo 1989 1990 1991:mod:`distutils.command.check` --- Check the meta-data of a package 1992=================================================================== 1993 1994.. module:: distutils.command.check 1995 :synopsis: Check the metadata of a package 1996 1997 1998The ``check`` command performs some tests on the meta-data of a package. 1999For example, it verifies that all required meta-data are provided as 2000the arguments passed to the :func:`setup` function. 2001 2002.. % todo 2003