pybind11-doc 2.0.1-4 / usr / share / doc / pybind11-doc / html / compiling.html

This file is indexed.

/usr/share/doc/pybind11-doc/html/compiling.html is in pybind11-doc 2.0.1-4.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Build systems &mdash; pybind11 2.0.1 documentation</title>
  

  
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  
    <link rel="stylesheet" href="_static/theme_overrides.css" type="text/css" />
  

  
        <link rel="index" title="Index"
              href="genindex.html"/>
        <link rel="search" title="Search" href="search.html"/>
    <link rel="top" title="pybind11 2.0.1 documentation" href="index.html"/>
        <link rel="next" title="Functions" href="advanced/functions.html"/>
        <link rel="prev" title="Object-oriented code" href="classes.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="index.html" class="icon icon-home"> pybind11
          

          
          </a>

          
            
            
              <div class="version">
                2.0
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul>
<li class="toctree-l1"><a class="reference internal" href="intro.html">About this project</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
</ul>
<p class="caption"><span class="caption-text">The Basics</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="basics.html">First steps</a></li>
<li class="toctree-l1"><a class="reference internal" href="classes.html">Object-oriented code</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Build systems</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#building-with-setuptools">Building with setuptools</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-with-cppimport">Building with cppimport</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-with-cmake">Building with CMake</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#pybind11-add-module">pybind11_add_module</a></li>
<li class="toctree-l3"><a class="reference internal" href="#configuration-variables">Configuration variables</a></li>
<li class="toctree-l3"><a class="reference internal" href="#find-package-vs-add-subdirectory">find_package vs. add_subdirectory</a></li>
<li class="toctree-l3"><a class="reference internal" href="#advanced-interface-library-target">Advanced: interface library target</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#generating-binding-code-automatically">Generating binding code automatically</a></li>
</ul>
</li>
</ul>
<p class="caption"><span class="caption-text">Advanced Topics</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="advanced/functions.html">Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced/classes.html">Classes</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced/exceptions.html">Exceptions</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced/smart_ptrs.html">Smart pointers</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced/cast/index.html">Type conversions</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced/pycpp/index.html">Python C++ interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced/misc.html">Miscellaneous</a></li>
</ul>
<p class="caption"><span class="caption-text">Extra Information</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently asked questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="benchmark.html">Benchmark</a></li>
<li class="toctree-l1"><a class="reference internal" href="limitations.html">Limitations</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">pybind11</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="index.html">Docs</a> &raquo;</li>
        
      <li>Build systems</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/compiling.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="build-systems">
<h1>Build systems<a class="headerlink" href="#build-systems" title="Permalink to this headline"></a></h1>
<div class="section" id="building-with-setuptools">
<h2>Building with setuptools<a class="headerlink" href="#building-with-setuptools" title="Permalink to this headline"></a></h2>
<p>For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay
has kindly provided an example project which shows how to set up everything,
including automatic generation of documentation using Sphinx. Please refer to
the <a class="reference internal" href="#python-example" id="id1">[python_example]</a> repository.</p>
<table class="docutils citation" frame="void" id="python-example" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[python_example]</a></td><td><a class="reference external" href="https://github.com/pybind/python_example">https://github.com/pybind/python_example</a></td></tr>
</tbody>
</table>
</div>
<div class="section" id="building-with-cppimport">
<h2>Building with cppimport<a class="headerlink" href="#building-with-cppimport" title="Permalink to this headline"></a></h2>
<blockquote>
<div>cppimport is a small Python import hook that determines whether there is a C++
source file whose name matches the requested module. If there is, the file is
compiled as a Python extension using pybind11 and placed in the same folder as
the C++ source file. Python is then able to find the module and load it.</div></blockquote>
<table class="docutils citation" frame="void" id="cppimport" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[cppimport]</td><td><a class="reference external" href="https://github.com/tbenthompson/cppimport">https://github.com/tbenthompson/cppimport</a></td></tr>
</tbody>
</table>
</div>
<div class="section" id="building-with-cmake">
<span id="cmake"></span><h2>Building with CMake<a class="headerlink" href="#building-with-cmake" title="Permalink to this headline"></a></h2>
<p>For C++ codebases that have an existing CMake-based build system, a Python
extension module can be created with just a few lines of code:</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">cmake_minimum_required</span><span class="p">(</span><span class="s">VERSION</span> <span class="s">2.8.12</span><span class="p">)</span>
<span class="nb">project</span><span class="p">(</span><span class="s">example</span><span class="p">)</span>

