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 — Python 3.5.1 documentation</title>
11
<link rel="stylesheet" href="../_static/pydoctheme.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 3.5.1 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 3.5.1 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">3.5.1</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">
77
<span id="building"></span><h1>3. Building C and C++ Extensions<a class="headerlink" href="#building-c-and-c-extensions" title="Permalink to this headline">¶</a></h1>
78
<p>A C extension for CPython is a shared library (e.g. a <code class="docutils literal"><span class="pre">.so</span></code> file on Linux,
79
<code class="docutils literal"><span class="pre">.pyd</span></code> on Windows), which exports an <em>initialization function</em>.</p>
80
<p>To be importable, the shared library must be available on <span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal"><span class="pre">PYTHONPATH</span></code></a>,
81
and must be named after the module name, with an appropriate extension.
82
When using distutils, the correct filename is generated automatically.</p>
83
<p>The initialization function has the signature:</p>
85
<dt id="c.PyInit_modulename">
86
<a class="reference internal" href="../c-api/structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyInit_modulename</code><span class="sig-paren">(</span>void<span class="sig-paren">)</span><a class="headerlink" href="#c.PyInit_modulename" title="Permalink to this definition">¶</a></dt>
89
<p>It returns either a fully-initialized module, or a <a class="reference internal" href="../c-api/module.html#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal"><span class="pre">PyModuleDef</span></code></a>
90
instance. See <a class="reference internal" href="../c-api/module.html#initializing-modules"><span>Initializing C modules</span></a> for details.</p>
91
<p>For modules with ASCII-only names, the function must be named
92
<code class="docutils literal"><span class="pre">PyInit_<modulename></span></code>, with <code class="docutils literal"><span class="pre"><modulename></span></code> replaced by the name of the
93
module. When using <a class="reference internal" href="../c-api/module.html#multi-phase-initialization"><span>Multi-phase initialization</span></a>, non-ASCII module names
94
are allowed. In this case, the initialization function name is
95
<code class="docutils literal"><span class="pre">PyInitU_<modulename></span></code>, with <code class="docutils literal"><span class="pre"><modulename></span></code> encoded using Python’s
96
<em>punycode</em> encoding with hyphens replaced by underscores. In Python:</p>
97
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">initfunc_name</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
98
<span class="k">try</span><span class="p">:</span>
99
<span class="n">suffix</span> <span class="o">=</span> <span class="n">b</span><span class="s1">'_'</span> <span class="o">+</span> <span class="n">name</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s1">'ascii'</span><span class="p">)</span>
100
<span class="k">except</span> <span class="ne">UnicodeEncodeError</span><span class="p">:</span>
101
<span class="n">suffix</span> <span class="o">=</span> <span class="n">b</span><span class="s1">'U_'</span> <span class="o">+</span> <span class="n">name</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s1">'punycode'</span><span class="p">)</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">b</span><span class="s1">'-'</span><span class="p">,</span> <span class="n">b</span><span class="s1">'_'</span><span class="p">)</span>
102
<span class="k">return</span> <span class="n">b</span><span class="s1">'PyInit'</span> <span class="o">+</span> <span class="n">suffix</span>
105
<p>It is possible to export multiple modules from a single shared library by
106
defining multiple initialization functions. However, importing them requires
107
using symbolic links or a custom importer, because by default only the
108
function corresponding to the filename is found.
109
See <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0489#multiple-modules-in-one-library"><strong>PEP 489#multiple-modules-in-one-library</strong></a> for details.</p>
110
<div class="section" id="building-c-and-c-extensions-with-distutils">
111
<h2>3.1. Building C and C++ Extensions with distutils<a class="headerlink" href="#building-c-and-c-extensions-with-distutils" title="Permalink to this headline">¶</a></h2>
112
<p>Extension modules can be built using distutils, which is included in Python.
113
Since distutils also supports creation of binary packages, users don’t
114
necessarily need a compiler and distutils to install the extension.</p>
115
<p>A distutils package contains a driver script, <code class="file docutils literal"><span class="pre">setup.py</span></code>. This is a plain
116
Python file, which, in the most simple case, could look like this:</p>
117
<div class="highlight-c"><div class="highlight"><pre>from distutils.core import setup, Extension
119
module1 = Extension('demo',
120
sources = ['demo.c'])
122
setup (name = 'PackageName',
123
version = '1.0',
124
description = 'This is a demo package',
125
ext_modules = [module1])
128
<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>
129
<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>
132
<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
133
the <code class="file docutils literal"><span class="pre">build</span></code> directory. Depending on the system, the module file will end
134
up in a subdirectory <code class="file docutils literal"><span class="pre">build/lib.system</span></code>, and may have a name like
135
<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>
136
<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>
137
function. This takes a variable number of keyword arguments, of which the
138
example above uses only a subset. Specifically, the example specifies
139
meta-information to build packages, and it specifies the contents of the
140
package. Normally, a package will contain additional modules, like Python
141
source modules, documentation, subpackages, etc. Please refer to the distutils
142
documentation in <a class="reference internal" href="../distutils/index.html#distutils-index"><span>Distributing Python Modules (Legacy version)</span></a> to learn more about the features of
143
distutils; this section explains building extension modules only.</p>
144
<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
145
driver script. In the example above, the <code class="docutils literal"><span class="pre">ext_modules</span></code> argument to
146
<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
147
the <code class="xref py py-class docutils literal"><span class="pre">Extension</span></code>. In the example, the instance
148
defines an extension named <code class="docutils literal"><span class="pre">demo</span></code> which is build by compiling a single source
149
file, <code class="file docutils literal"><span class="pre">demo.c</span></code>.</p>
150
<p>In many cases, building an extension is more complex, since additional
151
preprocessor defines and libraries may be needed. This is demonstrated in the
153
<div class="highlight-c"><div class="highlight"><pre>from distutils.core import setup, Extension
155
module1 = Extension('demo',
156
define_macros = [('MAJOR_VERSION', '1'),
157
('MINOR_VERSION', '0')],
158
include_dirs = ['/usr/local/include'],
159
libraries = ['tcl83'],
160
library_dirs = ['/usr/local/lib'],
161
sources = ['demo.c'])
163
setup (name = 'PackageName',
164
version = '1.0',
165
description = 'This is a demo package',
166
author = 'Martin v. Loewis',
167
author_email = 'martin@v.loewis.de',
168
url = 'https://docs.python.org/extending/building',
169
long_description = '''
170
This is really just a demo package.
172
ext_modules = [module1])
175
<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
176
is recommended when distribution packages have to be built. For the extension
177
itself, it specifies preprocessor defines, include directories, library
178
directories, and libraries. Depending on the compiler, distutils passes this
179
information in different ways to the compiler. For example, on Unix, this may
180
result in the compilation commands</p>
181
<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>
183
<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>
186
<p>These lines are for demonstration purposes only; distutils users should trust
187
that distutils gets the invocations right.</p>
189
<div class="section" id="distributing-your-extension-modules">
190
<span id="distributing"></span><h2>3.2. Distributing your extension modules<a class="headerlink" href="#distributing-your-extension-modules" title="Permalink to this headline">¶</a></h2>
191
<p>When an extension has been successfully build, there are three ways to use it.</p>
192
<p>End-users will typically want to install the module, they do so by running</p>
193
<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>
196
<p>Module maintainers should produce source packages; to do so, they run</p>
197
<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>
200
<p>In some cases, additional files need to be included in a source distribution;
201
this is done through a <code class="file docutils literal"><span class="pre">MANIFEST.in</span></code> file; see the distutils documentation
203
<p>If the source distribution has been build successfully, maintainers can also
204
create binary distributions. Depending on the platform, one of the following
205
commands can be used to do so.</p>
206
<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>
207
<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>
208
<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>
218
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
219
<div class="sphinxsidebarwrapper">
220
<h3><a href="../contents.html">Table Of Contents</a></h3>
222
<li><a class="reference internal" href="#">3. Building C and C++ Extensions</a><ul>
223
<li><a class="reference internal" href="#building-c-and-c-extensions-with-distutils">3.1. Building C and C++ Extensions with distutils</a></li>
224
<li><a class="reference internal" href="#distributing-your-extension-modules">3.2. Distributing your extension modules</a></li>
229
<h4>Previous topic</h4>
230
<p class="topless"><a href="newtypes.html"
231
title="previous chapter">2. Defining New Types</a></p>
233
<p class="topless"><a href="windows.html"
234
title="next chapter">4. Building C and C++ Extensions on Windows</a></p>
236
<ul class="this-page-menu">
237
<li><a href="../bugs.html">Report a Bug</a></li>
238
<li><a href="../_sources/extending/building.txt"
239
rel="nofollow">Show Source</a></li>
242
<div id="searchbox" style="display: none" role="search">
243
<h3>Quick search</h3>
244
<form class="search" action="../search.html" method="get">
245
<input type="text" name="q" />
246
<input type="submit" value="Go" />
247
<input type="hidden" name="check_keywords" value="yes" />
248
<input type="hidden" name="area" value="default" />
250
<p class="searchtip" style="font-size: 90%">
251
Enter search terms or a module, class or function name.
254
<script type="text/javascript">$('#searchbox').show(0);</script>
257
<div class="clearer"></div>
259
<div class="related" role="navigation" aria-label="related navigation">
262
<li class="right" style="margin-right: 10px">
263
<a href="../genindex.html" title="General Index"
266
<a href="../py-modindex.html" title="Python Module Index"
269
<a href="windows.html" title="4. Building C and C++ Extensions on Windows"
272
<a href="newtypes.html" title="2. Defining New Types"
274
<li><img src="../_static/py.png" alt=""
275
style="vertical-align: middle; margin-top: -1px"/></li>
276
<li><a href="https://www.python.org/">Python</a> »</li>
278
<span class="version_switcher_placeholder">3.5.1</span>
279
<a href="../index.html">Documentation </a> »
282
<li class="nav-item nav-item-1"><a href="index.html" >Extending and Embedding the Python Interpreter</a> »</li>
286
© <a href="../copyright.html">Copyright</a> 1990-2016, Python Software Foundation.
288
The Python Software Foundation is a non-profit corporation.
289
<a href="https://www.python.org/psf/donations/">Please donate.</a>
291
Last updated on Jan 22, 2016.
292
<a href="../bugs.html">Found a bug</a>?
294
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.
b'\\ No newline at end of file'
added
removed
python-3.5.1-docs-html/extending/building.html
