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