Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 27761f3

Browse files
loewisloewis
committed
Patch #500136: Update Update ext build documentation. 2.2.1 candidate.
1 parent 3921ff6 commit 27761f3

4 files changed

Lines changed: 148 additions & 190 deletions

File tree

‎Doc/ext/building.tex‎

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

‎Doc/ext/ext.tex‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ \chapter*{Front Matter\label{front}}
5252

5353
\input{extending}
5454
\input{newtypes}
55-
\input{unix}
55+
\input{building}
5656
\input{windows}
5757
\input{embedding}
5858

‎Doc/ext/unix.tex‎

Lines changed: 0 additions & 189 deletions
This file was deleted.

‎Doc/ext/windows.tex‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ \chapter{Building C and \Cpp{} Extensions on Windows
99
Python extensions and the \UNIX{} programmer interested in producing
1010
software which can be successfully built on both \UNIX{} and Windows.
1111

12+
Module authors are encouraged to use the distutils approach for
13+
building extension modules, instead of the one described in this
14+
section. You will still need the C compiler that was used to build
15+
Python; typically Microsoft Visual \Cpp.
1216

1317
\section{A Cookbook Approach \label{win-cookbook}}
1418

0 commit comments

Comments
 (0)