\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 makefile for building make files for building dynamically-linkedextensions and custom interpreters.  Starting with Python 2.0, thismechanism (known as related to Makefile.pre.in, and Setup files) is nolonger supported. Building custom interpreters was rarely used, andextension modules can be built using distutils. Building an extension module using distutils requires that distutilsis installed on the build machine, which is included in Python 2.x andavailable separately for Python 1.5. Since distutils also supportscreation of binary packages, users don't necessarily need a compilerand distutils to install the extension. A distutils package contains a driver script, \file{setup.py}. This isa plain Python file, which, in the most simple case, could look likethis: \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 asubset. Specifically, the example specifies meta-information to buildpackages, and it specifies the contents of the package.  Normally, apackage will contain of addition modules, like Python source modules,documentation, subpackages, etc. Please refer to the distutilsdocumentation in \citetitle[../dist/dist.html]{Distributing PythonModules} to learn more about the features of distutils; this sectionexplains building extension modules only. It is common to pre-compute arguments to \function{setup}, to betterstructure the driver script. In the example above,the\samp{ext_modules} argument to \function{setup} is a list ofextension modules, each of which is an instance of the\class{Extension}. In the example, the instance defines an extensionnamed \samp{demo} which is build by compiling a single source file,\file{demo.c}. In many cases, building an extension is more complex, since additionalpreprocessor defines and libraries may be needed. This is demonstratedin 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 additionalmeta-information, which is recommended when distribution packages haveto be built. For the extension itself, it specifies preprocessordefines, include directories, library directories, and libraries.Depending on the compiler, distutils passes this information indifferent ways to the compiler. For example, on \UNIX{}, this mayresult 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 usersshould 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 touse it. End-users will typically want to install the module, they do so byrunning \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 sourcedistribution; this is done through a \file{MANIFEST.in} file; see thedistutils documentation for details. If the source distribution has been build successfully, maintainerscan also create binary distributions. Depending on the platform, oneof the following commands can be used to do so. \begin{verbatim}python setup.py bdist_wininstpython setup.py bdist_rpmpython setup.py bdist_dumb\end{verbatim}