Changeset 391 for python/trunk/Doc/distutils/setupscript.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/distutils/setupscript.rst (modified) (31 diffs)

python/trunk/Doc/distutils/setupscript.rst

@@ -20 +20 @@
 the package into Python 1.5.2.) ::
 
-   #!/usr/bin/env python
-
-   from distutils.core import setup
-
-   setup(name='Distutils',
-         version='1.0',
-         description='Python Distribution Utilities',
-         author='Greg Ward',
-         author_email='gward@python.net',
-         url='http://www.python.org/sigs/distutils-sig/',
-         packages=['distutils', 'distutils.command'],
-        )
+    #!/usr/bin/env python
+
+    from distutils.core import setup
+
+    setup(name='Distutils',
+          version='1.0',
+          description='Python Distribution Utilities',
+          author='Greg Ward',
+          author_email='gward@python.net',
+          url='http://www.python.org/sigs/distutils-sig/',
+          packages=['distutils', 'distutils.command'],
+         )
 
 There are only two differences between this and the trivial one-file
@@ -54 +54 @@
 code instead of hardcoding path separators::
 
-   glob.glob(os.path.join('mydir', 'subdir', '*.html'))
-   os.listdir(os.path.join('mydir', 'subdir'))
+    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
+    os.listdir(os.path.join('mydir', 'subdir'))
 
 
@@ -73 +73 @@
 might be spelled differently on your system, but you get the idea) relative to
 the directory where your setup script lives.  If you break this promise, the
-Distutils will issue a warning but still process the broken package anyways.
+Distutils will issue a warning but still process the broken package anyway.
 
 If you use a different convention to lay out your source directory, that's no
@@ -82 +82 @@
 :file:`lib/foo`, and so forth.  Then you would put ::
 
-   package_dir = {'': 'lib'}
+    package_dir = {'': 'lib'}
 
 in your setup script.  The keys to this dictionary are package names, and an
@@ -93 +93 @@
 written in the setup script as ::
 
-   package_dir = {'foo': 'lib'}
+    package_dir = {'foo': 'lib'}
 
 A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
@@ -115 +115 @@
 section :ref:`distutils-simple-example`; here is a slightly more involved example::
 
-   py_modules = ['mod1', 'pkg.mod2']
+    py_modules = ['mod1', 'pkg.mod2']
 
 This describes two modules, one of them in the "root" package, the other in the
@@ -140 +140 @@
 All of this is done through another keyword argument to :func:`setup`, the
 :option:`ext_modules` option.  :option:`ext_modules` is just a list of
-:class:`Extension` instances, each of which describes a single extension module.
+:class:`~distutils.core.Extension` instances, each of which describes a
+single extension module.
 Suppose your distribution includes a single extension, called :mod:`foo` and
 implemented by :file:`foo.c`.  If no additional instructions to the
 compiler/linker are needed, describing this extension is quite simple::
 
-   Extension('foo', ['foo.c'])
+    Extension('foo', ['foo.c'])
 
 The :class:`Extension` class can be imported from :mod:`distutils.core` along
@@ -151 +152 @@
 contains only this one extension and nothing else might be::
 
