compiling.rst (11986:c12e4625ab56) compiling.rst (12037:d28054ac6ec9)
1Build systems
2#############
3
4Building with setuptools
5========================
6
7For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay
8has kindly provided an example project which shows how to set up everything,

--- 25 unchanged lines hidden (view full) ---

34 cmake_minimum_required(VERSION 2.8.12)
35 project(example)
36
37 add_subdirectory(pybind11)
38 pybind11_add_module(example example.cpp)
39
40This 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`.
1Build systems
2#############
3
4Building with setuptools
5========================
6
7For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay
8has kindly provided an example project which shows how to set up everything,

--- 25 unchanged lines hidden (view full) ---

34 cmake_minimum_required(VERSION 2.8.12)
35 project(example)
36
37 add_subdirectory(pybind11)
38 pybind11_add_module(example example.cpp)
39
40This 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`.
42The CMake command ``add_subdirectory`` will import a function with the signature
43``pybind11_add_module(<name> source1 [source2 ...])``. It will take care of all
44the details needed to build a Python extension module on any platform.
42The CMake command ``add_subdirectory`` will import the pybind11 project which
43provides the ``pybind11_add_module`` function. It will take care of all the
44details needed to build a Python extension module on any platform.
45
45
46The target Python version can be selected by setting the ``PYBIND11_PYTHON_VERSION``
47variable before adding the pybind11 subdirectory. Alternatively, an exact Python
48installation can be specified by setting ``PYTHON_EXECUTABLE``.
49
50A working sample project, including a way to invoke CMake from :file:`setup.py` for
51PyPI integration, can be found in the [cmake_example]_ repository.
52
53.. [cmake_example] https://github.com/pybind/cmake_example
54
46A working sample project, including a way to invoke CMake from :file:`setup.py` for
47PyPI integration, can be found in the [cmake_example]_ repository.
48
49.. [cmake_example] https://github.com/pybind/cmake_example
50
55For CMake-based projects that don't include the pybind11
56repository internally, an external installation can be detected
57through `find_package(pybind11 ... CONFIG ...)`. See the `Config file
58<https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in>`_
59docstring for details of relevant CMake variables.
51pybind11_add_module
52-------------------
60
53
61Once detected, and after setting any variables to guide Python and
62C++ standard detection, the aforementioned ``pybind11_add_module``
63wrapper to ``add_library`` can be employed as described above (after
64``include(pybind11Tools)``). This procedure is available when using CMake
65>= 2.8.12. A working example can be found at [test_installed_module]_ .
54To ease the creation of Python extension modules, pybind11 provides a CMake
55function with the following signature:
66
67.. code-block:: cmake
68
56
57.. code-block:: cmake
58
59 pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL]
60 [NO_EXTRAS] [THIN_LTO] source1 [source2 ...])
61
62This function behaves very much like CMake's builtin ``add_library`` (in fact,
63it's a wrapper function around that command). It will add a library target
64called ``<name>`` to be built from the listed source files. In addition, it
65will take care of all the Python-specific compiler and linker flags as well
66as the OS- and Python-version-specific file extension. The produced target
67``<name>`` can be further manipulated with regular CMake commands.
68
69``MODULE`` or ``SHARED`` may be given to specify the type of library. If no
70type is given, ``MODULE`` is used by default which ensures the creation of a
71Python-exclusive module. Specifying ``SHARED`` will create a more traditional
72dynamic library which can also be linked from elsewhere. ``EXCLUDE_FROM_ALL``
73removes this target from the default build (see CMake docs for details).
74
75Since pybind11 is a template library, ``pybind11_add_module`` adds compiler
76flags to ensure high quality code generation without bloat arising from long
77symbol names and duplication of code in different translation units. The
78additional flags enable LTO (Link Time Optimization), set default visibility
79to *hidden* and strip unneeded symbols. See the :ref:`FAQ entry <faq:symhidden>`
80for a more detailed explanation. These optimizations are never applied in
81``Debug`` mode. If ``NO_EXTRAS`` is given, they will always be disabled, even
82in ``Release`` mode. However, this will result in code bloat and is generally
83not recommended.
84
85As stated above, LTO is enabled by default. Some newer compilers also support
86different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause
87the function to prefer this flavor if available. The function falls back to
88regular LTO if ``-flto=thin`` is not available.
89
90.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html
91
92Configuration variables
93-----------------------
94
95By default, pybind11 will compile modules with the latest C++ standard
96available on the target compiler. To override this, the standard flag can
97be given explicitly in ``PYBIND11_CPP_STANDARD``:
98
99.. code-block:: cmake
100
101 set(PYBIND11_CPP_STANDARD -std=c++11)
102 add_subdirectory(pybind11) # or find_package(pybind11)
103
104Note that this and all other configuration variables must be set **before** the
105call to ``add_subdiretory`` or ``find_package``. The variables can also be set
106when calling CMake from the command line using the ``-D<variable>=<value>`` flag.
107
108The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION``
109or an exact Python installation can be specified with ``PYTHON_EXECUTABLE``.
110For example:
111
112.. code-block:: bash
113
114 cmake -DPYBIND11_PYTHON_VERSION=3.6 ..
115 # or
116 cmake -DPYTHON_EXECUTABLE=path/to/python ..
117
118find_package vs. add_subdirectory
119---------------------------------
120
121For CMake-based projects that don't include the pybind11 repository internally,
122an external installation can be detected through ``find_package(pybind11)``.
123See the `Config file`_ docstring for details of relevant CMake variables.
124
125.. code-block:: cmake
126
69 cmake_minimum_required(VERSION 2.8.12)
70 project(example)
71
72 find_package(pybind11 REQUIRED)
73 pybind11_add_module(example example.cpp)
74
127 cmake_minimum_required(VERSION 2.8.12)
128 project(example)
129
130 find_package(pybind11 REQUIRED)
131 pybind11_add_module(example example.cpp)
132
75.. [test_installed_module] https://github.com/pybind/pybind11/blob/master/tests/test_installed_module/CMakeLists.txt
133Once detected, the aforementioned ``pybind11_add_module`` can be employed as
134before. The function usage and configuration variables are identical no matter
135if pybind11 is added as a subdirectory or found as an installed package. You
136can refer to the same [cmake_example]_ repository for a full sample project
137-- just swap out ``add_subdirectory`` for ``find_package``.
76
138
77When using a version of CMake greater than 3.0, pybind11 can
78additionally be used as a special *interface library* following the
79call to ``find_package``. CMake variables to guide Python and C++
80standard detection should be set *before* ``find_package``. When
81``find_package`` returns, the target ``pybind11::pybind11`` is
82available with pybind11 headers, Python headers and libraries as
83needed, and C++ compile definitions attached. This target is suitable
84for linking to an independently constructed (through ``add_library``,
85not ``pybind11_add_module``) target in the consuming project. A working
86example can be found at [test_installed_target]_ .
139.. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in
87
140
141Advanced: interface library target
142----------------------------------
143
144When using a version of CMake greater than 3.0, pybind11 can additionally
145be used as a special *interface library* . The target ``pybind11::module``
146is available with pybind11 headers, Python headers and libraries as needed,
147and C++ compile definitions attached. This target is suitable for linking
148to an independently constructed (through ``add_library``, not
149``pybind11_add_module``) target in the consuming project.
150
88.. code-block:: cmake
89
90 cmake_minimum_required(VERSION 3.0)
91 project(example)
92
151.. code-block:: cmake
152
153 cmake_minimum_required(VERSION 3.0)
154 project(example)
155
93 add_library(example MODULE main.cpp)
156 find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11)
94
157
95 find_package(pybind11 REQUIRED)
96 target_link_libraries(example PRIVATE pybind11::pybind11)
158 add_library(example MODULE main.cpp)
159 target_link_libraries(example PRIVATE pybind11::module)
97 set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
98 SUFFIX "${PYTHON_MODULE_EXTENSION}")
99
100.. warning::
101
102 Since pybind11 is a metatemplate library, it is crucial that certain
103 compiler flags are provided to ensure high quality code generation. In
104 contrast to the ``pybind11_add_module()`` command, the CMake interface
105 library only provides the *minimal* set of parameters to ensure that the
106 code using pybind11 compiles, but it does **not** pass these extra compiler
107 flags (i.e. this is up to you).
108
109 These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
110 and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC
111 (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio
112 (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
113 explanation on why these are needed.
114
160 set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
161 SUFFIX "${PYTHON_MODULE_EXTENSION}")
162
163.. warning::
164
165 Since pybind11 is a metatemplate library, it is crucial that certain
166 compiler flags are provided to ensure high quality code generation. In
167 contrast to the ``pybind11_add_module()`` command, the CMake interface
168 library only provides the *minimal* set of parameters to ensure that the
169 code using pybind11 compiles, but it does **not** pass these extra compiler
170 flags (i.e. this is up to you).
171
172 These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
173 and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC
174 (``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio
175 (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
176 explanation on why these are needed.
177
115.. [test_installed_target] https://github.com/pybind/pybind11/blob/master/tests/test_installed_target/CMakeLists.txt
178Generating binding code automatically
179=====================================
116
180
181The ``Binder`` project is a tool for automatic generation of pybind11 binding
182code by introspecting existing C++ codebases using LLVM/Clang. See the
183[binder]_ documentation for details.
184
185.. [binder] http://cppbinder.readthedocs.io/en/latest/about.html