1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
<html xmlns="http://www.w3.org/1999/xhtml">
7
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
9
<title>3. Building C and C++ Extensions with distutils — Python 2.7.11 documentation</title>
11
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
12
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
14
<script type="text/javascript">
15
var DOCUMENTATION_OPTIONS = {
18
COLLAPSE_INDEX: false,
23
<script type="text/javascript" src="../_static/jquery.js"></script>
24
<script type="text/javascript" src="../_static/underscore.js"></script>
25
<script type="text/javascript" src="../_static/doctools.js"></script>
26
<script type="text/javascript" src="../_static/sidebar.js"></script>
27
<link rel="search" type="application/opensearchdescription+xml"
28
title="Search within Python 2.7.11 documentation"
29
href="../_static/opensearch.xml"/>
30
<link rel="author" title="About these documents" href="../about.html" />
31
<link rel="copyright" title="Copyright" href="../copyright.html" />
32
<link rel="top" title="Python 2.7.11 documentation" href="../contents.html" />
33
<link rel="up" title="Extending and Embedding the Python Interpreter" href="index.html" />
34
<link rel="next" title="4. Building C and C++ Extensions on Windows" href="windows.html" />
35
<link rel="prev" title="2. Defining New Types" href="newtypes.html" />
36
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
37
<script type="text/javascript" src="../_static/copybutton.js"></script>
38
<script type="text/javascript" src="../_static/version_switch.js"></script>
43
<body role="document">
44
<div class="related" role="navigation" aria-label="related navigation">
47
<li class="right" style="margin-right: 10px">
48
<a href="../genindex.html" title="General Index"
49
accesskey="I">index</a></li>
51
<a href="../py-modindex.html" title="Python Module Index"
54
<a href="windows.html" title="4. Building C and C++ Extensions on Windows"
55
accesskey="N">next</a> |</li>
57
<a href="newtypes.html" title="2. Defining New Types"
58
accesskey="P">previous</a> |</li>
59
<li><img src="../_static/py.png" alt=""
60
style="vertical-align: middle; margin-top: -1px"/></li>
61
<li><a href="https://www.python.org/">Python</a> »</li>
63
<span class="version_switcher_placeholder">2.7.11</span>
64
<a href="../index.html">Documentation</a> »
67
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Extending and Embedding the Python Interpreter</a> »</li>
71
<div class="document">
72
<div class="documentwrapper">
73
<div class="bodywrapper">
74
<div class="body" role="main">
76
<div class="section" id="building-c-and-c-extensions-with-distutils">
77
<span id="building"></span><h1>3. Building C and C++ Extensions with distutils<a class="headerlink" href="#building-c-and-c-extensions-with-distutils" title="Permalink to this headline">¶</a></h1>
78
<p>Starting in Python 1.4, Python provides, on Unix, a special make file for
79
building make files for building dynamically-linked extensions and custom
80
interpreters. Starting with Python 2.0, this mechanism (known as related to
81
Makefile.pre.in, and Setup files) is no longer supported. Building custom
82
interpreters was rarely used, and extension modules can be built using
84
<p>Building an extension module using distutils requires that distutils is
85
installed on the build machine, which is included in Python 2.x and available
86
separately for Python 1.5. Since distutils also supports creation of binary
87
packages, users don’t necessarily need a compiler and distutils to install the
89
<p>A distutils package contains a driver script, <code class="file docutils literal"><span class="pre">setup.py</span></code>. This is a plain
90
Python file, which, in the most simple case, could look like this:</p>
91
<div class="highlight-c"><div class="highlight"><pre>from distutils.core import setup, Extension
93
module1 = Extension('demo',
94
sources = ['demo.c'])
96
setup (name = 'PackageName',
97
version = '1.0',
98
description = 'This is a demo package',
99
ext_modules = [module1])
102
<p>With this <code class="file docutils literal"><span class="pre">setup.py</span></code>, and a file <code class="file docutils literal"><span class="pre">demo.c</span></code>, running</p>
103
<div class="highlight-c"><div class="highlight"><pre><span class="n">python</span> <span class="n">setup</span><span class="p">.</span><span class="n">py</span> <span class="n">build</span>
106
<p>will compile <code class="file docutils literal"><span class="pre">demo.c</span></code>, and produce an extension module named <code class="docutils literal"><span class="pre">demo</span></code> in
107
the <code class="file docutils literal"><span class="pre">build</span></code> directory. Depending on the system, the module file will end
108
up in a subdirectory <code class="file docutils literal"><span class="pre">build/lib.system</span></code>, and may have a name like
109
<code class="file docutils literal"><span class="pre">demo.so</span></code> or <code class="file docutils literal"><span class="pre">demo.pyd</span></code>.</p>
110
<p>In the <code class="file docutils literal"><span class="pre">setup.py</span></code>, all execution is performed by calling the <code class="docutils literal"><span class="pre">setup</span></code>
111
function. This takes a variable number of keyword arguments, of which the
112
example above uses only a subset. Specifically, the example specifies
113
meta-information to build packages, and it specifies the contents of the
114
package. Normally, a package will contain of addition modules, like Python
115
source modules, documentation, subpackages, etc. Please refer to the distutils
116
documentation in <a class="reference internal" href="../distutils/index.html#distutils-index"><span>Distributing Python Modules</span></a> to learn more about the features of
117
distutils; this section explains building extension modules only.</p>
118
<p>It is common to pre-compute arguments to <code class="xref py py-func docutils literal"><span class="pre">setup()</span></code>, to better structure the
119
driver script. In the example above, the <code class="docutils literal"><span class="pre">ext_modules</span></code> argument to
120
<code class="xref py py-func docutils literal"><span class="pre">setup()</span></code> is a list of extension modules, each of which is an instance of
121
the <code class="xref py py-class docutils literal"><span class="pre">Extension</span></code>. In the example, the instance
122
defines an extension named <code class="docutils literal"><span class="pre">demo</span></code> which is build by compiling a single source
123
file, <code class="file docutils literal"><span class="pre">demo.c</span></code>.</p>
124
<p>In many cases, building an extension is more complex, since additional
125
preprocessor defines and libraries may be needed. This is demonstrated in the
127
<div class="highlight-c"><div class="highlight"><pre>from distutils.core import setup, Extension
129
module1 = Extension('demo',
130
define_macros = [('MAJOR_VERSION', '1'),
131
('MINOR_VERSION', '0')],
132
include_dirs = ['/usr/local/include'],
133
libraries = ['tcl83'],
134
library_dirs = ['/usr/local/lib'],
135
sources = ['demo.c'])
137
setup (name = 'PackageName',
138
version = '1.0',
139
description = 'This is a demo package',
140
author = 'Martin v. Loewis',
141
author_email = 'martin@v.loewis.de',
142
url = 'https://docs.python.org/extending/building',
143
long_description = '''
144
This is really just a demo package.
146
ext_modules = [module1])
149
<p>In this example, <code class="xref py py-func docutils literal"><span class="pre">setup()</span></code> is called with additional meta-information, which
150
is recommended when distribution packages have to be built. For the extension
151
itself, it specifies preprocessor defines, include directories, library
152
directories, and libraries. Depending on the compiler, distutils passes this
153
information in different ways to the compiler. For example, on Unix, this may
154
result in the compilation commands</p>
155
<div class="highlight-c"><div class="highlight"><pre><span class="n">gcc</span> <span class="o">-</span><span class="n">DNDEBUG</span> <span class="o">-</span><span class="n">g</span> <span class="o">-</span><span class="n">O3</span> <span class="o">-</span><span class="n">Wall</span> <span class="o">-</span><span class="n">Wstrict</span><span class="o">-</span><span class="n">prototypes</span> <span class="o">-</span><span class="n">fPIC</span> <span class="o">-</span><span class="n">DMAJOR_VERSION</span><span class="o">=</span><span class="mi">1</span> <span class="o">-</span><span class="n">DMINOR_VERSION</span><span class="o">=</span><span class="mi">0</span> <span class="o">-</span><span class="n">I</span><span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">include</span> <span class="o">-</span><span class="n">I</span><span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">include</span><span class="o">/</span><span class="n">python2</span><span class="mf">.2</span> <span class="o">-</span><span class="n">c</span> <span class="n">demo</span><span class="p">.</span><span class="n">c</span> <span class="o">-</span><span class="n">o</span> <span class="n">build</span><span class="o">/</span><span class="n">temp</span><span class="p">.</span><span class="n">linux</span><span class="o">-</span><span class="n">i686</span><span class="o">-</span><span class="mf">2.2</span><span class="o">/</span><span class="n">demo</span><span class="p">.</span><span class="n">o</span>
157
<span class="n">gcc</span> <span class="o">-</span><span class="n">shared</span> <span class="n">build</span><span class="o">/</span><span class="n">temp</span><span class="p">.</span><span class="n">linux</span><span class="o">-</span><span class="n">i686</span><span class="o">-</span><span class="mf">2.2</span><span class="o">/</span><span class="n">demo</span><span class="p">.</span><span class="n">o</span> <span class="o">-</span><span class="n">L</span><span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="n">lib</span> <span class="o">-</span><span class="n">ltcl83</span> <span class="o">-</span><span class="n">o</span> <span class="n">build</span><span class="o">/</span><span class="n">lib</span><span class="p">.</span><span class="n">linux</span><span class="o">-</span><span class="n">i686</span><span class="o">-</span><span class="mf">2.2</span><span class="o">/</span><span class="n">demo</span><span class="p">.</span><span class="n">so</span>
160
<p>These lines are for demonstration purposes only; distutils users should trust
161
that distutils gets the invocations right.</p>
162
<div class="section" id="distributing-your-extension-modules">
163
<span id="distributing"></span><h2>3.1. Distributing your extension modules<a class="headerlink" href="#distributing-your-extension-modules" title="Permalink to this headline">¶</a></h2>
164
<p>When an extension has been successfully build, there are three ways to use it.</p>
165
<p>End-users will typically want to install the module, they do so by running</p>
166
<div class="highlight-c"><div class="highlight"><pre><span class="n">python</span> <span class="n">setup</span><span class="p">.</span><span class="n">py</span> <span class="n">install</span>
169
<p>Module maintainers should produce source packages; to do so, they run</p>
170
<div class="highlight-c"><div class="highlight"><pre><span class="n">python</span> <span class="n">setup</span><span class="p">.</span><span class="n">py</span> <span class="n">sdist</span>
173
<p>In some cases, additional files need to be included in a source distribution;
174
this is done through a <code class="file docutils literal"><span class="pre">MANIFEST.in</span></code> file; see the distutils documentation
176
<p>If the source distribution has been build successfully, maintainers can also
177
create binary distributions. Depending on the platform, one of the following
178
commands can be used to do so.</p>
179
<div class="highlight-c"><div class="highlight"><pre><span class="n">python</span> <span class="n">setup</span><span class="p">.</span><span class="n">py</span> <span class="n">bdist_wininst</span>
180
<span class="n">python</span> <span class="n">setup</span><span class="p">.</span><span class="n">py</span> <span class="n">bdist_rpm</span>
181
<span class="n">python</span> <span class="n">setup</span><span class="p">.</span><span class="n">py</span> <span class="n">bdist_dumb</span>
191
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
192
<div class="sphinxsidebarwrapper">
193
<h3><a href="../contents.html">Table Of Contents</a></h3>
195
<li><a class="reference internal" href="#">3. Building C and C++ Extensions with distutils</a><ul>
196
<li><a class="reference internal" href="#distributing-your-extension-modules">3.1. Distributing your extension modules</a></li>
201
<h4>Previous topic</h4>
202
<p class="topless"><a href="newtypes.html"
203
title="previous chapter">2. Defining New Types</a></p>
205
<p class="topless"><a href="windows.html"
206
title="next chapter">4. Building C and C++ Extensions on Windows</a></p>
208
<ul class="this-page-menu">
209
<li><a href="../bugs.html">Report a Bug</a></li>
210
<li><a href="../_sources/extending/building.txt"
211
rel="nofollow">Show Source</a></li>
214
<div id="searchbox" style="display: none" role="search">
215
<h3>Quick search</h3>
216
<form class="search" action="../search.html" method="get">
217
<input type="text" name="q" />
218
<input type="submit" value="Go" />
219
<input type="hidden" name="check_keywords" value="yes" />
220
<input type="hidden" name="area" value="default" />
222
<p class="searchtip" style="font-size: 90%">
223
Enter search terms or a module, class or function name.
226
<script type="text/javascript">$('#searchbox').show(0);</script>
229
<div class="clearer"></div>
231
<div class="related" role="navigation" aria-label="related navigation">
234
<li class="right" style="margin-right: 10px">
235
<a href="../genindex.html" title="General Index"
238
<a href="../py-modindex.html" title="Python Module Index"
241
<a href="windows.html" title="4. Building C and C++ Extensions on Windows"
244
<a href="newtypes.html" title="2. Defining New Types"
246
<li><img src="../_static/py.png" alt=""
247
style="vertical-align: middle; margin-top: -1px"/></li>
248
<li><a href="https://www.python.org/">Python</a> »</li>
250
<span class="version_switcher_placeholder">2.7.11</span>
251
<a href="../index.html">Documentation</a> »
254
<li class="nav-item nav-item-1"><a href="index.html" >Extending and Embedding the Python Interpreter</a> »</li>
258
© <a href="../copyright.html">Copyright</a> 1990-2016, Python Software Foundation.
260
The Python Software Foundation is a non-profit corporation.
261
<a href="https://www.python.org/psf/donations/">Please donate.</a>
263
Last updated on Jan 23, 2016.
264
<a href="../bugs.html">Found a bug</a>?
266
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.
b'\\ No newline at end of file'
added
removed
python-2.7.11-docs-html/extending/building.html