<span class="nb">add_subdirectory</span><span class="p">(</span><span class="s">pybind11</span><span class="p">)</span>
<span class="nb">pybind11_add_module</span><span class="p">(</span><span class="s">example</span> <span class="s">example.cpp</span><span class="p">)</span>
</pre></div>
</div>
<p>This assumes that the pybind11 repository is located in a subdirectory named
<code class="file docutils literal"><span class="pre">pybind11</span></code> and that the code is located in a file named <code class="file docutils literal"><span class="pre">example.cpp</span></code>.
The CMake command <code class="docutils literal"><span class="pre">add_subdirectory</span></code> will import the pybind11 project which
provides the <code class="docutils literal"><span class="pre">pybind11_add_module</span></code> function. It will take care of all the
details needed to build a Python extension module on any platform.</p>
<p>A working sample project, including a way to invoke CMake from <code class="file docutils literal"><span class="pre">setup.py</span></code> for
PyPI integration, can be found in the <a class="reference internal" href="#cmake-example" id="id2">[cmake_example]</a>  repository.</p>
<table class="docutils citation" frame="void" id="cmake-example" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[cmake_example]</td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> <a class="reference external" href="https://github.com/pybind/cmake_example">https://github.com/pybind/cmake_example</a></td></tr>
</tbody>
</table>
<div class="section" id="pybind11-add-module">
<h3>pybind11_add_module<a class="headerlink" href="#pybind11-add-module" title="Permalink to this headline"></a></h3>
<p>To ease the creation of Python extension modules, pybind11 provides a CMake
function with the following signature:</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">pybind11_add_module</span><span class="p">(</span><span class="s">&lt;name&gt;</span> <span class="s">[MODULE</span> <span class="s">|</span> <span class="s">SHARED]</span> <span class="s">[EXCLUDE_FROM_ALL]</span>
                    <span class="s">[NO_EXTRAS]</span> <span class="s">[THIN_LTO]</span> <span class="s">source1</span> <span class="s">[source2</span> <span class="s">...]</span><span class="p">)</span>
