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