From 5ab6d2bb373a63fdf2812bd1c619e7f5844f8868 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Fri, 15 Mar 2002 10:29:08 +0000 Subject: This commit was manufactured by cvs2svn to create branch 'release22-maint'. --- Doc/ext/building.tex | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 Doc/ext/building.tex 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} + -- cgit v0.12