← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/extending/building.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/extending/building.rst
 
1
.. highlightlang:: c
 
2
 
 
3
 
 
4
.. _building:
 
5
 
 
6
********************************************
 
7
Building C and C++ Extensions with distutils
 
8
********************************************
 
9
 
 
10
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
 
11
 
 
12
 
 
13
Starting in Python 1.4, Python provides, on Unix, a special make file for
 
14
building make files for building dynamically-linked extensions and custom
 
15
interpreters.  Starting with Python 2.0, this mechanism (known as related to
 
16
Makefile.pre.in, and Setup files) is no longer supported. Building custom
 
17
interpreters was rarely used, and extension modules can be built using
 
18
distutils.
 
19
 
 
20
Building an extension module using distutils requires that distutils is
 
21
installed on the build machine, which is included in Python 2.x and available
 
22
separately for Python 1.5. Since distutils also supports creation of binary
 
23
packages, users don't necessarily need a compiler and distutils to install the
 
24
extension.
 
25
 
 
26
A distutils package contains a driver script, :file:`setup.py`. This is a plain
 
27
Python file, which, in the most simple case, could look like this::
 
28
 
 
29
   from distutils.core import setup, Extension
 
30
 
 
31
   module1 = Extension('demo',
 
32
                       sources = ['demo.c'])
 
33
 
 
34
   setup (name = 'PackageName',
 
35
          version = '1.0',
 
36
          description = 'This is a demo package',
 
37
          ext_modules = [module1])
 
38
 
 
39
 
 
40
With this :file:`setup.py`, and a file :file:`demo.c`, running ::
 
41
 
 
42
   python setup.py build 
 
43
 
 
44
will compile :file:`demo.c`, and produce an extension module named ``demo`` in
 
45
the :file:`build` directory. Depending on the system, the module file will end
 
46
up in a subdirectory :file:`build/lib.system`, and may have a name like
 
47
:file:`demo.so` or :file:`demo.pyd`.
 
48
 
 
49
In the :file:`setup.py`, all execution is performed by calling the ``setup``
 
50
function. This takes a variable number of keyword arguments, of which the
 
51
example above uses only a subset. Specifically, the example specifies
 
52
meta-information to build packages, and it specifies the contents of the
 
53
package.  Normally, a package will contain of addition modules, like Python
 
54
source modules, documentation, subpackages, etc. Please refer to the distutils
 
55
documentation in :ref:`distutils-index` to learn more about the features of
 
56
distutils; this section explains building extension modules only.
 
57
 
 
58
It is common to pre-compute arguments to :func:`setup`, to better structure the
 
59
driver script. In the example above, the\ ``ext_modules`` argument to
 
60
:func:`setup` is a list of extension modules, each of which is an instance of
 
61
the :class:`Extension`. In the example, the instance defines an extension named
 
62
``demo`` which is build by compiling a single source file, :file:`demo.c`.
 
63
 
 
64
In many cases, building an extension is more complex, since additional
 
65
preprocessor defines and libraries may be needed. This is demonstrated in the
 
66
example below. ::
 
67
 
 
68
   from distutils.core import setup, Extension
 
69
 
 
70
   module1 = Extension('demo',
 
71
                       define_macros = [('MAJOR_VERSION', '1'),
 
72
                                        ('MINOR_VERSION', '0')],
 
73
                       include_dirs = ['/usr/local/include'],
 
74
                       libraries = ['tcl83'],
 
75
                       library_dirs = ['/usr/local/lib'],
 
76
                       sources = ['demo.c'])
 
77
 
 
78
   setup (name = 'PackageName',
 
79
          version = '1.0',
 
80
          description = 'This is a demo package',
 
81
          author = 'Martin v. Loewis',
 
82
          author_email = 'martin@v.loewis.de',
 
83
          url = 'http://docs.python.org/extending/building',
 
84
          long_description = '''
 
85
   This is really just a demo package.
 
86
   ''',
 
87
          ext_modules = [module1])
 
88
 
 
89
 
 
90
In this example, :func:`setup` is called with additional meta-information, which
 
91
is recommended when distribution packages have to be built. For the extension
 
92
itself, it specifies preprocessor defines, include directories, library
 
93
directories, and libraries. Depending on the compiler, distutils passes this
 
94
information in different ways to the compiler. For example, on Unix, this may
 
95
result in the compilation commands ::
 
96
 
 
97
   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
 
98
 
 
99
   gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
 
100
 
 
101
These lines are for demonstration purposes only; distutils users should trust
 
102
that distutils gets the invocations right.
 
103
 
 
104
 
 
105
.. _distributing:
 
106
 
 
107
Distributing your extension modules
 
108
===================================
 
109
 
 
110
When an extension has been successfully build, there are three ways to use it.
 
111
 
 
112
End-users will typically want to install the module, they do so by running ::
 
113
 
 
114
   python setup.py install
 
115
 
 
116
Module maintainers should produce source packages; to do so, they run ::
 
117
 
 
118
   python setup.py sdist
 
119
 
 
120
In some cases, additional files need to be included in a source distribution;
 
121
this is done through a :file:`MANIFEST.in` file; see the distutils documentation
 
122
for details.
 
123
 
 
124
If the source distribution has been build successfully, maintainers can also
 
125
create binary distributions. Depending on the platform, one of the following
 
126
commands can be used to do so. ::
 
127
 
 
128
   python setup.py bdist_wininst
 
129
   python setup.py bdist_rpm
 
130
   python setup.py bdist_dumb
 
131