Patch #500136: Update Update ext build documentation. 2.2.1 candidate.

4 files changed, 148 insertions, 190 deletions

diff --git a/Doc/ext/building.tex b/Doc/ext/building.tex
new file mode 100644
index 0000000..9eadca3
--- /dev/null
+++ b/Doc/ext/building.tex
@@ -0,0 +1,143 @@
+\chapter{Building C and \Cpp{} Extensions with distutils
+     \label{building}}
+
+\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
+
+Starting in Python 1.4, Python provides, on \UNIX{}, a special make
+file for building make files for building dynamically-linked
+extensions and custom interpreters.  Starting with Python 2.0, this
+mechanism (known as related to Makefile.pre.in, and Setup files) is no
+longer supported. Building custom interpreters was rarely used, and
+extensions modules can be build using distutils.
+
+Building an extension module using distutils requires that distutils
+is installed on the build machine, which is included in Python 2.x and
+available separately for Python 1.5. Since distutils also supports
+creation of binary packages, users don't necessarily need a compiler
+and distutils to install the extension.
+
+A distutils package contains a driver script, \file{setup.py}. This is
+a plain Python file, which, in the most simple case, could look like
+this:
+
+\begin{verbatim}
+from distutils.core import setup, Extension
+
+module1 = Extension('demo',
+                    sources = ['demo.c'])
+
+setup (name = 'PackageName',
+       version = '1.0',
+       description = 'This is a demo package',
+       ext_modules = [module1])
+
+\end{verbatim}
+
+With this \file{setup.py}, and a file \file{demo.c}, running
+
+\begin{verbatim}
+python setup.py build 
+\end{verbatim}
+
+will compile \file{demo.c}, and produce an extension module named
+\samp{demo} in the \file{build} directory. Depending on the system,
+the module file will end up in a subdirectory \file{build/lib.system},
+and may have a name like \file{demo.so} or \file{demo.pyd}.
+
+In the \file{setup.py}, all execution is performed by calling the
+\samp{setup} function. This takes a variable number of keyword 
+arguments, of which the example above uses only a
+subset. Specifically, the example specifies meta-information to build
+packages, and it specifies the contents of the package.  Normally, a
+package will contain of addition modules, like Python source modules,
+documentation, subpackages, etc. Please refer to the distutils
+documentation in \citetitle[../dist/dist.html]{Distributing Python
+Modules} to learn more about the features of distutils; this section
+explains building extension modules only.
+
+It is common to pre-compute arguments to \function{setup}, to better
+structure the driver script. In the example above,
+the\samp{ext_modules} argument to \function{setup} is a list of
+extension modules, each of which is an instance of the
+\class{Extension}. In the example, the instance defines an extension
+named \samp{demo} which is build by compiling a single source file,
+\file{demo.c}.
+
+In many cases, building an extension is more complex, since additional
+preprocessor defines and libraries may be needed. This is demonstrated
+in the example below.
+
+\begin{verbatim}
+from distutils.core import setup, Extension
+
+module1 = Extension('demo',
+                    define_macros = [('MAJOR_VERSION', '1'),
+                                     ('MINOR_VERSION', '0')],
+                    include_dirs = ['/usr/local/include'],
+                    libraries = ['tcl83'],
+                    library_dirs = ['/usr/local/lib'],
+                    sources = ['demo.c'])
+
+setup (name = 'PackageName',
+       version = '1.0',
+       description = 'This is a demo package',
+       author = 'Martin v. Loewis',
+       author_email = 'martin@v.loewis.de',
+       url = 'http://www.python.org/doc/current/ext/building.html',
+       long_description = '''
+This is really just a demo package.
+''',
+       ext_modules = [module1])
+
+\end{verbatim}
+
+In this example, \function{setup} is called with additional
+meta-information, which is recommended when distribution packages have
+to be built. For the extension itself, it specifies preprocessor
+defines, include directories, library directories, and libraries.
+Depending on the compiler, distutils passes this information in
+different ways to the compiler. For example, on \UNIX{}, this may
+result in the compilation commands
+
+\begin{verbatim}
+gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
+
+gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
+\end{verbatim}
+
+These lines are for demonstration purposes only; distutils users
+should trust that distutils gets the invocations right.
+
+\section{Distributing your extension modules
+     \label{distributing}}
+
+When an extension has been successfully build, there are three ways to
+use it.
+
+End-users will typically want to install the module, they do so by
+running
+
+\begin{verbatim}
+python setup.py install
+\end{verbatim}
+
+Module maintainers should produce source packages; to do so, they run
+
+\begin{verbatim}
+python setup.py sdist
+\end{verbatim}
+
+In some cases, additional files need to be included in a source
+distribution; this is done through a \file{MANIFEST.in} file; see the
+distutils documentation for details.
+
+If the source distribution has been build successfully, maintainers
+can also create binary distributions. Depending on the platform, one
+of the following commands can be used to do so.
+
+\begin{verbatim}
+python setup.py bdist_wininst
+python setup.py bdist_rpm
+python setup.py bdist_dumb
+\end{verbatim}
+
diff --git a/Doc/ext/ext.tex b/Doc/ext/ext.tex
index 9ad6523..b4130d1 100644
--- a/Doc/ext/ext.tex
+++ b/Doc/ext/ext.tex
@@ -52,7 +52,7 @@ For a detailed description of the whole Python/C API, see the separate
 
 \input{extending}
 \input{newtypes}