-   from distutils.core import setup, Extension
-   setup(name='foo',
-         version='1.0',
-         ext_modules=[Extension('foo', ['foo.c'])],
-         )
+    from distutils.core import setup, Extension
+    setup(name='foo',
+          version='1.0',
+          ext_modules=[Extension('foo', ['foo.c'])],
+          )
 
 The :class:`Extension` class (actually, the underlying extension-building
@@ -166 +167 @@
 ----------------------------
 
-The first argument to the :class:`Extension` constructor is always the name of
-the extension, including any package names.  For example, ::
-
-   Extension('foo', ['src/foo1.c', 'src/foo2.c'])
+The first argument to the :class:`~distutils.core.Extension` constructor is
+always the name of the extension, including any package names.  For example, ::
+
+    Extension('foo', ['src/foo1.c', 'src/foo2.c'])
 
 describes an extension that lives in the root package, while ::
 
-   Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
+    Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
 
 describes the same extension in the :mod:`pkg` package.  The source files and
@@ -184 +185 @@
 :func:`setup`.  For example, ::
 
-   setup(...,
-         ext_package='pkg',
-         ext_modules=[Extension('foo', ['foo.c']),
-                      Extension('subpkg.bar', ['bar.c'])],
-        )
+    setup(...,
+          ext_package='pkg',
+          ext_modules=[Extension('foo', ['foo.c']),
+                       Extension('subpkg.bar', ['bar.c'])],
+         )
 
 will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
@@ -197 +198 @@
 ----------------------
 
-The second argument to the :class:`Extension` constructor is a list of source
+The second argument to the :class:`~distutils.core.Extension` constructor is
+a list of source
 files.  Since the Distutils currently only support C, C++, and Objective-C
 extensions, these are normally C/C++/Objective-C source files.  (Be sure to use
@@ -208 +210 @@
 extension.
 
-**\*\*** SWIG support is rough around the edges and largely untested! **\*\***
+.. XXX SWIG support is rough around the edges and largely untested!
 
 This warning notwithstanding, options to SWIG can be currently passed like
 this::
 
-   setup(...,
-         ext_modules=[Extension('_foo', ['foo.i'],
-                                swig_opts=['-modern', '-I../include'])],
-         py_modules=['foo'],
-        )
+    setup(...,
+          ext_modules=[Extension('_foo', ['foo.i'],
+                                 swig_opts=['-modern', '-I../include'])],
+          py_modules=['foo'],
+         )
 
 Or on the commandline like this::
 
-   > python setup.py build_ext --swig-opts="-modern -I../include"
+    > python setup.py build_ext --swig-opts="-modern -I../include"
 
 On some platforms, you can include non-source files that are processed by the
@@ -233 +235 @@
 --------------------
 
-Three optional arguments to :class:`Extension` will help if you need to specify
-include directories to search or preprocessor macros to define/undefine:
-``include_dirs``, ``define_macros``, and ``undef_macros``.
+Three optional arguments to :class:`~distutils.core.Extension` will help if
+you need to specify include directories to search or preprocessor macros to
+define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``.
 
 For example, if your extension requires header files in the :file:`include`
 directory under your distribution root, use the ``include_dirs`` option::
 
-   Extension('foo', ['foo.c'], include_dirs=['include'])
+    Extension('foo', ['foo.c'], include_dirs=['include'])
 
 You can specify absolute directories there; if you know that your extension will
@@ -246 +248 @@
 away with ::
 
-   Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
+    Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
 
 You should avoid this sort of non-portable usage if you plan to distribute your
 code: it's probably better to write C code like  ::
 
-   #include <X11/Xlib.h>
+    #include <X11/Xlib.h>
 
 If you need to include header files from some other Python extension, you can
 take advantage of the fact that header files are installed in a consistent way
-by the Distutils :command:`install_header` command.  For example, the Numerical
+by the Distutils :command:`install_headers` command.  For example, the Numerical
 Python header files are installed (on a standard Unix installation) to
 :file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
@@ -263 +265 @@
 is to write C code like  ::
 
-   #include <Numerical/arrayobject.h>
+    #include <Numerical/arrayobject.h>
 
 If you must put the :file:`Numerical` include directory right into your header
@@ -269 +271 @@
 :mod:`distutils.sysconfig` module::
 
-   from distutils.sysconfig import get_python_inc
-   incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
-   setup(...,
-         Extension(..., include_dirs=[incdir]),
-         )
+    from distutils.sysconfig import get_python_inc
+    incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
+    setup(...,
+          Extension(..., include_dirs=[incdir]),
+          )
 
 Even though this is quite portable---it will work on any Python installation,
@@ -289 +291 @@
 For example::
 
-   Extension(...,
-             define_macros=[('NDEBUG', '1'),
-                            ('HAVE_STRFTIME', None)],
-             undef_macros=['HAVE_FOO', 'HAVE_BAR'])
+    Extension(...,
+              define_macros=[('NDEBUG', '1'),
+                             ('HAVE_STRFTIME', None)],
+              undef_macros=['HAVE_FOO', 'HAVE_BAR'])
 
 is the equivalent of having this at the top of every C source file::
 
-   #define NDEBUG 1
-   #define HAVE_STRFTIME
-   #undef HAVE_FOO
-   #undef HAVE_BAR
+    #define NDEBUG 1
+    #define HAVE_STRFTIME
+    #undef HAVE_FOO
+    #undef HAVE_BAR
 
 
@@ -314 +316 @@
 library search path on target systems ::
 
-   Extension(...,
-             libraries=['gdbm', 'readline'])
+    Extension(...,
+              libraries=['gdbm', 'readline'])
 
 If you need to link with libraries in a non-standard location, you'll have to
 include the location in ``library_dirs``::
 
-   Extension(...,
-             library_dirs=['/usr/X11R6/lib'],
-             libraries=['X11', 'Xt'])
+    Extension(...,
+              library_dirs=['/usr/X11R6/lib'],
+              libraries=['X11', 'Xt'])
 
 (Again, this sort of non-portable construct should be avoided if you intend to
 distribute your code.)
 
-**\*\*** Should mention clib libraries here or somewhere else! **\*\***
+.. XXX Should mention clib libraries here or somewhere else!
 
 
@@ -348 +350 @@
 to the list of exported symbols.
 
+The :option:`depends` option is a list of files that the extension depends on
+(for example header files). The build command will call the compiler on the
+sources to rebuild extension if any on this files has been modified since the
+previous build.
 
 Relationships between Distributions and Packages
@@ -376 +382 @@
 number.  The accepted comparison operators are::
 
-   <    >    ==
-   <=   >=   !=
+    <    >    ==
+    <=   >=   !=
 
 These can be combined by using multiple qualifiers separated by commas (and
@@ -424 +430 @@
 named module or package are understood to be obsoleted.
 
+.. _distutils-installing-scripts:
 
 Installing Scripts
@@ -442 +449 @@
 way.  From the PyXML setup script::
 
-   setup(...,
-         scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
-         )
-
+    setup(...,
+          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
+          )
+
+.. versionchanged:: 2.7
+    All the scripts will also be added to the ``MANIFEST``
+    file if no template is provided. See :ref:`manifest`.
+
+.. _distutils-installing-package-data:
 
 Installing Package Data
@@ -469 +481 @@
 the files can be arranged like this in the source tree::
 
-   setup.py
-   src/
-       mypkg/
-           __init__.py
-           module.py
-           data/
-               tables.dat
-               spoons.dat
-               forks.dat
+    setup.py
+    src/
+        mypkg/
+            __init__.py
+            module.py
+            data/
+                tables.dat
+                spoons.dat
+                forks.dat
 
 The corresponding call to :func:`setup` might be::
 
-   setup(...,
-         packages=['mypkg'],
-         package_dir={'mypkg': 'src/mypkg'},
-         package_data={'mypkg': ['data/*.dat']},
-         )
+    setup(...,
+          packages=['mypkg'],
+          package_dir={'mypkg': 'src/mypkg'},
+          package_data={'mypkg': ['data/*.dat']},
+          )
 
 .. versionadded:: 2.4
 
+.. versionchanged:: 2.7
+    All the files that match ``package_data`` will be added to the ``MANIFEST``
+    file if no template is provided. See :ref:`manifest`.
+
+
+.. _distutils-additional-files:
 
 Installing Additional Files
@@ -500 +518 @@
 following way::
 
-   setup(...,
-         data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
-                     ('config', ['cfg/data.cfg']),
-                     ('/etc/init.d', ['init-script'])]
-        )
+    setup(...,
+          data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
+                      ('config', ['cfg/data.cfg']),
+                      ('/etc/init.d', ['init-script'])]
+         )
 
 Note that you can specify the directory names where the data files will be
@@ -524 +542 @@
 directory.
 
+.. versionchanged:: 2.7
+    All the files that match ``data_files`` will be added to the ``MANIFEST``
+    file if no template is provided. See :ref:`manifest`.
+
+
 
 .. _meta-data:
@@ -556 +579 @@
 |                      | package                   |                 |        |
 +----------------------+---------------------------+-----------------+--------+
-| ``long_description`` | longer description of the | long string     |        |
+| ``long_description`` | longer description of the | long string     | \(5)   |
 |                      | package                   |                 |        |
 +----------------------+---------------------------+-----------------+--------+
@@ -572 +595 @@
 
 (1)
-   These fields are required.
+    These fields are required.
 
 (2)
-   It is recommended that versions take the form *major.minor[.patch[.sub]]*.
+    It is recommended that versions take the form *major.minor[.patch[.sub]]*.
 
 (3)
-   Either the author or the maintainer must be identified.
+    Either the author or the maintainer must be identified. If maintainer is
+    provided, distutils lists it as the author in :file:`PKG-INFO`.
 
 (4)
-   These fields should not be used if your package is to be compatible with Python
-   versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
-   <http://pypi.python.org/pypi>`_.
+    These fields should not be used if your package is to be compatible with Python
+    versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
+    <http://pypi.python.org/pypi>`_.
+
+(5)
+    The ``long_description`` field is used by PyPI when you are
+    :ref:`registering <package-register>` a package, to
+    :ref:`build its home page <package-display>`.
 
 (6)
@@ -593 +622 @@
 
 'short string'
-   A single line of text, not more than 200 characters.
+    A single line of text, not more than 200 characters.
 
 'long string'
-   Multiple lines of plain text in reStructuredText format (see
-   http://docutils.sf.net/).
+    Multiple lines of plain text in reStructuredText format (see
+    http://docutils.sf.net/).
 
 'list of strings'
-   See below.
+    See below.
 
 None of the string values may be Unicode.
@@ -616 +645 @@
 
 0.1.0
-   the first, experimental release of a package
+    the first, experimental release of a package
 
 1.0.1a2
-   the second alpha release of the first patch version of 1.0
+    the second alpha release of the first patch version of 1.0
 
 :option:`classifiers` are specified in a Python list::
 
-   setup(...,
-         classifiers=[
-             'Development Status :: 4 - Beta',
-             'Environment :: Console',
-             'Environment :: Web Environment',
-             'Intended Audience :: End Users/Desktop',
-             'Intended Audience :: Developers',
-             'Intended Audience :: System Administrators',
-             'License :: OSI Approved :: Python Software Foundation License',
-             'Operating System :: MacOS :: MacOS X',
-             'Operating System :: Microsoft :: Windows',
-             'Operating System :: POSIX',
-             'Programming Language :: Python',
-             'Topic :: Communications :: Email',
-             'Topic :: Office/Business',
-             'Topic :: Software Development :: Bug Tracking',
-             ],
-         )
+    setup(...,
+          classifiers=[
+              'Development Status :: 4 - Beta',
+              'Environment :: Console',
+              'Environment :: Web Environment',
+              'Intended Audience :: End Users/Desktop',
+              'Intended Audience :: Developers',
+              'Intended Audience :: System Administrators',
+              'License :: OSI Approved :: Python Software Foundation License',
+              'Operating System :: MacOS :: MacOS X',
+              'Operating System :: Microsoft :: Windows',
+              'Operating System :: POSIX',
+              'Programming Language :: Python',
+              'Topic :: Communications :: Email',
+              'Topic :: Office/Business',
+              'Topic :: Software Development :: Bug Tracking',
+              ],
+          )
 
 If you wish to include classifiers in your :file:`setup.py` file and also wish
@@ -647 +676 @@
 :func:`setup` call. ::
 
-   # patch distutils if it can't cope with the "classifiers" or
-   # "download_url" keywords
-   from sys import version
-   if version < '2.2.3':
-       from distutils.dist import DistributionMetadata
-       DistributionMetadata.classifiers = None
-       DistributionMetadata.download_url = None
+    # patch distutils if it can't cope with the "classifiers" or
+    # "download_url" keywords
+    from sys import version
+    if version < '2.2.3':
+        from distutils.dist import DistributionMetadata
+        DistributionMetadata.classifiers = None
+        DistributionMetadata.download_url = None
 
 
@@ -675 +704 @@
 information what it is doing, and prints the full traceback in case an exception
 occurs.
-
-