3. Construire les extensions C et C++ avec distutils¶
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 extension modules can be built 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, setup.py
. This is a plain
Python file, which, in the most simple case, could look like this:
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])
Avec ce setup.py
et un fichier demo.c
, lancer :
python setup.py build
compilera demo.c
, et produira un module d’extension nommé demo
dans le dossier build
. En fonction du système, le fichier du module peut se retrouver dans build/lib.system
, et son nom peut être demo.py
ou demo.pyd
.
In the setup.py
, all execution is performed by calling the 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 Distributing Python Modules (Legacy version) to learn more about the features of
distutils; this section explains building extension modules only.
It is common to pre-compute arguments to setup()
, to better structure the
driver script. In the example above, theext_modules
argument to
setup()
is a list of extension modules, each of which is an instance of
the Extension
. In the example, the instance
defines an extension named demo
which is build by compiling a single source
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.
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 = 'https://docs.python.org/extending/building',
long_description = '''
This is really just a demo package.
''',
ext_modules = [module1])
In this example, 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
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
Ces lignes ne sont qu’à titre d’exemple, les utilisateurs de distutils doivent avoir confiance en distutils qui fera les appels correctement.
3.1. Distribuer vos modules d’extension¶
Lorsqu’une extension a été construite avec succès, il existe trois moyens de l’utiliser.
Typiquement, les utilisateurs vont vouloir installer le module, ils le font en exécutant :
python setup.py install
Les mainteneurs de modules voudront produire des paquets source, pour ce faire ils exécuteront :
python setup.py sdist
In some cases, additional files need to be included in a source distribution;
this is done through a MANIFEST.in
file; see the distutils documentation
for details.
Si la distribution source a été construite avec succès, les mainteneurs peuvent créer une distribution binaire. En fonction de la plateforme, une des commandes suivantes peut être utilisée.
python setup.py bdist_wininst
python setup.py bdist_rpm
python setup.py bdist_dumb