-\input{unix}
+\input{building}
 \input{windows}
 \input{embedding}
 
diff --git a/Doc/ext/unix.tex b/Doc/ext/unix.tex
deleted file mode 100644
index 396909e..0000000
--- a/Doc/ext/unix.tex
+++ /dev/null
@@ -1,189 +0,0 @@
-\chapter{Building C and \Cpp{} Extensions on \UNIX{}
-     \label{building-on-unix}}
-
-\sectionauthor{Jim Fulton}{jim@zope.com}
-
-
-%The make file make file, building C extensions on Unix
-
-
-Starting in Python 1.4, Python provides a special make file for
-building make files for building dynamically-linked extensions and
-custom interpreters.  The make file make file builds a make file
-that reflects various system variables determined by configure when
-the Python interpreter was built, so people building module's don't
-have to resupply these settings.  This vastly simplifies the process
-of building extensions and custom interpreters on \UNIX{} systems.
-
-The make file make file is distributed as the file
-\file{Misc/Makefile.pre.in} in the Python source distribution.  The
-first step in building extensions or custom interpreters is to copy
-this make file to a development directory containing extension module
-source.
-
-The make file make file, \file{Makefile.pre.in} uses metadata
-provided in a file named \file{Setup}.  The format of the \file{Setup}
-file is the same as the \file{Setup} (or \file{Setup.dist}) file
-provided in the \file{Modules/} directory of the Python source
-distribution.  The \file{Setup} file contains variable definitions:
-
-\begin{verbatim}
-EC=/projects/ExtensionClass
-\end{verbatim}
-
-and module description lines.  It can also contain blank lines and
-comment lines that start with \character{\#}.
-
-A module description line includes a module name, source files,
-options, variable references, and other input files, such
-as libraries or object files.  Consider a simple example:
-
-\begin{verbatim}
-ExtensionClass ExtensionClass.c
-\end{verbatim}
-
-This is the simplest form of a module definition line.  It defines a
-module, \module{ExtensionClass}, which has a single source file,
-\file{ExtensionClass.c}.
-
-This slightly more complex example uses an \strong{-I} option to
-specify an include directory:
-
-\begin{verbatim}
-EC=/projects/ExtensionClass
-cPersistence cPersistence.c -I$(EC)
-\end{verbatim} % $ <-- bow to font lock
-
-This example also illustrates the format for variable references.
-
-For systems that support dynamic linking, the \file{Setup} file should 
-begin:
-
-\begin{verbatim}
-*shared*
-\end{verbatim}
-
-to indicate that the modules defined in \file{Setup} are to be built
-as dynamically linked modules.  A line containing only \samp{*static*}
-can be used to indicate the subsequently listed modules should be
-statically linked.
-
-Here is a complete \file{Setup} file for building a
-\module{cPersistent} module:
-
-\begin{verbatim}
-# Set-up file to build the cPersistence module. 
-# Note that the text should begin in the first column.
-*shared*
-
-# We need the path to the directory containing the ExtensionClass
-# include file.
-EC=/projects/ExtensionClass
-cPersistence cPersistence.c -I$(EC)
-\end{verbatim} % $ <-- bow to font lock
-
-After the \file{Setup} file has been created, \file{Makefile.pre.in}
-is run with the \samp{boot} target to create a make file:
-
-\begin{verbatim}
-make -f Makefile.pre.in boot
-\end{verbatim}
-
-This creates the file, Makefile.  To build the extensions, simply
-run the created make file:
-
-\begin{verbatim}
-make
-\end{verbatim}
-
-It's not necessary to re-run \file{Makefile.pre.in} if the
-\file{Setup} file is changed.  The make file automatically rebuilds
-itself if the \file{Setup} file changes.
-
-
-\section{Building Custom Interpreters \label{custom-interps}}
-
-The make file built by \file{Makefile.pre.in} can be run with the
-\samp{static} target to build an interpreter:
-
-\begin{verbatim}
-make static
-\end{verbatim}
-
-Any modules defined in the \file{Setup} file before the
-\samp{*shared*} line will be statically linked into the interpreter.
-Typically, a \samp{*shared*} line is omitted from the
-\file{Setup} file when a custom interpreter is desired.
-
-
-\section{Module Definition Options \label{module-defn-options}}
-
-Several compiler options are supported:
-
-\begin{tableii}{l|l}{programopt}{Option}{Meaning}
-  \lineii{-C}{Tell the C pre-processor not to discard comments}
-  \lineii{-D\var{name}=\var{value}}{Define a macro}
-  \lineii{-I\var{dir}}{Specify an include directory, \var{dir}}
-  \lineii{-L\var{dir}}{Specify a link-time library directory, \var{dir}}
-  \lineii{-R\var{dir}}{Specify a run-time library directory, \var{dir}}
-  \lineii{-l\var{lib}}{Link a library, \var{lib}}
-  \lineii{-U\var{name}}{Undefine a macro}
-\end{tableii}
-
-Other compiler options can be included (snuck in) by putting them
-in variables.
-
-Source files can include files with \file{.c}, \file{.C}, \file{.cc},
-\file{.cpp}, \file{.cxx}, and \file{.c++} extensions. 
-
-Other input files include files with \file{.a}, \file{.o}, \file{.sl}, 
-and \file{.so} extensions.
-
-
-\section{Example \label{module-defn-example}}
-
-Here is a more complicated example from \file{Modules/Setup.dist}:
-
-\begin{verbatim}
-GMP=/ufs/guido/src/gmp
-mpz mpzmodule.c -I$(GMP) $(GMP)/libgmp.a
-\end{verbatim}
-
-which could also be written as:
-
-\begin{verbatim}
-mpz mpzmodule.c -I$(GMP) -L$(GMP) -lgmp
-\end{verbatim}
-
-
-\section{Distributing your extension modules
-     \label{distributing}}
-
-There are two ways to distribute extension modules for others to use.
-The way that allows the easiest cross-platform support is to use the
-\module{distutils}\refstmodindex{distutils} package.  The manual
-\citetitle[../dist/dist.html]{Distributing Python Modules} contains
-information on this approach.  It is recommended that all new
-extensions be distributed using this approach to allow easy building
-and installation across platforms.  Older extensions should migrate to
-this approach as well.
-
-What follows describes the older approach; there are still many
-extensions which use this.
-
-When distributing your extension modules in source form, make sure to
-include a \file{Setup} file.  The \file{Setup} file should be named
-\file{Setup.in} in the distribution.  The make file make file,
-\file{Makefile.pre.in}, will copy \file{Setup.in} to \file{Setup} if
-the person installing the extension doesn't do so manually.
-Distributing a \file{Setup.in} file makes it easy for people to
-customize the \file{Setup} file while keeping the original in
-\file{Setup.in}.
-
-It is a good idea to include a copy of \file{Makefile.pre.in} for
-people who do not have a source distribution of Python.
-
-Do not distribute a make file.  People building your modules
-should use \file{Makefile.pre.in} to build their own make file.  A
-\file{README} file included in the package should provide simple
-instructions to perform the build.
diff --git a/Doc/ext/windows.tex b/Doc/ext/windows.tex
index 9623eab..caac646 100644
--- a/Doc/ext/windows.tex
+++ b/Doc/ext/windows.tex
@@ -9,6 +9,10 @@ material is useful for both the Windows programmer learning to build
 Python extensions and the \UNIX{} programmer interested in producing
 software which can be successfully built on both \UNIX{} and Windows.
 
+Module authors are encouraged to use the distutils approach for
+building extension modules, instead of the one described in this
+section. You will still need the C compiler that was used to build
+Python; typically Microsoft Visual \Cpp.
 
 \section{A Cookbook Approach \label{win-cookbook}}