rest25/distutils/apiref.rst => rest262/distutils/apiref.rst
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
n29-   +--------------------+--------------------------------+------------------------------------------------------------------+
n29+   +--------------------+--------------------------------+-------------------------------------------------------------+
30-   | argument name      | value                          | type                                                             |
30+   | argument name      | value                          | type                                                        |
31-   +====================+================================+==================================================================+
31+   +====================+================================+=============================================================+
32-   | *name*             | The name of the package        | a string                                                         |
32+   | *name*             | The name of the package        | a string                                                    |
33-   +--------------------+--------------------------------+------------------------------------------------------------------+
33+   +--------------------+--------------------------------+-------------------------------------------------------------+
34-   | *version*          | The version number of the      | See :mod:`distutils.version`                                     |
34+   | *version*          | The version number of the      | See :mod:`distutils.version`                                |
35-   |                    | package                        |                                                                  |
35+   |                    | package                        |                                                             |
36-   +--------------------+--------------------------------+------------------------------------------------------------------+
36+   +--------------------+--------------------------------+-------------------------------------------------------------+
37-   | *description*      | A single line describing the   | a string                                                         |
37+   | *description*      | A single line describing the   | a string                                                    |
38-   |                    | package                        |                                                                  |
38+   |                    | package                        |                                                             |
39-   +--------------------+--------------------------------+------------------------------------------------------------------+
39+   +--------------------+--------------------------------+-------------------------------------------------------------+
40-   | *long_description* | Longer description of the      | a string                                                         |
40+   | *long_description* | Longer description of the      | a string                                                    |
41-   |                    | package                        |                                                                  |
41+   |                    | package                        |                                                             |
42-   +--------------------+--------------------------------+------------------------------------------------------------------+
42+   +--------------------+--------------------------------+-------------------------------------------------------------+
43-   | *author*           | The name of the package author | a string                                                         |
43+   | *author*           | The name of the package author | a string                                                    |
44-   +--------------------+--------------------------------+------------------------------------------------------------------+
44+   +--------------------+--------------------------------+-------------------------------------------------------------+
45-   | *author_email*     | The email address of the       | a string                                                         |
45+   | *author_email*     | The email address of the       | a string                                                    |
46-   |                    | package author                 |                                                                  |
46+   |                    | package author                 |                                                             |
47-   +--------------------+--------------------------------+------------------------------------------------------------------+
47+   +--------------------+--------------------------------+-------------------------------------------------------------+
48-   | *maintainer*       | The name of the current        | a string                                                         |
48+   | *maintainer*       | The name of the current        | a string                                                    |
49-   |                    | maintainer, if different from  |                                                                  |
49+   |                    | maintainer, if different from  |                                                             |
50-   |                    | the author                     |                                                                  |
50+   |                    | the author                     |                                                             |
51-   +--------------------+--------------------------------+------------------------------------------------------------------+
51+   +--------------------+--------------------------------+-------------------------------------------------------------+
52-   | *maintainer_email* | The email address of the       |                                                                  |
52+   | *maintainer_email* | The email address of the       |                                                             |
53-   |                    | current maintainer, if         |                                                                  |
53+   |                    | current maintainer, if         |                                                             |
54-   |                    | different from the author      |                                                                  |
54+   |                    | different from the author      |                                                             |
55-   +--------------------+--------------------------------+------------------------------------------------------------------+
55+   +--------------------+--------------------------------+-------------------------------------------------------------+
56-   | *url*              | A URL for the package          | a URL                                                            |
56+   | *url*              | A URL for the package          | a URL                                                       |
57-   |                    | (homepage)                     |                                                                  |
57+   |                    | (homepage)                     |                                                             |
58-   +--------------------+--------------------------------+------------------------------------------------------------------+
58+   +--------------------+--------------------------------+-------------------------------------------------------------+
59-   | *download_url*     | A URL to download the package  | a URL                                                            |
59+   | *download_url*     | A URL to download the package  | a URL                                                       |
60-   +--------------------+--------------------------------+------------------------------------------------------------------+
60+   +--------------------+--------------------------------+-------------------------------------------------------------+
61-   | *packages*         | A list of Python packages that | a list of strings                                                |
61+   | *packages*         | A list of Python packages that | a list of strings                                           |
62-   |                    | distutils will manipulate      |                                                                  |
62+   |                    | distutils will manipulate      |                                                             |
63-   +--------------------+--------------------------------+------------------------------------------------------------------+
63+   +--------------------+--------------------------------+-------------------------------------------------------------+
64-   | *py_modules*       | A list of Python modules that  | a list of strings                                                |
64+   | *py_modules*       | A list of Python modules that  | a list of strings                                           |
65-   |                    | distutils will manipulate      |                                                                  |
65+   |                    | distutils will manipulate      |                                                             |
66-   +--------------------+--------------------------------+------------------------------------------------------------------+
66+   +--------------------+--------------------------------+-------------------------------------------------------------+
67-   | *scripts*          | A list of standalone script    | a list of strings                                                |
67+   | *scripts*          | A list of standalone script    | a list of strings                                           |
68-   |                    | files to be built and          |                                                                  |
68+   |                    | files to be built and          |                                                             |
69-   |                    | installed                      |                                                                  |
69+   |                    | installed                      |                                                             |
70-   +--------------------+--------------------------------+------------------------------------------------------------------+
70+   +--------------------+--------------------------------+-------------------------------------------------------------+
71-   | *ext_modules*      | A list of Python extensions to | A list of  instances of                                          |
71+   | *ext_modules*      | A list of Python extensions to | A list of  instances of                                     |
72-   |                    | be built                       | :class:`distutils.core.Extension`                                |
72+   |                    | be built                       | :class:`distutils.core.Extension`                           |
73-   +--------------------+--------------------------------+------------------------------------------------------------------+
73+   +--------------------+--------------------------------+-------------------------------------------------------------+
74-   | *classifiers*      | A list of categories for the   | The list of available                                            |
74+   | *classifiers*      | A list of categories for the   | The list of available                                       |
75-   |                    | package                        | categorizations is at                                            |
75+   |                    | package                        | categorizations is at                                       |
76-   |                    |                                | `<http://cheeseshop.python.org/pypi?:action=list_classifiers>`_. |
76+   |                    |                                | http://pypi.python.org/pypi?:action=list_classifiers.       |
77-   +--------------------+--------------------------------+------------------------------------------------------------------+
77+   +--------------------+--------------------------------+-------------------------------------------------------------+
78-   | *distclass*        | the :class:`Distribution`      | A subclass of                                                    |
78+   | *distclass*        | the :class:`Distribution`      | A subclass of                                               |
79-   |                    | class to use                   | :class:`distutils.core.Distribution`                             |
79+   |                    | class to use                   | :class:`distutils.core.Distribution`                        |
80-   +--------------------+--------------------------------+------------------------------------------------------------------+
80+   +--------------------+--------------------------------+-------------------------------------------------------------+
81-   | *script_name*      | The name of the setup.py       | a string                                                         |
81+   | *script_name*      | The name of the setup.py       | a string                                                    |
82-   |                    | script - defaults to           |                                                                  |
82+   |                    | script - defaults to           |                                                             |
83-   |                    | ``sys.argv[0]``                |                                                                  |
83+   |                    | ``sys.argv[0]``                |                                                             |
84-   +--------------------+--------------------------------+------------------------------------------------------------------+
84+   +--------------------+--------------------------------+-------------------------------------------------------------+
85-   | *script_args*      | Arguments to supply to the     | a list of strings                                                |
85+   | *script_args*      | Arguments to supply to the     | a list of strings                                           |
86-   |                    | setup script                   |                                                                  |
86+   |                    | setup script                   |                                                             |
87-   +--------------------+--------------------------------+------------------------------------------------------------------+
87+   +--------------------+--------------------------------+-------------------------------------------------------------+
88-   | *options*          | default options for the setup  | a string                                                         |
88+   | *options*          | default options for the setup  | a string                                                    |
89-   |                    | script                         |                                                                  |
89+   |                    | script                         |                                                             |
90-   +--------------------+--------------------------------+------------------------------------------------------------------+
90+   +--------------------+--------------------------------+-------------------------------------------------------------+
91-   | *license*          | The license for the package    |                                                                  |
91+   | *license*          | The license for the package    | a string                                                    |
92-   +--------------------+--------------------------------+------------------------------------------------------------------+
92+   +--------------------+--------------------------------+-------------------------------------------------------------+
93-   | *keywords*         | Descriptive meta-data. See     |                                                                  |
93+   | *keywords*         | Descriptive meta-data, see     |                                                             |
94-   |                    | :pep:`314`                     |                                                                  |
94+   |                    | :pep:`314`                     |                                                             |
95-   +--------------------+--------------------------------+------------------------------------------------------------------+
95+   +--------------------+--------------------------------+-------------------------------------------------------------+
96-   | *platforms*        |                                |                                                                  |
96+   | *platforms*        |                                |                                                             |
97-   +--------------------+--------------------------------+------------------------------------------------------------------+
97+   +--------------------+--------------------------------+-------------------------------------------------------------+
98-   | *cmdclass*         | A mapping of command names to  | a dictionary                                                     |
98+   | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
99-   |                    | :class:`Command` subclasses    |                                                                  |
99+   |                    | :class:`Command` subclasses    |                                                             |
100-   +--------------------+--------------------------------+------------------------------------------------------------------+
100+   +--------------------+--------------------------------+-------------------------------------------------------------+
101+   | *data_files*       | A list of data files to        | a list                                                      |
102+   |                    | install                        |                                                             |
103+   +--------------------+--------------------------------+-------------------------------------------------------------+
104+   | *package_dir*      | A mapping of package to        | a dictionary                                                |
105+   |                    | directory names                |                                                             |
106+   +--------------------+--------------------------------+-------------------------------------------------------------+
101
n102-   The list of available categorizations is at
103-   `<http://cheeseshop.python.org/pypi?:action=list_classifiers>`_.
104
105
n106-.. function:: run_setup(script_name[, script_args=``None``, stop_after=``'run'``])
n110+.. function:: run_setup(script_name[, script_args=None, stop_after='run'])
107
108   Run a setup script in a somewhat controlled environment, and return  the
109   :class:`distutils.dist.Distribution` instance that drives things.   This is
110   useful if you need to find out the distribution meta-data  (passed as keyword
111   args from *script* to :func:`setup`), or  the contents of the config files or
112   command-line.
113
114   *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]``
179   |                        | :command:`build_ext` command   |                           |
180   |                        | as source for a Python         |                           |
181   |                        | extension.                     |                           |
182   +------------------------+--------------------------------+---------------------------+
183   | *include_dirs*         | list of directories to search  | string                    |
184   |                        | for C/C++ header files (in     |                           |
185   |                        | Unix form for portability)     |                           |
186   +------------------------+--------------------------------+---------------------------+
n187-   | *define_macros*        | list of macros to define; each | (string,string)  tuple or |
n191+   | *define_macros*        | list of macros to define; each | (string, string) tuple or |
188-   |                        | macro is defined using a       | (name,``None``)           |
192+   |                        | macro is defined using a       | (name, ``None``)          |
193+   |                        | 2-tuple ``(name, value)``,     |                           |
189-   |                        | 2-tuple, where 'value' is      |                           |
194+   |                        | where *value* is               |                           |
190   |                        | either the string to define it |                           |
191   |                        | to or ``None`` to define it    |                           |
192   |                        | without a particular value     |                           |
193   |                        | (equivalent of ``#define FOO`` |                           |
194   |                        | in source or :option:`-DFOO`   |                           |
195   |                        | on Unix C compiler command     |                           |
196   |                        | line)                          |                           |
197   +------------------------+--------------------------------+---------------------------+
324
325.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
326
327   Factory function to generate an instance of some CCompiler subclass for the
328   supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
329   ``'posix'``, ``'nt'``), and *compiler*  defaults to the default compiler for
330   that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
331   default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
n332-   class) and Visual C++(:class:`MSVCCompiler` class).  Note that it's perfectly
n337+   class) and Visual C++ (:class:`MSVCCompiler` class).  Note that it's perfectly
333   possible to ask for a Unix compiler object under Windows, and a Microsoft
334   compiler object under Unix---if you supply a value for *compiler*, *plat* is
335   ignored.
336
337   .. % Is the posix/nt only thing still true? Mac OS X seems to work, and
338   .. % returns a UnixCCompiler instance. How to document this... hmm.
339
340
341.. function:: show_compilers()
342
343   Print list of available compilers (used by the :option:`--help-compiler` options
344   to :command:`build`, :command:`build_ext`, :command:`build_clib`).
345
346
n347-.. class:: CCompiler([verbose=``0``, dry_run=``0``, force=``0``])
n352+.. class:: CCompiler([verbose=0, dry_run=0, force=0])
348
349   The abstract base class :class:`CCompiler` defines the interface that  must be
350   implemented by real compiler classes.  The class also has  some utility methods
351   used by several compiler classes.
352
353   The basic idea behind a compiler abstraction class is that each instance can be
354   used for all the compile/link steps in building a single project.  Thus,
355   attributes common to all of those compile and link steps --- include
429
430   .. method:: CCompiler.set_runtime_library_dirs(dirs)
431
432      Set the list of directories to search for shared libraries at runtime to *dirs*
433      (a list of strings).  This does not affect any standard search path that the
434      runtime linker may search by default.
435
436
n437-   .. method:: CCompiler.define_macro(name[, value=``None``])
n442+   .. method:: CCompiler.define_macro(name[, value=None])
438
439      Define a preprocessor macro for all compilations driven by this compiler object.
440      The optional parameter *value* should be a string; if it is not supplied, then
441      the macro will be defined without an explicit value and the exact outcome
442      depends on the compiler used (XXX true? does ANSI say anything about this?)
443
444
445   .. method:: CCompiler.undefine_macro(name)
446
447      Undefine a preprocessor macro for all compilations driven by this compiler
n448-      object.  If the same macro is defined by :meth:`define_macro` and undefined by
n453+      object.  If the same macro is defined by :meth:`define_macro` and
449-      :meth:`undefine_macro`  the last call takes precedence (including multiple
454+      undefined by :meth:`undefine_macro` the last call takes precedence
450-      redefinitions or undefinitions).  If the macro is redefined/undefined on a per-
455+      (including multiple redefinitions or undefinitions).  If the macro is
451-      compilation basis (ie. in the call to :meth:`compile`), then that takes
456+      redefined/undefined on a per-compilation basis (ie. in the call to
452-      precedence.
457+      :meth:`compile`), then that takes precedence.
453
454
455   .. method:: CCompiler.add_link_object(object)
456
457      Add *object* to the list of object files (or analogues, such as explicitly named
458      library files or the output of "resource compilers") to be included in every
459      link driven by this compiler object.
460
471
472   .. method:: CCompiler.detect_language(sources)
473
474      Detect the language of a given file, or list of files. Uses the  instance
475      attributes :attr:`language_map` (a dictionary), and  :attr:`language_order` (a
476      list) to do the job.
477
478
n479-   .. method:: CCompiler.find_library_file(dirs, lib[, debug=``0``])
n484+   .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
480
481      Search the specified list of directories for a static or shared library file
482      *lib* and return the full path to that file.  If *debug* is true, look for a
483      debugging version (if that makes sense on the current platform).  Return
484      ``None`` if *lib* wasn't found in any of the specified directories.
485
486
n487-   .. method:: CCompiler.has_function(funcname [, includes=``None``, include_dirs=``None``, libraries=``None``, library_dirs=``None``])
n492+   .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
488
489      Return a boolean indicating whether *funcname* is supported on the current
490      platform.  The optional arguments can be used to augment the compilation
491      environment by providing additional include files and paths and libraries and
492      paths.
493
494
495   .. method:: CCompiler.library_dir_option(dir)
534      that will be split into executable name and (optional) list of arguments.
535      (Splitting the string is done similarly to how Unix shells operate: words are
536      delimited by spaces, but quotes and backslashes can override this.  See
537      :func:`distutils.util.split_quoted`.)
538
539   The following methods invoke stages in the build process.
540
541
n542-   .. method:: CCompiler.compile(sources[, output_dir=``None``, macros=``None``, include_dirs=``None``, debug=``0``, extra_preargs=``None``, extra_postargs=``None``, depends=``None``])
n547+   .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
543
544      Compile one or more source files. Generates object files (e.g.  transforms a
545      :file:`.c` file to a :file:`.o` file.)
546
547      *sources* must be a list of filenames, most likely C/C++ files, but in reality
548      anything that can be handled by a particular compiler and compiler class (eg.
549      :class:`MSVCCompiler` can handle resource files in *sources*).  Return a list of
550      object filenames, one per source filename in *sources*.  Depending on the
578      *depends*, if given, is a list of filenames that all targets depend on.  If a
579      source file is older than any file in depends, then the source file will be
580      recompiled.  This supports dependency tracking, but only at a coarse
581      granularity.
582
583      Raises :exc:`CompileError` on failure.
584
585
n586-   .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=``None``, debug=``0``, target_lang=``None``])
n591+   .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
587
588      Link a bunch of stuff together to create a static library file. The "bunch of
589      stuff" consists of the list of object files supplied as *objects*, the extra
590      object files supplied to :meth:`add_link_object` and/or
591      :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
592      :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
593
594      *output_libname* should be a library name, not a filename; the filename will be
600      the *debug* flag is included here just for consistency).
601
602      *target_lang* is the target language for which the given objects are being
603      compiled. This allows specific linkage time treatment of certain languages.
604
605      Raises :exc:`LibError` on failure.
606
607
n608-   .. 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``])
n613+   .. 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])
609
610      Link a bunch of stuff together to create an executable or shared library file.
611
612      The "bunch of stuff" consists of the list of object files supplied as *objects*.
613      *output_filename* should be a filename.  If *output_dir* is supplied,
614      *output_filename* is relative to it (i.e. *output_filename* can provide
615      directory components if needed).
616
642      used).
643
644      *target_lang* is the target language for which the given objects are being
645      compiled. This allows specific linkage time treatment of certain languages.
646
647      Raises :exc:`LinkError` on failure.
648
649
n650-   .. 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``])
n655+   .. 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])
651
652      Link an executable.  *output_progname* is the name of the file executable, while
653      *objects* are a list of object filenames to link in. Other arguments  are as for
654      the :meth:`link` method.
655
656
n657-   .. 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``])
n662+   .. 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])
658
659      Link a shared library. *output_libname* is the name of the output  library,
660      while *objects* is a list of object filenames to link in.  Other arguments are
661      as for the :meth:`link` method.
662
663
n664-   .. 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``])
n669+   .. 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])
665
666      Link a shared object. *output_filename* is the name of the shared object that
667      will be created, while *objects* is a list of object filenames  to link in.
668      Other arguments are as for the :meth:`link` method.
669
670
n671-   .. method:: CCompiler.preprocess(source[, output_file=``None``, macros=``None``, include_dirs=``None``, extra_preargs=``None``, extra_postargs=``None``])
n676+   .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
672
673      Preprocess a single C/C++ source file, named in *source*. Output will be written
674      to file named *output_file*, or *stdout* if *output_file* not supplied.
675      *macros* is a list of macro definitions as for :meth:`compile`, which will
676      augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
677      *include_dirs* is a list of directory names that will be added to the  default
678      list, in the same way as :meth:`add_include_dir`.
679
680      Raises :exc:`PreprocessError` on failure.
681
682   The following utility methods are defined by the :class:`CCompiler` class, for
683   use by the various concrete subclasses.
684
685
n686-   .. method:: CCompiler.executable_filename(basename[, strip_dir=``0``, output_dir=``''``])
n691+   .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
687
688      Returns the filename of the executable for the given *basename*.  Typically for
689      non-Windows platforms this is the same as the basename,  while Windows will get
690      a :file:`.exe` added.
691
692
n693-   .. method:: CCompiler.library_filename(libname[, lib_type=``'static'``, strip_dir=``0``, output_dir=``''``])
n698+   .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
694
695      Returns the filename for the given library name on the current platform. On Unix
696      a library with *lib_type* of ``'static'`` will typically  be of the form
697      :file:`liblibname.a`, while a *lib_type* of ``'dynamic'``  will be of the form
698      :file:`liblibname.so`.
699
700
n701-   .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=``0``, output_dir=``''``])
n706+   .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
702
703      Returns the name of the object files for the given source files.
704      *source_filenames* should be a list of filenames.
705
706
n707-   .. method:: CCompiler.shared_object_filename(basename[, strip_dir=``0``, output_dir=``''``])
n712+   .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
708
709      Returns the name of a shared object file for the given file name *basename*.
710
711
n712-   .. method:: CCompiler.execute(func, args[, msg=``None``, level=``1``])
n717+   .. method:: CCompiler.execute(func, args[, msg=None, level=1])
713
714      Invokes :func:`distutils.util.execute` This method invokes a  Python function
715      *func* with the given arguments *args*, after  logging and taking into account
716      the *dry_run* flag. XXX see also.
717
718
719   .. method:: CCompiler.spawn(cmd)
720
721      Invokes :func:`distutils.util.spawn`. This invokes an external  process to run
722      the given command. XXX see also.
723
724
n725-   .. method:: CCompiler.mkpath(name[, mode=``511``])
n730+   .. method:: CCompiler.mkpath(name[, mode=511])
726
727      Invokes :func:`distutils.dir_util.mkpath`. This creates a directory  and any
728      missing ancestor directories. XXX see also.
729
730
731   .. method:: CCompiler.move_file(src, dst)
732
733      Invokes :meth:`distutils.file_util.move_file`. Renames *src* to  *dst*.  XXX see
734      also.
735
736
n737-   .. method:: CCompiler.announce(msg[, level=``1``])
n742+   .. method:: CCompiler.announce(msg[, level=1])
738
739      Write a message using :func:`distutils.log.debug`. XXX see also.
740
741
742   .. method:: CCompiler.warn(msg)
743
744      Write a warning message *msg* to standard error.
745
746
747   .. method:: CCompiler.debug_print(msg)
748
749      If the *debug* flag is set on this :class:`CCompiler` instance, print  *msg* to
750      standard output, otherwise do nothing.
751
752.. % \subsection{Compiler-specific modules}
n753-.. % 
n758+.. %
754.. % The following modules implement concrete subclasses of the abstract
755.. % \class{CCompiler} class. They should not be instantiated directly, but should
756.. % be created using \function{distutils.ccompiler.new_compiler()} factory
757.. % function.
758
759
760:mod:`distutils.unixccompiler` --- Unix C Compiler
761==================================================
849   :synopsis: Metrowerks CodeWarrior support
850
851
852Contains :class:`MWerksCompiler`, an implementation of the abstract
853:class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X
854Macintosh. Needs work to support CW on Windows or Mac OS X.
855
856.. % \subsection{Utility modules}
n857-.. % 
n862+.. %
858.. % The following modules all provide general utility functions. They haven't
859.. % all been documented yet.
860
861
862:mod:`distutils.archive_util` ---  Archiving utilities
863======================================================
864
865.. module:: distutils.archive_util
866   :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
867
868
869This module provides a few functions for creating archive files, such as
870tarballs or zipfiles.
871
872
n873-.. function:: make_archive(base_name, format[, root_dir=``None``, base_dir=``None``, verbose=``0``, dry_run=``0``])
n878+.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
874
875   Create an archive file (eg. ``zip`` or ``tar``).  *base_name*  is the name of
876   the file to create, minus any format-specific extension;  *format* is the
877   archive format: one of ``zip``, ``tar``,  ``ztar``, or ``gztar``. *root_dir* is
878   a directory that will be the root directory of the archive; ie. we typically
879   ``chdir`` into *root_dir* before  creating the archive.  *base_dir* is the
880   directory where we start  archiving from; ie. *base_dir* will be the common
881   prefix of all files and directories in the archive.  *root_dir* and *base_dir*
882   both default to the current directory.  Returns the name of the archive file.
883
884   .. warning::
885
886      This should be changed to support bz2 files
887
888
n889-.. function:: make_tarball(base_name, base_dir[, compress=``'gzip'``, verbose=``0``, dry_run=``0``])
n894+.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
890
891   'Create an (optional compressed) archive as a tar file from all files in and
892   under *base_dir*. *compress* must be ``'gzip'`` (the default),  ``'compress'``,
893   ``'bzip2'``, or ``None``.  Both :program:`tar` and the compression utility named
894   by *compress* must be on the  default program search path, so this is probably
895   Unix-specific.  The  output tar file will be named :file:`base_dir.tar`,
896   possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
897   or :file:`.Z`).  Return the output filename.
898
899   .. warning::
900
901      This should be replaced with calls to the :mod:`tarfile` module.
902
903
n904-.. function:: make_zipfile(base_name, base_dir[, verbose=``0``, dry_run=``0``])
n909+.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
905
906   Create a zip file from all files in and under *base_dir*.  The output zip file
907   will be named *base_dir* + :file:`.zip`.  Uses either the  :mod:`zipfile` Python
908   module (if available) or the InfoZIP :file:`zip`  utility (if installed and
909   found on the default search path).  If neither  tool is available, raises
910   :exc:`DistutilsExecError`.   Returns the name of the output zip file.
911
912
934
935   Walk two filename lists in parallel, testing if each source is newer than its
936   corresponding target.  Return a pair of lists (*sources*, *targets*) where
937   source is newer than target, according to the semantics of :func:`newer`
938
939   .. % % equivalent to a listcomp...
940
941
n942-.. function:: newer_group(sources, target[, missing=``'error'``])
n947+.. function:: newer_group(sources, target[, missing='error'])
943
944   Return true if *target* is out-of-date with respect to any file listed in
945   *sources*  In other words, if *target* exists and is newer than every file in
946   *sources*, return false; otherwise return true. *missing* controls what we do
947   when a source file is missing; the default (``'error'``) is to blow up with an
948   :exc:`OSError` from  inside :func:`os.stat`; if it is ``'ignore'``, we silently
949   drop any missing source files; if it is ``'newer'``, any missing source files
950   make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
959.. module:: distutils.dir_util
960   :synopsis: Utility functions for operating on directories and directory trees
961
962
963This module provides functions for operating on directories and trees of
964directories.
965
966
n967-.. function:: mkpath(name[, mode=``0777``, verbose=``0``, dry_run=``0``])
n972+.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0])
968
969   Create a directory and any missing ancestor directories.  If the directory
970   already exists (or if *name* is the empty string, which means the current
971   directory, which of course exists), then do nothing.  Raise
972   :exc:`DistutilsFileError` if unable to create some directory along the way (eg.
973   some sub-path exists, but is a file rather than a directory).  If *verbose* is
974   true, print a one-line summary of each mkdir to stdout.  Return the list of
975   directories actually created.
976
977
n978-.. function:: create_tree(base_dir, files[, mode=``0777``, verbose=``0``, dry_run=``0``])
n983+.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0])
979
980   Create all the empty directories under *base_dir* needed to put *files* there.
981   *base_dir* is just the a name of a directory which doesn't necessarily exist
982   yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
983   *base_dir* + the directory portion of every file in *files* will be created if
984   it doesn't already exist.  *mode*, *verbose* and *dry_run* flags  are as for
985   :func:`mkpath`.
986
987
n988-.. function:: copy_tree(src, dst[preserve_mode=``1``, preserve_times=``1``, preserve_symlinks=``0``, update=``0``, verbose=``0``, dry_run=``0``])
n993+.. function:: copy_tree(src, dst[preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
989
990   Copy an entire directory tree *src* to a new location *dst*.  Both *src* and
991   *dst* must be directory names.  If *src* is not a directory, raise
992   :exc:`DistutilsFileError`.  If *dst* does  not exist, it is created with
993   :func:`mkpath`.  The end result of the  copy is that every file in *src* is
994   copied to *dst*, and  directories under *src* are recursively copied to *dst*.
995   Return the list of files that were copied or might have been copied, using their
996   output name. The return value is unaffected by *update* or *dry_run*: it is
1000   *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in
1001   :mod:`distutils.file_util`; note that they only apply to regular files, not to
1002   directories.  If *preserve_symlinks* is true, symlinks will be copied as
1003   symlinks (on platforms that support them!); otherwise (the default), the
1004   destination of the symlink will be copied.  *update* and *verbose* are the same
1005   as for :func:`copy_file`.
1006
1007
n1008-.. function:: remove_tree(directory[verbose=``0``, dry_run=``0``])
n1013+.. function:: remove_tree(directory[verbose=0, dry_run=0])
1009
1010   Recursively remove *directory* and all files and directories underneath it. Any
1011   errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
1012   true).
1013
1014**\*\*** Some of this could be replaced with the shutil module? **\*\***
1015
1016
1019
1020.. module:: distutils.file_util
1021   :synopsis: Utility functions for operating on single files
1022
1023
1024This module contains some utility functions for operating on individual files.
1025
1026
n1027-.. function:: copy_file(src, dst[preserve_mode=``1``, preserve_times=``1``, update=``0``, link=``None``, verbose=``0``, dry_run=``0``])
n1032+.. function:: copy_file(src, dst[preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
1028
1029   Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
1030   with the same name; otherwise, it must be a filename. (If the file exists, it
1031   will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
n1032-   file's mode (type and permission bits, or whatever is analogous on the current
n1037+   file's mode (type and permission bits, or whatever is analogous on the
1033-   platform) is copied. If *preserve_times* is true (the default), the last-
1038+   current platform) is copied. If *preserve_times* is true (the default), the
1034-   modified and last-access times are copied as well. If *update* is true, *src*
1039+   last-modified and last-access times are copied as well. If *update* is true,
1035-   will only be copied if *dst* does not exist, or if *dst* does exist but is older
1040+   *src* will only be copied if *dst* does not exist, or if *dst* does exist but
1036-   than *src*.
1041+   is older than *src*.
1037
1038   *link* allows you to make hard links (using :func:`os.link`) or symbolic links
1039   (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
1040   ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
1041   on systems that don't support it: :func:`copy_file` doesn't check if hard or
1042   symbolic linking is available.  It uses :func:`_copy_file_contents` to copy file
1043   contents.
1044
1049   .. % XXX if the destination file already exists, we clobber it if
1050   .. % copying, but blow up if linking.  Hmmm.  And I don't know what
1051   .. % macostools.copyfile() does.  Should definitely be consistent, and
1052   .. % should probably blow up if destination exists and we would be
1053   .. % changing it (ie. it's not already a hard/soft link to src OR
1054   .. % (not update) and (src newer than dst)).
1055
1056
n1057-.. function:: move_file(src, dst[verbose, dry_run])
n1062+.. function:: move_file(src, dst[verbose, dry_run])
1058
1059   Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
1060   it with the same name; otherwise, *src* is just renamed to *dst*.  Returns the
1061   new full name of the file.
1062
1063   .. warning::
1064
n1065-      Handles cross-device moves on Unix using :func:`copy_file`.   What about other
n1070+      Handles cross-device moves on Unix using :func:`copy_file`.  What about
1066-      systems???
1071+      other systems?
1067
1068
1069.. function:: write_file(filename, contents)
1070
1071   Create a file called *filename* and write *contents* (a sequence of strings
1072   without line terminators) to it.
1073
1074
1090   distributions.  Typically includes the OS name and version and the architecture
1091   (as supplied by 'os.uname()'), although the exact information included depends
1092   on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
1093   runs on SGI hardware), but for Linux the kernel version isn't particularly
1094   important.
1095
1096   Examples of returned values:
1097
n1098-* ``linux-i586``
n1103+   * ``linux-i586``
1099- 
1100-* ``linux-alpha``
1104+   * ``linux-alpha``
1101- 
1102-* ``solaris-2.6-sun4u``
1105+   * ``solaris-2.6-sun4u``
1103- 
1104-* ``irix-5.3``
1106+   * ``irix-5.3``
1105- 
1106-* ``irix64-6.2``
1107+   * ``irix64-6.2``
1107
1108   For non-POSIX platforms, currently just returns ``sys.platform``.
n1110+ 
1111+   For Mac OS X systems the OS version reflects the minimal version on which
1112+   binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
1113+   during the build of Python), not the OS version of the current system.
1114+ 
1115+   For universal binary builds on Mac OS X the architecture value reflects
1116+   the univeral binary status instead of the architecture of the current
1117+   processor. For 32-bit universal binaries the architecture is ``fat``,
1118+   for 64-bit universal binaries the architecture is ``fat64``, and
1119+   for 4-way universal binaries the architecture is ``universal``.
1120+ 
1121+   Examples of returned values on Mac OS X:
1122+ 
1123+   * ``macosx-10.3-ppc``
1124+ 
1125+   * ``macosx-10.3-fat``
1126+ 
1127+   * ``macosx-10.5-universal``
1109
1110   .. % XXX isn't this also provided by some other non-distutils module?
1111
1112
1113.. function:: convert_path(pathname)
1114
1115   Return 'pathname' as a name that will work on the native filesystem, i.e. split
1116   it on '/' and put it back together again using the current directory separator.
1128
1129
1130.. function:: check_environ()
1131
1132   Ensure that 'os.environ' has all the environment variables we guarantee that
1133   users can use in config files, command-line options, etc.  Currently this
1134   includes:
1135
n1136-* :envvar:`HOME` - user's home directory (Unix only)
n1155+   * :envvar:`HOME` - user's home directory (Unix only)
1137- 
1138-* :envvar:`PLAT` - description of the current platform, including hardware and
1156+   * :envvar:`PLAT` - description of the current platform, including hardware and
1139     OS (see :func:`get_platform`)
1140
1141
1142.. function:: subst_vars(s, local_vars)
1143
1144   Perform shell/Perl-style variable substitution on *s*.  Every occurrence of
1145   ``$`` followed by a name is considered a variable, and variable is substituted
1146   by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
1148   it contains certain values: see :func:`check_environ`.  Raise :exc:`ValueError`
1149   for any variables not found in either *local_vars* or ``os.environ``.
1150
1151   Note that this is not a fully-fledged string interpolation function. A valid
1152   ``$variable`` can consist only of upper and lower case letters, numbers and an
1153   underscore. No { } or ( ) style quoting is available.
1154
1155
n1156-.. function:: grok_environment_error(exc[, prefix=``'error: '``])
n1174+.. function:: grok_environment_error(exc[, prefix='error: '])
1157
1158   Generate a useful error message from an :exc:`EnvironmentError`  (:exc:`IOError`
1159   or :exc:`OSError`) exception object.   Handles Python 1.5.1 and later styles,
1160   and does what it can to deal with  exception objects that don't have a filename
1161   (which happens when the error  is due to a two-file operation, such as
1162   :func:`rename` or  :func:`link`).  Returns the error message as a string
1163   prefixed  with *prefix*.
1164
1171   equivalent, and the quote characters can be backslash-escaped.  The backslash is
1172   stripped from any two-character escape sequence, leaving only the escaped
1173   character.  The quote characters are stripped from any quoted string.  Returns a
1174   list of words.
1175
1176   .. % Should probably be moved into the standard library.
1177
1178
n1179-.. function:: execute(func, args[, msg=``None``, verbose=``0``, dry_run=``0``])
n1197+.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
1180
1181   Perform some action that affects the outside world (for instance, writing to the
1182   filesystem).  Such actions are special because they are disabled by the
1183   *dry_run* flag.  This method takes  care of all that bureaucracy for you; all
1184   you have to do is supply the function to call and an argument tuple for it (to
1185   embody the "external action" being performed), and an optional message to print.
1186
1187
1189
1190   Convert a string representation of truth to true (1) or false (0).
1191
1192   True values are ``y``, ``yes``, ``t``, ``true``, ``on``  and ``1``; false values
1193   are ``n``, ``no``, ``f``, ``false``,  ``off`` and ``0``.  Raises
1194   :exc:`ValueError` if *val*  is anything else.
1195
1196
n1197-.. function:: byte_compile(py_files[, optimize=``0``, force=``0``, prefix=``None``, base_dir=``None``, verbose=``1``, dry_run=``0``, direct=``None``])
n1215+.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
1198
1199   Byte-compile a collection of Python source files to either :file:`.pyc` or
1200   :file:`.pyo` files in the same directory.  *py_files* is a list of files to
1201   compile; any files that don't end in :file:`.py` are silently skipped.
1202   *optimize* must be one of the following:
1203
n1204-* ``0`` - don't optimize (generate :file:`.pyc`)
n1222+   * ``0`` - don't optimize (generate :file:`.pyc`)
1205- 
1206-* ``1`` - normal optimization (like ``python -O``)
1223+   * ``1`` - normal optimization (like ``python -O``)
1207- 
1208-* ``2`` - extra optimization (like ``python -OO``)
1224+   * ``2`` - extra optimization (like ``python -OO``)
1209
1210   If *force* is true, all files are recompiled regardless of timestamps.
1211
n1212-   The source filename encoded in each bytecode file defaults to the filenames
n1228+   The source filename encoded in each :term:`bytecode` file defaults to the filenames
1213   listed in *py_files*; you can modify these with *prefix* and *basedir*.
1214   *prefix* is a string that will be stripped off of each source filename, and
1215   *base_dir* is a directory name that will be prepended (after *prefix* is
1216   stripped).  You can supply either or both (or neither) of *prefix* and
1217   *base_dir*, as you wish.
1218
1219   If *dry_run* is true, doesn't actually do anything that would affect the
1220   filesystem.
1331   Wraps *text* to less than *width* wide.
1332
1333   .. warning::
1334
1335      Should be replaced with :mod:`textwrap` (which is available  in Python 2.3 and
1336      later).
1337
1338
n1339-.. class:: FancyGetopt([option_table=``None``])
n1355+.. class:: FancyGetopt([option_table=None])
1340
1341   The option_table is a list of 3-tuples: ``(long_option, short_option,
1342   help_string)``
1343
1344   If an option takes an argument, its *long_option* should have ``'='`` appended;
1345   *short_option* should just be a single character, no ``':'`` in any case.
1346   *short_option* should be ``None`` if a *long_option*  doesn't have a
1347   corresponding *short_option*. All option tuples must have long options.
1348
1349The :class:`FancyGetopt` class provides the following methods:
1350
1351
n1352-.. method:: FancyGetopt.getopt([args=``None``, object=``None``])
n1368+.. method:: FancyGetopt.getopt([args=None, object=None])
1353
1354   Parse command-line options in args. Store as attributes on *object*.
1355
1356   If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``.  If *object* is
1357   ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
1358   option values there, and returns a tuple ``(args, object)``.  If *object* is
1359   supplied, it is modified in place and :func:`getopt` just returns *args*; in
1360   both cases, the returned *args* is a modified copy of the passed-in *args* list,
1365
1366.. method:: FancyGetopt.get_option_order()
1367
1368   Returns the list of ``(option, value)`` tuples processed by the previous run of
1369   :meth:`getopt`  Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
1370   yet.
1371
1372
n1373-.. method:: FancyGetopt.generate_help([header=``None``])
n1389+.. method:: FancyGetopt.generate_help([header=None])
1374
1375   Generate help text (a list of strings, one per suggested line of output) from
1376   the option table for this :class:`FancyGetopt` object.
1377
1378   If supplied, prints the supplied *header* at the top of the help.
1379
1380
1381:mod:`distutils.filelist` --- The FileList class
1413   :synopsis: Provides the spawn() function
1414
1415
1416This module provides the :func:`spawn` function, a front-end to  various
1417platform-specific functions for launching another program in a  sub-process.
1418Also provides :func:`find_executable` to search the path for a given executable
1419name.
1420
n1421-XXX: input{sysconfig} :XXX
n1437+ 
1438+:mod:`distutils.sysconfig` --- System configuration information
1439+===============================================================
1440+ 
1441+.. module:: distutils.sysconfig
1442+   :synopsis: Low-level access to configuration information of the Python interpreter.
1443+.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1444+.. moduleauthor:: Greg Ward <gward@python.net>
1445+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1446+ 
1447+ 
1448+The :mod:`distutils.sysconfig` module provides access to Python's low-level
1449+configuration information.  The specific configuration variables available
1450+depend heavily on the platform and configuration. The specific variables depend
1451+on the build process for the specific version of Python being run; the variables
1452+are those found in the :file:`Makefile` and configuration header that are
1453+installed with Python on Unix systems.  The configuration header is called
1454+:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
1455+for earlier versions of Python.
1456+ 
1457+Some additional functions are provided which perform some useful manipulations
1458+for other parts of the :mod:`distutils` package.
1459+ 
1460+ 
1461+.. data:: PREFIX
1462+ 
1463+   The result of ``os.path.normpath(sys.prefix)``.
1464+ 
1465+ 
1466+.. data:: EXEC_PREFIX
1467+ 
1468+   The result of ``os.path.normpath(sys.exec_prefix)``.
1469+ 
1470+ 
1471+.. function:: get_config_var(name)
1472+ 
1473+   Return the value of a single variable.  This is equivalent to
1474+   ``get_config_vars().get(name)``.
1475+ 
1476+ 
1477+.. function:: get_config_vars(...)
1478+ 
1479+   Return a set of variable definitions.  If there are no arguments, this returns a
1480+   dictionary mapping names of configuration variables to values.  If arguments are
1481+   provided, they should be strings, and the return value will be a sequence giving
1482+   the associated values. If a given name does not have a corresponding value,
1483+   ``None`` will be included for that variable.
1484+ 
1485+ 
1486+.. function:: get_config_h_filename()
1487+ 
1488+   Return the full path name of the configuration header.  For Unix, this will be
1489+   the header generated by the :program:`configure` script; for other platforms the
1490+   header will have been supplied directly by the Python source distribution.  The
1491+   file is a platform-specific text file.
1492+ 
1493+ 
1494+.. function:: get_makefile_filename()
1495+ 
1496+   Return the full path name of the :file:`Makefile` used to build Python.  For
1497+   Unix, this will be a file generated by the :program:`configure` script; the
1498+   meaning for other platforms will vary.  The file is a platform-specific text
1499+   file, if it exists. This function is only useful on POSIX platforms.
1500+ 
1501+ 
1502+.. function:: get_python_inc([plat_specific[, prefix]])
1503+ 
1504+   Return the directory for either the general or platform-dependent C include
1505+   files.  If *plat_specific* is true, the platform-dependent include directory is
1506+   returned; if false or omitted, the platform-independent directory is returned.
1507+   If *prefix* is given, it is used as either the prefix instead of
1508+   :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1509+   *plat_specific* is true.
1510+ 
1511+ 
1512+.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
1513+ 
1514+   Return the directory for either the general or platform-dependent library
1515+   installation.  If *plat_specific* is true, the platform-dependent include
1516+   directory is returned; if false or omitted, the platform-independent directory
1517+   is returned.  If *prefix* is given, it is used as either the prefix instead of
1518+   :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1519+   *plat_specific* is true.  If *standard_lib* is true, the directory for the
1520+   standard library is returned rather than the directory for the installation of
1521+   third-party extensions.
1522+ 
1523+The following function is only intended for use within the :mod:`distutils`
1524+package.
1525+ 
1526+ 
1527+.. function:: customize_compiler(compiler)
1528+ 
1529+   Do any platform-specific customization of a
1530+   :class:`distutils.ccompiler.CCompiler` instance.
1531+ 
1532+   This function is only needed on Unix at this time, but should be called
1533+   consistently to support forward-compatibility.  It inserts the information that
1534+   varies across Unix flavors and is stored in Python's :file:`Makefile`.  This
1535+   information includes the selected compiler, compiler and linker options, and the
1536+   extension used by the linker for shared objects.
1537+ 
1538+This function is even more special-purpose, and should only be used from
1539+Python's own build procedures.
1540+ 
1541+ 
1542+.. function:: set_python_build()
1543+ 
1544+   Inform the :mod:`distutils.sysconfig` module that it is being used as part of
1545+   the build process for Python.  This changes a lot of relative locations for
1546+   files, allowing them to be located in the build area rather than in an installed
1547+   Python.
1548+ 
1422
1423:mod:`distutils.text_file` --- The TextFile class
1424=================================================
1425
1426.. module:: distutils.text_file
1427   :synopsis: provides the TextFile class, a simple interface to text files
1428
1429
1430This module provides the :class:`TextFile` class, which gives an interface  to
1431text files that (optionally) takes care of stripping comments, ignoring  blank
1432lines, and joining lines with backslashes.
1433
1434
n1435-.. class:: TextFile([filename=``None``, file=``None``, **options])
n1562+.. class:: TextFile([filename=None, file=None, **options])
1436
1437   This class provides a file-like object that takes care of all  the things you
1438   commonly want to do when processing a text file  that has some line-by-line
1439   syntax: strip comments (as long as ``#``  is your comment character), skip blank
1440   lines, join adjacent lines by escaping the newline (ie. backslash at end of
1441   line), strip leading and/or trailing whitespace.  All of these are optional and
1442   independently controllable.
1443
1515
1516
1517   .. method:: TextFile.close()
1518
1519      Close the current file and forget everything we know about it (including the
1520      filename and the current line number).
1521
1522
n1523-   .. method:: TextFile.warn(msg[,line=``None``])
n1650+   .. method:: TextFile.warn(msg[,line=None])
1524
1525      Print (to stderr) a warning message tied to the current logical line in the
1526      current file.  If the current logical line in the file spans multiple physical
1527      lines, the warning refers to the whole range, such as ``"lines 3-5"``.  If
1528      *line* is supplied,  it overrides the current line number; it may be a list or
1529      tuple  to indicate a range of physical lines, or an integer for a  single
1530      physical line.
1531
1561===================================================
1562
1563.. module:: distutils.version
1564   :synopsis: implements classes that represent module version numbers.
1565
1566
1567.. % todo
1568.. % \section{Distutils Commands}
n1569-.. % 
n1696+.. %
1570.. % This part of Distutils implements the various Distutils commands, such
1571.. % as \code{build}, \code{install} \&c. Each command is implemented as a
1572.. % separate module, with the command name as the name of the module.
1573
1574
1575:mod:`distutils.cmd` --- Abstract base class for Distutils commands
1576===================================================================
1577
1637
1638.. module:: distutils.command.bdist_dumb
1639   :synopsis: Build a "dumb" installer - a simple archive of files
1640
1641
1642.. % todo
1643
1644
n1772+:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
1773+=================================================================================
1774+ 
1775+.. module:: distutils.command.bdist_msi
1776+   :synopsis: Build a binary distribution as a Windows MSI file
1777+ 
1778+.. class:: bdist_msi(Command)
1779+ 
1780+   Builds a `Windows Installer`_ (.msi) binary package.
1781+ 
1782+   .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
1783+ 
1784+   In most cases, the ``bdist_msi`` installer is a better choice than the
1785+   ``bdist_wininst`` installer, because it provides better support for
1786+   Win64 platforms, allows administrators to perform non-interactive
1787+   installations, and allows installation through group policies.
1788+ 
1789+ 
1645:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
1646===========================================================================================
1647
1648.. module:: distutils.command.bdist_rpm
1649   :synopsis: Build a binary distribution as a Redhat RPM and SRPM
1650
1651
1652.. % todo
1818``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
1819:file:`command_template`  to :file:`distutils/command/peel_banana.py`, then edit
1820it so that it's implementing the class :class:`peel_banana`, a subclass of
1821:class:`distutils.cmd.Command`.
1822
1823Subclasses of :class:`Command` must define the following methods.
1824
1825
n1826-.. method:: XXX Class.initialize_options()(S)
n1971+.. method:: Command.initialize_options()(S)
1827
1828   et default values for all the options that this command supports.  Note that
1829   these defaults may be overridden by other commands, by the setup script, by
1830   config files, or by the command-line.  Thus, this is not the place to code
1831   dependencies between options; generally, :meth:`initialize_options`
1832   implementations are just a bunch of ``self.foo = None`` assignments.
1833
1834
n1835-.. method:: XXX Class.finalize_options()
n1980+.. method:: Command.finalize_options()
1836
n1837-   Set final values for all the options that this command supports. This is always
n1982+   Set final values for all the options that this command supports. This is
1838-   called as late as possible, ie.  after any option assignments from the command-
1983+   always called as late as possible, ie.  after any option assignments from the
1839-   line or from other commands have been done.  Thus, this is the place to to code
1984+   command-line or from other commands have been done.  Thus, this is the place
1840-   option dependencies: if *foo* depends on *bar*, then it is safe to set *foo*
1985+   to to code option dependencies: if *foo* depends on *bar*, then it is safe to
1841-   from  *bar* as long as *foo* still has the same value it was assigned in
1986+   set *foo* from *bar* as long as *foo* still has the same value it was
1842-   :meth:`initialize_options`.
1987+   assigned in :meth:`initialize_options`.
1843
1844
n1845-.. method:: XXX Class.run()
n1990+.. method:: Command.run()
1846
1847   A command's raison d'etre: carry out the action it exists to perform, controlled
1848   by the options initialized in :meth:`initialize_options`, customized by other
1849   commands, the setup script, the command-line, and config files, and finalized in
1850   :meth:`finalize_options`.  All terminal output and filesystem interaction should
1851   be done by :meth:`run`.
1852
1853*sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
1858the parent command that determines whether the corresponding command is
1859applicable in the current situation.  (Eg. we ``install_headers`` is only
1860applicable if we have any C header files to install.)  If *predicate* is None,
1861that command is always applicable.
1862
1863*sub_commands* is usually defined at the \*end\* of a class, because predicates
1864can be unbound methods, so they must already have been defined.  The canonical
1865example is the :command:`install` command.
t1866- 
1867-.. % 
1868-.. % The ugly "%begin{latexonly}" pseudo-environments are really just to
1869-.. % keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
1870-.. % not really valuable.
1871-.. % 
1872-.. % begin{latexonly}
1873-.. % end{latexonly}
1874- 
1875-XXX: input{moddist.ind} :XXX
1876-.. % Module Index
1877-.. % begin{latexonly}
1878-.. % end{latexonly}
1879- 
1880-XXX: input{dist.ind} :XXX
1881-.. % Index
1882- 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op