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 the [python_example] repository.
[python_example] | https://github.com/pybind/python_example |
Building with cppimport¶
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.
[cppimport] | https://github.com/tbenthompson/cppimport |
Building with CMake¶
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:
cmake_minimum_required(VERSION 2.8.12)
project(example)
add_subdirectory(pybind11)
pybind11_add_module(example example.cpp)
This assumes that the pybind11 repository is located in a subdirectory named
pybind11
and that the code is located in a file named example.cpp
.
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.
A working sample project, including a way to invoke CMake from setup.py
for
PyPI integration, can be found in the [cmake_example] repository.
[cmake_example] | (1, 2) https://github.com/pybind/cmake_example |
pybind11_add_module¶
To ease the creation of Python extension modules, pybind11 provides a CMake function with the following signature:
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
symbol names and duplication of code in different translation units. The
additional flags enable LTO (Link Time Optimization), set default visibility
to hidden and strip unneeded symbols. See the FAQ entry
for a more detailed explanation. These 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.
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.
Configuration variables¶
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 PYBIND11_CPP_STANDARD
:
set(PYBIND11_CPP_STANDARD -std=c++11)
add_subdirectory(pybind11) # or find_package(pybind11)
Note that this and all other configuration variables must be set before the
call to add_subdiretory
or find_package
. The variables can also be set
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:
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.
cmake_minimum_required(VERSION 2.8.12)
project(example)
find_package(pybind11 REQUIRED)
pybind11_add_module(example example.cpp)
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
.
Advanced: interface library target¶
When using a version of CMake greater than 3.0, pybind11 can additionally
be used as a special interface library . The target pybind11::module
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.
cmake_minimum_required(VERSION 3.0)
project(example)
find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11)
add_library(example MODULE main.cpp)
target_link_libraries(example PRIVATE pybind11::module)
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
and /LTCG
on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC
(-fvisibility=hidden
) and .OBJ files with many sections on Visual Studio
(/bigobj
). The FAQ contains an
explanation on why these are needed.
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 |