</pre></div>
</div>
<p>This function behaves very much like CMake&#8217;s builtin <code class="docutils literal"><span class="pre">add_library</span></code> (in fact,
it&#8217;s a wrapper function around that command). It will add a library target
called <code class="docutils literal"><span class="pre">&lt;name&gt;</span></code> to be built from the listed source files. In addition, it
will take care of all the Python-specific compiler and linker flags as well
as the OS- and Python-version-specific file extension. The produced target
<code class="docutils literal"><span class="pre">&lt;name&gt;</span></code> can be further manipulated with regular CMake commands.</p>
<p><code class="docutils literal"><span class="pre">MODULE</span></code> or <code class="docutils literal"><span class="pre">SHARED</span></code> may be given to specify the type of library. If no
type is given, <code class="docutils literal"><span class="pre">MODULE</span></code> is used by default which ensures the creation of a
Python-exclusive module. Specifying <code class="docutils literal"><span class="pre">SHARED</span></code> will create a more traditional
dynamic library which can also be linked from elsewhere. <code class="docutils literal"><span class="pre">EXCLUDE_FROM_ALL</span></code>
removes this target from the default build (see CMake docs for details).</p>
<p>Since pybind11 is a template library, <code class="docutils literal"><span class="pre">pybind11_add_module</span></code> adds compiler
flags to ensure high quality code generation without bloat arising from long
symbol names and duplication of code in different translation units. The
additional flags enable LTO (Link Time Optimization), set default visibility
to <em>hidden</em> and strip unneeded symbols. See the <a class="reference internal" href="faq.html#faq-symhidden"><span class="std std-ref">FAQ entry</span></a>
for a more detailed explanation. These optimizations are never applied in
<code class="docutils literal"><span class="pre">Debug</span></code> mode. If <code class="docutils literal"><span class="pre">NO_EXTRAS</span></code> is given, they will always be disabled, even
in <code class="docutils literal"><span class="pre">Release</span></code> mode. However, this will result in code bloat and is generally
not recommended.</p>
<p>As stated above, LTO is enabled by default. Some newer compilers also support
different flavors of LTO such as <a class="reference external" href="http://clang.llvm.org/docs/ThinLTO.html">ThinLTO</a>. Setting <code class="docutils literal"><span class="pre">THIN_LTO</span></code> will cause
the function to prefer this flavor if available. The function falls back to
regular LTO if <code class="docutils literal"><span class="pre">-flto=thin</span></code> is not available.</p>
</div>
<div class="section" id="configuration-variables">
<h3>Configuration variables<a class="headerlink" href="#configuration-variables" title="Permalink to this headline"></a></h3>
<p>By default, pybind11 will compile modules with the latest C++ standard
available on the target compiler. To override this, the standard flag can
be given explicitly in <code class="docutils literal"><span class="pre">PYBIND11_CPP_STANDARD</span></code>:</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">set</span><span class="p">(</span><span class="s">PYBIND11_CPP_STANDARD</span> <span class="s">-std=c++11</span><span class="p">)</span>
<span class="nb">add_subdirectory</span><span class="p">(</span><span class="s">pybind11</span><span class="p">)</span>  <span class="c"># or find_package(pybind11)</span>
</pre></div>
</div>
<p>Note that this and all other configuration variables must be set <strong>before</strong> the
call to <code class="docutils literal"><span class="pre">add_subdiretory</span></code> or <code class="docutils literal"><span class="pre">find_package</span></code>. The variables can also be set
when calling CMake from the command line using the <code class="docutils literal"><span class="pre">-D&lt;variable&gt;=&lt;value&gt;</span></code> flag.</p>
<p>The target Python version can be selected by setting <code class="docutils literal"><span class="pre">PYBIND11_PYTHON_VERSION</span></code>
or an exact Python installation can be specified with <code class="docutils literal"><span class="pre">PYTHON_EXECUTABLE</span></code>.
For example:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>cmake -DPYBIND11_PYTHON_VERSION<span class="o">=</span><span class="m">3</span>.6 ..
<span class="c1"># or</span>
cmake -DPYTHON_EXECUTABLE<span class="o">=</span>path/to/python ..
</pre></div>
</div>
</div>
<div class="section" id="find-package-vs-add-subdirectory">
<h3>find_package vs. add_subdirectory<a class="headerlink" href="#find-package-vs-add-subdirectory" title="Permalink to this headline"></a></h3>
<p>For CMake-based projects that don&#8217;t include the pybind11 repository internally,
an external installation can be detected through <code class="docutils literal"><span class="pre">find_package(pybind11)</span></code>.
See the <a class="reference external" href="https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in">Config file</a> docstring for details of relevant CMake variables.</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">cmake_minimum_required</span><span class="p">(</span><span class="s">VERSION</span> <span class="s">2.8.12</span><span class="p">)</span>
<span class="nb">project</span><span class="p">(</span><span class="s">example</span><span class="p">)</span>

<span class="nb">find_package</span><span class="p">(</span><span class="s">pybind11</span> <span class="s">REQUIRED</span><span class="p">)</span>
<span class="nb">pybind11_add_module</span><span class="p">(</span><span class="s">example</span> <span class="s">example.cpp</span><span class="p">)</span>
</pre></div>
</div>
<p>Once detected, the aforementioned <code class="docutils literal"><span class="pre">pybind11_add_module</span></code> can be employed as
before. The function usage and configuration variables are identical no matter
if pybind11 is added as a subdirectory or found as an installed package. You
can refer to the same <a class="reference internal" href="#cmake-example" id="id3">[cmake_example]</a> repository for a full sample project
&#8211; just swap out <code class="docutils literal"><span class="pre">add_subdirectory</span></code> for <code class="docutils literal"><span class="pre">find_package</span></code>.</p>
</div>
<div class="section" id="advanced-interface-library-target">
<h3>Advanced: interface library target<a class="headerlink" href="#advanced-interface-library-target" title="Permalink to this headline"></a></h3>
<p>When using a version of CMake greater than 3.0, pybind11 can additionally
be used as a special <em>interface library</em> . The target <code class="docutils literal"><span class="pre">pybind11::module</span></code>
is available with pybind11 headers, Python headers and libraries as needed,
and C++ compile definitions attached. This target is suitable for linking
to an independently constructed (through <code class="docutils literal"><span class="pre">add_library</span></code>, not
<code class="docutils literal"><span class="pre">pybind11_add_module</span></code>) target in the consuming project.</p>
<div class="highlight-cmake"><div class="highlight"><pre><span></span><span class="nb">cmake_minimum_required</span><span class="p">(</span><span class="s">VERSION</span> <span class="s">3.0</span><span class="p">)</span>
<span class="nb">project</span><span class="p">(</span><span class="s">example</span><span class="p">)</span>

<span class="nb">find_package</span><span class="p">(</span><span class="s">pybind11</span> <span class="s">REQUIRED</span><span class="p">)</span>  <span class="c"># or add_subdirectory(pybind11)</span>

<span class="nb">add_library</span><span class="p">(</span><span class="s">example</span> <span class="s">MODULE</span> <span class="s">main.cpp</span><span class="p">)</span>
<span class="nb">target_link_libraries</span><span class="p">(</span><span class="s">example</span> <span class="s">PRIVATE</span> <span class="s">pybind11::module</span><span class="p">)</span>
<span class="nb">set_target_properties</span><span class="p">(</span><span class="s">example</span> <span class="s">PROPERTIES</span> <span class="s">PREFIX</span> <span class="s2">&quot;${PYTHON_MODULE_PREFIX}&quot;</span>
                                         <span class="s">SUFFIX</span> <span class="s2">&quot;${PYTHON_MODULE_EXTENSION}&quot;</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>Since pybind11 is a metatemplate library, it is crucial that certain
compiler flags are provided to ensure high quality code generation. In
contrast to the <code class="docutils literal"><span class="pre">pybind11_add_module()</span></code> command, the CMake interface
library only provides the <em>minimal</em> set of parameters to ensure that the
code using pybind11 compiles, but it does <strong>not</strong> pass these extra compiler
flags (i.e. this is up to you).</p>
<p class="last">These include Link Time Optimization (<code class="docutils literal"><span class="pre">-flto</span></code> on GCC/Clang/ICPC, <code class="docutils literal"><span class="pre">/GL</span></code>
and <code class="docutils literal"><span class="pre">/LTCG</span></code> on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC
(<code class="docutils literal"><span class="pre">-fvisibility=hidden</span></code>) and .OBJ files with many sections on Visual Studio
(<code class="docutils literal"><span class="pre">/bigobj</span></code>). The <a class="reference internal" href="faq.html#faq-symhidden"><span class="std std-ref">FAQ</span></a> contains an
explanation on why these are needed.</p>
</div>
</div>
</div>
<div class="section" id="generating-binding-code-automatically">
<h2>Generating binding code automatically<a class="headerlink" href="#generating-binding-code-automatically" title="Permalink to this headline"></a></h2>
<p>The <code class="docutils literal"><span class="pre">Binder</span></code> project is a tool for automatic generation of pybind11 binding
code by introspecting existing C++ codebases using LLVM/Clang. See the
<a class="reference internal" href="#binder" id="id4">[binder]</a> documentation for details.</p>
<table class="docutils citation" frame="void" id="binder" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[binder]</a></td><td><a class="reference external" href="http://cppbinder.readthedocs.io/en/latest/about.html">http://cppbinder.readthedocs.io/en/latest/about.html</a></td></tr>
</tbody>
</table>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="advanced/functions.html" class="btn btn-neutral float-right" title="Functions" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="classes.html" class="btn btn-neutral" title="Object-oriented code" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2017, Wenzel Jakob.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'2.0.1',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: '.txt'
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>

APT Browse - Built by Thomas Orozco.