compiling.rst 8.94 KB
Newer Older
Wenzel Jakob's avatar
Wenzel Jakob committed
1
2
3
4
5
6
7
8
9
Build systems
#############

Building with setuptools
========================

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
Wenzel Jakob's avatar
Wenzel Jakob committed
10
the [python_example]_ repository.
Wenzel Jakob's avatar
Wenzel Jakob committed
11

Wenzel Jakob's avatar
Wenzel Jakob committed
12
.. [python_example] https://github.com/pybind/python_example
Wenzel Jakob's avatar
Wenzel Jakob committed
13

14
15
16
Building with cppimport
========================

Dean Moldovan's avatar
Dean Moldovan committed
17
18
19
20
[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.
21
22
23

.. [cppimport] https://github.com/tbenthompson/cppimport

24
25
26
27
28
.. _cmake:

Building with CMake
===================

Wenzel Jakob's avatar
Wenzel Jakob committed
29
For C++ codebases that have an existing CMake-based build system, a Python
30
extension module can be created with just a few lines of code:
31
32
33

.. code-block:: cmake

34
    cmake_minimum_required(VERSION 2.8.12)
35
36
    project(example)

37
38
39
    add_subdirectory(pybind11)
    pybind11_add_module(example example.cpp)

Wenzel Jakob's avatar
Wenzel Jakob committed
40
This assumes that the pybind11 repository is located in a subdirectory named
41
:file:`pybind11` and that the code is located in a file named :file:`example.cpp`.
42
43
44
The CMake command ``add_subdirectory`` will import the pybind11 project which
provides the ``pybind11_add_module`` function. It will take care of all the
details needed to build a Python extension module on any platform.
45
46
47
48

A working sample project, including a way to invoke CMake from :file:`setup.py` for
PyPI integration, can be found in the [cmake_example]_  repository.

Wenzel Jakob's avatar
Wenzel Jakob committed
49
.. [cmake_example] https://github.com/pybind/cmake_example
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
pybind11_add_module
-------------------

To ease the creation of Python extension modules, pybind11 provides a CMake
function with the following signature:

.. code-block:: cmake

    pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL]
                        [NO_EXTRAS] [THIN_LTO] source1 [source2 ...])

This function behaves very much like CMake's builtin ``add_library`` (in fact,
it's a wrapper function around that command). It will add a library target
called ``<name>`` 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
``<name>`` can be further manipulated with regular CMake commands.

``MODULE`` or ``SHARED`` may be given to specify the type of library. If no
type is given, ``MODULE`` is used by default which ensures the creation of a
Python-exclusive module. Specifying ``SHARED`` will create a more traditional
dynamic library which can also be linked from elsewhere. ``EXCLUDE_FROM_ALL``
removes this target from the default build (see CMake docs for details).

Since pybind11 is a template library, ``pybind11_add_module`` adds compiler
flags to ensure high quality code generation without bloat arising from long
77
78
79
80
81
82
83
84
85
symbol names and duplication of code in different translation units. It
sets default visibility to *hidden*, which is required for some pybind11
features and functionality when attempting to load multiple pybind11 modules
compiled under different pybind11 versions.  It also adds additional flags
enabling LTO (Link Time Optimization) and strip unneeded symbols. See the
:ref:`FAQ entry <faq:symhidden>` for a more detailed explanation. These
latter optimizations are never applied in ``Debug`` mode.  If ``NO_EXTRAS`` is
given, they will always be disabled, even in ``Release`` mode. However, this
will result in code bloat and is generally not recommended.
86
87
88
89
90
91
92
93
94
95
96

As stated above, LTO is enabled by default. Some newer compilers also support
different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause
the function to prefer this flavor if available. The function falls back to
regular LTO if ``-flto=thin`` is not available.

.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html

Configuration variables
-----------------------

97
98
99
100
101
102
By default, pybind11 will compile modules with the C++14 standard, if available
on the target compiler, falling back to C++11 if C++14 support is not
available.  Note, however, that this default is subject to change: future
pybind11 releases are expected to migrate to newer C++ standards as they become
available.  To override this, the standard flag can be given explicitly in
``PYBIND11_CPP_STANDARD``:
103
104
105

.. code-block:: cmake

