mirror of https://github.com/python/cpython
Patch #500136: Update Update ext build documentation. 2.2.1 candidate.
This commit is contained in:
Martin v. Löwis
parent
3921ff675e
commit
27761f39a5
|
|
@ -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}
|
||||
|
||||
|
|
@ -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}
|
||||
|
||||
|
|
|
|||
189
Doc/ext/unix.tex
189
Doc/ext/unix.tex
|
|
@ -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.
|
||||
|
|
@ -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}}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue