144 lines
5.3 KiB
TeX
144 lines
5.3 KiB
TeX
\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}
|
|
|