106
107
    # Use just one of these:
    # GCC/clang:
108
    set(PYBIND11_CPP_STANDARD -std=c++11)
109
110
111
112
113
114
    set(PYBIND11_CPP_STANDARD -std=c++14)
    set(PYBIND11_CPP_STANDARD -std=c++1z) # Experimental C++17 support
    # MSVC:
    set(PYBIND11_CPP_STANDARD /std:c++14)
    set(PYBIND11_CPP_STANDARD /std:c++latest) # Enables some MSVC C++17 features

115
116
117
    add_subdirectory(pybind11)  # or find_package(pybind11)

Note that this and all other configuration variables must be set **before** the
118
call to ``add_subdirectory`` or ``find_package``. The variables can also be set
119
120
121
122
123
when calling CMake from the command line using the ``-D<variable>=<value>`` flag.

The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION``
or an exact Python installation can be specified with ``PYTHON_EXECUTABLE``.
For example:
124

125
126
127
128
129
130
131
132
133
134
135
136
.. code-block:: bash

    cmake -DPYBIND11_PYTHON_VERSION=3.6 ..
    # or
    cmake -DPYTHON_EXECUTABLE=path/to/python ..

find_package vs. add_subdirectory
---------------------------------

For CMake-based projects that don't include the pybind11 repository internally,
an external installation can be detected through ``find_package(pybind11)``.
See the `Config file`_ docstring for details of relevant CMake variables.
137
138
139
140
141
142
143
144
145

.. code-block:: cmake

    cmake_minimum_required(VERSION 2.8.12)
    project(example)

    find_package(pybind11 REQUIRED)
    pybind11_add_module(example example.cpp)

146
147
148
149
150
151
152
153
154
155
Once detected, the aforementioned ``pybind11_add_module`` 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 [cmake_example]_ repository for a full sample project
-- just swap out ``add_subdirectory`` for ``find_package``.

.. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in

Advanced: interface library target
----------------------------------
156

157
When using a version of CMake greater than 3.0, pybind11 can additionally
158
be used as a special *interface library* . The target ``pybind11::module``
159
160
161
162
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 ``add_library``, not
``pybind11_add_module``) target in the consuming project.
163
164
165
166
167
168

.. code-block:: cmake

    cmake_minimum_required(VERSION 3.0)
    project(example)

169
    find_package(pybind11 REQUIRED)  # or add_subdirectory(pybind11)
170

171
    add_library(example MODULE main.cpp)
172
    target_link_libraries(example PRIVATE pybind11::module)
173
174
175
176
177
178
179
180
181
182
183
184
185
    set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
                                             SUFFIX "${PYTHON_MODULE_EXTENSION}")

.. warning::

    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 ``pybind11_add_module()`` command, the CMake interface
    library only provides the *minimal* set of parameters to ensure that the
    code using pybind11 compiles, but it does **not** pass these extra compiler
    flags (i.e. this is up to you).

    These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
186
187
    and ``/LTCG`` on Visual Studio) and .OBJ files with many sections on Visual
    Studio (``/bigobj``).  The :ref:`FAQ <faq:symhidden>` contains an
188
    explanation on why these are needed.
189

190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
Embedding the Python interpreter
--------------------------------

In addition to extension modules, pybind11 also supports embedding Python into
a C++ executable or library. In CMake, simply link with the ``pybind11::embed``
target. It provides everything needed to get the interpreter running. The Python
headers and libraries are attached to the target. Unlike ``pybind11::module``,
there is no need to manually set any additional properties here. For more
information about usage in C++, see :doc:`/advanced/embedding`.

.. code-block:: cmake

    cmake_minimum_required(VERSION 3.0)
    project(example)

    find_package(pybind11 REQUIRED)  # or add_subdirectory(pybind11)

207
    add_executable(example main.cpp)
208
209
210
    target_link_libraries(example PRIVATE pybind11::embed)


211
212
213
214
215
216
217
218
Generating binding code automatically
=====================================

The ``Binder`` project is a tool for automatic generation of pybind11 binding
code by introspecting existing C++ codebases using LLVM/Clang. See the
[binder]_ documentation for details.

.. [binder] http://cppbinder.readthedocs.io/en/latest/about.html