|
|
.. _compiling: |
|
|
|
|
|
Build systems |
|
|
############# |
|
|
|
|
|
.. _build-setuptools: |
|
|
|
|
|
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 |
|
|
|
|
|
A helper file is provided with pybind11 that can simplify usage with setuptools. |
|
|
|
|
|
To use pybind11 inside your ``setup.py``, you have to have some system to |
|
|
ensure that ``pybind11`` is installed when you build your package. There are |
|
|
four possible ways to do this, and pybind11 supports all four: You can ask all |
|
|
users to install pybind11 beforehand (bad), you can use |
|
|
:ref:`setup_helpers-pep518` (good, but very new and requires Pip 10), |
|
|
:ref:`setup_helpers-setup_requires` (discouraged by Python packagers now that |
|
|
PEP 518 is available, but it still works everywhere), or you can |
|
|
:ref:`setup_helpers-copy-manually` (always works but you have to manually sync |
|
|
your copy to get updates). |
|
|
|
|
|
An example of a ``setup.py`` using pybind11's helpers: |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
from glob import glob |
|
|
from setuptools import setup |
|
|
from pybind11.setup_helpers import Pybind11Extension |
|
|
|
|
|
ext_modules = [ |
|
|
Pybind11Extension( |
|
|
"python_example", |
|
|
sorted(glob("src/*.cpp")), # Sort source files for reproducibility |
|
|
), |
|
|
] |
|
|
|
|
|
setup(..., ext_modules=ext_modules) |
|
|
|
|
|
If you want to do an automatic search for the highest supported C++ standard, |
|
|
that is supported via a ``build_ext`` command override; it will only affect |
|
|
``Pybind11Extensions``: |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
from glob import glob |
|
|
from setuptools import setup |
|
|
from pybind11.setup_helpers import Pybind11Extension, build_ext |
|
|
|
|
|
ext_modules = [ |
|
|
Pybind11Extension( |
|
|
"python_example", |
|
|
sorted(glob("src/*.cpp")), |
|
|
), |
|
|
] |
|
|
|
|
|
setup(..., cmdclass={"build_ext": build_ext}, ext_modules=ext_modules) |
|
|
|
|
|
If you have single-file extension modules that are directly stored in the |
|
|
Python source tree (``foo.cpp`` in the same directory as where a ``foo.py`` |
|
|
would be located), you can also generate ``Pybind11Extensions`` using |
|
|
``setup_helpers.intree_extensions``: ``intree_extensions(["path/to/foo.cpp", |
|
|
...])`` returns a list of ``Pybind11Extensions`` which can be passed to |
|
|
``ext_modules``, possibly after further customizing their attributes |
|
|
(``libraries``, ``include_dirs``, etc.). By doing so, a ``foo.*.so`` extension |
|
|
module will be generated and made available upon installation. |
|
|
|
|
|
``intree_extension`` will automatically detect if you are using a ``src``-style |
|
|
layout (as long as no namespace packages are involved), but you can also |
|
|
explicitly pass ``package_dir`` to it (as in ``setuptools.setup``). |
|
|
|
|
|
Since pybind11 does not require NumPy when building, a light-weight replacement |
|
|
for NumPy's parallel compilation distutils tool is included. Use it like this: |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
from pybind11.setup_helpers import ParallelCompile |
|
|
|
|
|
# Optional multithreaded build |
|
|
ParallelCompile("NPY_NUM_BUILD_JOBS").install() |
|
|
|
|
|
setup(...) |
|
|
|
|
|
The argument is the name of an environment variable to control the number of |
|
|
threads, such as ``NPY_NUM_BUILD_JOBS`` (as used by NumPy), though you can set |
|
|
something different if you want; ``CMAKE_BUILD_PARALLEL_LEVEL`` is another choice |
|
|
a user might expect. You can also pass ``default=N`` to set the default number |
|
|
of threads (0 will take the number of threads available) and ``max=N``, the |
|
|
maximum number of threads; if you have a large extension you may want set this |
|
|
to a memory dependent number. |
|
|
|
|
|
If you are developing rapidly and have a lot of C++ files, you may want to |
|
|
avoid rebuilding files that have not changed. For simple cases were you are |
|
|
using ``pip install -e .`` and do not have local headers, you can skip the |
|
|
rebuild if an object file is newer than its source (headers are not checked!) |
|
|
with the following: |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
from pybind11.setup_helpers import ParallelCompile, naive_recompile |
|
|
|
|
|
ParallelCompile("NPY_NUM_BUILD_JOBS", needs_recompile=naive_recompile).install() |
|
|
|
|
|
|
|
|
If you have a more complex build, you can implement a smarter function and pass |
|
|
it to ``needs_recompile``, or you can use [Ccache]_ instead. ``CXX="cache g++" |
|
|
pip install -e .`` would be the way to use it with GCC, for example. Unlike the |
|
|
simple solution, this even works even when not compiling in editable mode, but |
|
|
it does require Ccache to be installed. |
|
|
|
|
|
Keep in mind that Pip will not even attempt to rebuild if it thinks it has |
|
|
already built a copy of your code, which it deduces from the version number. |
|
|
One way to avoid this is to use [setuptools_scm]_, which will generate a |
|
|
version number that includes the number of commits since your last tag and a |
|
|
hash for a dirty directory. Another way to force a rebuild is purge your cache |
|
|
or use Pip's ``--no-cache-dir`` option. |
|
|
|
|
|
.. [Ccache] https://ccache.dev |
|
|
|
|
|
.. [setuptools_scm] https://github.com/pypa/setuptools_scm |
|
|
|
|
|
.. _setup_helpers-pep518: |
|
|
|
|
|
PEP 518 requirements (Pip 10+ required) |
|
|
--------------------------------------- |
|
|
|
|
|
If you use `PEP 518's <https://www.python.org/dev/peps/pep-0518/>`_ |
|
|
``pyproject.toml`` file, you can ensure that ``pybind11`` is available during |
|
|
the compilation of your project. When this file exists, Pip will make a new |
|
|
virtual environment, download just the packages listed here in ``requires=``, |
|
|
and build a wheel (binary Python package). It will then throw away the |
|
|
environment, and install your wheel. |
|
|
|
|
|
Your ``pyproject.toml`` file will likely look something like this: |
|
|
|
|
|
.. code-block:: toml |
|
|
|
|
|
[build-system] |
|
|
requires = ["setuptools>=42", "pybind11>=2.6.1"] |
|
|
build-backend = "setuptools.build_meta" |
|
|
|
|
|
.. note:: |
|
|
|
|
|
The main drawback to this method is that a `PEP 517`_ compliant build tool, |
|
|
such as Pip 10+, is required for this approach to work; older versions of |
|
|
Pip completely ignore this file. If you distribute binaries (called wheels |
|
|
in Python) using something like `cibuildwheel`_, remember that ``setup.py`` |
|
|
and ``pyproject.toml`` are not even contained in the wheel, so this high |
|
|
Pip requirement is only for source builds, and will not affect users of |
|
|
your binary wheels. If you are building SDists and wheels, then |
|
|
`pypa-build`_ is the recommended official tool. |
|
|
|
|
|
.. _PEP 517: https://www.python.org/dev/peps/pep-0517/ |
|
|
.. _cibuildwheel: https://cibuildwheel.readthedocs.io |
|
|
.. _pypa-build: https://pypa-build.readthedocs.io/en/latest/ |
|
|
|
|
|
.. _setup_helpers-setup_requires: |
|
|
|
|
|
Classic ``setup_requires`` |
|
|
-------------------------- |
|
|
|
|
|
If you want to support old versions of Pip with the classic |
|
|
``setup_requires=["pybind11"]`` keyword argument to setup, which triggers a |
|
|
two-phase ``setup.py`` run, then you will need to use something like this to |
|
|
ensure the first pass works (which has not yet installed the ``setup_requires`` |
|
|
packages, since it can't install something it does not know about): |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
try: |
|
|
from pybind11.setup_helpers import Pybind11Extension |
|
|
except ImportError: |
|
|
from setuptools import Extension as Pybind11Extension |
|
|
|
|
|
|
|
|
It doesn't matter that the Extension class is not the enhanced subclass for the |
|
|
first pass run; and the second pass will have the ``setup_requires`` |
|
|
requirements. |
|
|
|
|
|
This is obviously more of a hack than the PEP 518 method, but it supports |
|
|
ancient versions of Pip. |
|
|
|
|
|
.. _setup_helpers-copy-manually: |
|
|
|
|
|
Copy manually |
|
|
------------- |
|
|
|
|
|
You can also copy ``setup_helpers.py`` directly to your project; it was |
|
|
designed to be usable standalone, like the old example ``setup.py``. You can |
|
|
set ``include_pybind11=False`` to skip including the pybind11 package headers, |
|
|
so you can use it with git submodules and a specific git version. If you use |
|
|
this, you will need to import from a local file in ``setup.py`` and ensure the |
|
|
helper file is part of your MANIFEST. |
|
|
|
|
|
|
|
|
Closely related, if you include pybind11 as a subproject, you can run the |
|
|
``setup_helpers.py`` inplace. If loaded correctly, this should even pick up |
|
|
the correct include for pybind11, though you can turn it off as shown above if |
|
|
you want to input it manually. |
|
|
|
|
|
Suggested usage if you have pybind11 as a submodule in ``extern/pybind11``: |
|
|
|
|
|
.. code-block:: python |
|
|
|
|
|
DIR = os.path.abspath(os.path.dirname(__file__)) |
|
|
|
|
|
sys.path.append(os.path.join(DIR, "extern", "pybind11")) |
|
|
from pybind11.setup_helpers import Pybind11Extension # noqa: E402 |
|
|
|
|
|
del sys.path[-1] |
|
|
|
|
|
|
|
|
.. versionchanged:: 2.6 |
|
|
|
|
|
Added ``setup_helpers`` file. |
|
|
|
|
|
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 |
|
|
|
|
|
.. _cmake: |
|
|
|
|
|
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: |
|
|
|
|
|
.. code-block:: cmake |
|
|
|
|
|
cmake_minimum_required(VERSION 3.5...3.27) |
|
|
project(example LANGUAGES CXX) |
|
|
|
|
|
add_subdirectory(pybind11) |
|
|
pybind11_add_module(example example.cpp) |
|
|
|
|
|
This assumes that the pybind11 repository is located in a subdirectory named |
|
|
:file:`pybind11` and that the code is located in a file named :file:`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 :file:`setup.py` for |
|
|
PyPI integration, can be found in the [cmake_example]_ repository. |
|
|
|
|
|
.. [cmake_example] https://github.com/pybind/cmake_example |
|
|
|
|
|
.. versionchanged:: 2.6 |
|
|
CMake 3.4+ is required. |
|
|
|
|
|
.. versionchanged:: 2.11 |
|
|
CMake 3.5+ is required. |
|
|
|
|
|
Further information can be found at :doc:`cmake/index`. |
|
|
|
|
|
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] [OPT_SIZE] 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. 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. |
|
|
|
|
|
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. If |
|
|
``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` is set (either ``ON`` or ``OFF``), then |
|
|
that will be respected instead of the built-in flag search. |
|
|
|
|
|
.. note:: |
|
|
|
|
|
If you want to set the property form on targets or the |
|
|
``CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>`` versions of this, you should |
|
|
still use ``set(CMAKE_INTERPROCEDURAL_OPTIMIZATION OFF)`` (otherwise a |
|
|
no-op) to disable pybind11's ipo flags. |
|
|
|
|
|
The ``OPT_SIZE`` flag enables size-based optimization equivalent to the |
|
|
standard ``/Os`` or ``-Os`` compiler flags and the ``MinSizeRel`` build type, |
|
|
which avoid optimizations that that can substantially increase the size of the |
|
|
resulting binary. This flag is particularly useful in projects that are split |
|
|
into performance-critical parts and associated bindings. In this case, we can |
|
|
compile the project in release mode (and hence, optimize performance globally), |
|
|
and specify ``OPT_SIZE`` for the binding target, where size might be the main |
|
|
concern as performance is often less critical here. A ~25% size reduction has |
|
|
been observed in practice. This flag only changes the optimization behavior at |
|
|
a per-target level and takes precedence over the global CMake build type |
|
|
(``Release``, ``RelWithDebInfo``) except for ``Debug`` builds, where |
|
|
optimizations remain disabled. |
|
|
|
|
|
.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html |
|
|
|
|
|
Configuration variables |
|
|
----------------------- |
|
|
|
|
|
By default, pybind11 will compile modules with the compiler default or the |
|
|
minimum standard required by pybind11, whichever is higher. You can set the |
|
|
standard explicitly with |
|
|
`CMAKE_CXX_STANDARD <https://cmake.org/cmake/help/latest/variable/CMAKE_CXX_STANDARD.html>`_: |
|
|
|
|
|
.. code-block:: cmake |
|
|
|
|
|
set(CMAKE_CXX_STANDARD 14 CACHE STRING "C++ version selection") # or 11, 14, 17, 20 |
|
|
set(CMAKE_CXX_STANDARD_REQUIRED ON) # optional, ensure standard is supported |
|
|
set(CMAKE_CXX_EXTENSIONS OFF) # optional, keep compiler extensions off |
|
|
|
|
|
The variables can also be set when calling CMake from the command line using |
|
|
the ``-D<variable>=<value>`` flag. You can also manually set ``CXX_STANDARD`` |
|
|
on a target or use ``target_compile_features`` on your targets - anything that |
|
|
CMake supports. |
|
|
|
|
|
Classic Python support: 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: |
|
|
|
|
|
.. code-block:: bash |
|
|
|
|
|
cmake -DPYBIND11_PYTHON_VERSION=3.6 .. |
|
|
|
|
|
# Another method: |
|
|
cmake -DPYTHON_EXECUTABLE=/path/to/python .. |
|
|
|
|
|
# This often is a good way to get the current Python, works in environments: |
|
|
cmake -DPYTHON_EXECUTABLE=$(python3 -c "import sys; print(sys.executable)") .. |
|
|
|
|
|
|
|
|
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. |
|
|
|
|
|
.. code-block:: cmake |
|
|
|
|
|
cmake_minimum_required(VERSION 3.4...3.18) |
|
|
project(example LANGUAGES CXX) |
|
|
|
|
|
find_package(pybind11 REQUIRED) |
|
|
pybind11_add_module(example example.cpp) |
|
|
|
|
|
Note that ``find_package(pybind11)`` will only work correctly if pybind11 |
|
|
has been correctly installed on the system, e. g. after downloading or cloning |
|
|
the pybind11 repository : |
|
|
|
|
|
.. code-block:: bash |
|
|
|
|
|
# Classic CMake |
|
|
cd pybind11 |
|
|
mkdir build |
|
|
cd build |
|
|
cmake .. |
|
|
make install |
|
|
|
|
|
# CMake 3.15+ |
|
|
cd pybind11 |
|
|
cmake -S . -B build |
|
|
cmake --build build -j 2 # Build on 2 cores |
|
|
cmake --install build |
|
|
|
|
|
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 |
|
|
|
|
|
|
|
|
.. _find-python-mode: |
|
|
|
|
|
FindPython mode |
|
|
--------------- |
|
|
|
|
|
CMake 3.12+ (3.15+ recommended, 3.18.2+ ideal) added a new module called |
|
|
FindPython that had a highly improved search algorithm and modern targets |
|
|
and tools. If you use FindPython, pybind11 will detect this and use the |
|
|
existing targets instead: |
|
|
|
|
|
.. code-block:: cmake |
|
|
|
|
|
cmake_minimum_required(VERSION 3.15...3.22) |
|
|
project(example LANGUAGES CXX) |
|
|
|
|
|
find_package(Python 3.6 COMPONENTS Interpreter Development REQUIRED) |
|
|
find_package(pybind11 CONFIG REQUIRED) |
|
|
# or add_subdirectory(pybind11) |
|
|
|
|
|
pybind11_add_module(example example.cpp) |
|
|
|
|
|
You can also use the targets (as listed below) with FindPython. If you define |
|
|
``PYBIND11_FINDPYTHON``, pybind11 will perform the FindPython step for you |
|
|
(mostly useful when building pybind11's own tests, or as a way to change search |
|
|
algorithms from the CMake invocation, with ``-DPYBIND11_FINDPYTHON=ON``. |
|
|
|
|
|
.. warning:: |
|
|
|
|
|
If you use FindPython to multi-target Python versions, use the individual |
|
|
targets listed below, and avoid targets that directly include Python parts. |
|
|
|
|
|
There are `many ways to hint or force a discovery of a specific Python |
|
|
installation <https://cmake.org/cmake/help/latest/module/FindPython.html>`_), |
|
|
setting ``Python_ROOT_DIR`` may be the most common one (though with |
|
|
virtualenv/venv support, and Conda support, this tends to find the correct |
|
|
Python version more often than the old system did). |
|
|
|
|
|
.. warning:: |
|
|
|
|
|
When the Python libraries (i.e. ``libpythonXX.a`` and ``libpythonXX.so`` |
|
|
on Unix) are not available, as is the case on a manylinux image, the |
|
|
``Development`` component will not be resolved by ``FindPython``. When not |
|
|
using the embedding functionality, CMake 3.18+ allows you to specify |
|
|
``Development.Module`` instead of ``Development`` to resolve this issue. |
|
|
|
|
|
.. versionadded:: 2.6 |
|
|
|
|
|
Advanced: interface library targets |
|
|
----------------------------------- |
|
|
|
|
|
Pybind11 supports modern CMake usage patterns with a set of interface targets, |
|
|
available in all modes. The targets provided are: |
|
|
|
|
|
``pybind11::headers`` |
|
|
Just the pybind11 headers and minimum compile requirements |
|
|
|
|
|
``pybind11::pybind11`` |
|
|
Python headers + ``pybind11::headers`` |
|
|
|
|
|
``pybind11::python_link_helper`` |
|
|
Just the "linking" part of pybind11:module |
|
|
|
|
|
``pybind11::module`` |
|
|
Everything for extension modules - ``pybind11::pybind11`` + ``Python::Module`` (FindPython CMake 3.15+) or ``pybind11::python_link_helper`` |
|
|
|
|
|
``pybind11::embed`` |
|
|
Everything for embedding the Python interpreter - ``pybind11::pybind11`` + ``Python::Python`` (FindPython) or Python libs |
|
|
|
|
|
``pybind11::lto`` / ``pybind11::thin_lto`` |
|
|
An alternative to `INTERPROCEDURAL_OPTIMIZATION` for adding link-time optimization. |
|
|
|
|
|
``pybind11::windows_extras`` |
|
|
``/bigobj`` and ``/mp`` for MSVC. |
|
|
|
|
|
``pybind11::opt_size`` |
|
|
``/Os`` for MSVC, ``-Os`` for other compilers. Does nothing for debug builds. |
|
|
|
|
|
Two helper functions are also provided: |
|
|
|
|
|
``pybind11_strip(target)`` |
|
|
Strips a target (uses ``CMAKE_STRIP`` after the target is built) |
|
|
|
|
|
``pybind11_extension(target)`` |
|
|
Sets the correct extension (with SOABI) for a target. |
|
|
|
|
|
You can use these targets to build complex applications. For example, the |
|
|
``add_python_module`` function is identical to: |
|
|
|
|
|
.. code-block:: cmake |
|
|
|
|
|
cmake_minimum_required(VERSION 3.5...3.27) |
|
|
project(example LANGUAGES CXX) |
|
|
|
|
|
find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) |
|
|
|
|
|
add_library(example MODULE main.cpp) |
|
|
|
|
|
target_link_libraries(example PRIVATE pybind11::module pybind11::lto pybind11::windows_extras) |
|
|
|
|
|
pybind11_extension(example) |
|
|
if(NOT MSVC AND NOT ${CMAKE_BUILD_TYPE} MATCHES Debug|RelWithDebInfo) |
|
|
# Strip unnecessary sections of the binary on Linux/macOS |
|
|
pybind11_strip(example) |
|
|
endif() |
|
|
|
|
|
set_target_properties(example PROPERTIES CXX_VISIBILITY_PRESET "hidden" |
|
|
CUDA_VISIBILITY_PRESET "hidden") |
|
|
|
|
|
Instead of setting properties, you can set ``CMAKE_*`` variables to initialize these correctly. |
|
|
|
|
|
.. 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 |
|
|
provides a *composable* set of targets to ensure that you retain flexibility. |
|
|
It can be especially important to provide or set these properties; the |
|
|
:ref:`FAQ <faq:symhidden>` contains an explanation on why these are needed. |
|
|
|
|
|
.. versionadded:: 2.6 |
|
|
|
|
|
.. _nopython-mode: |
|
|
|
|
|
Advanced: NOPYTHON mode |
|
|
----------------------- |
|
|
|
|
|
If you want complete control, you can set ``PYBIND11_NOPYTHON`` to completely |
|
|
disable Python integration (this also happens if you run ``FindPython2`` and |
|
|
``FindPython3`` without running ``FindPython``). This gives you complete |
|
|
freedom to integrate into an existing system (like `Scikit-Build's |
|
|
<https://scikit-build.readthedocs.io>`_ ``PythonExtensions``). |
|
|
``pybind11_add_module`` and ``pybind11_extension`` will be unavailable, and the |
|
|
targets will be missing any Python specific behavior. |
|
|
|
|
|
.. versionadded:: 2.6 |
|
|
|
|
|
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.5...3.27) |
|
|
project(example LANGUAGES CXX) |
|
|
|
|
|
find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) |
|
|
|
|
|
add_executable(example main.cpp) |
|
|
target_link_libraries(example PRIVATE pybind11::embed) |
|
|
|
|
|
.. _building_manually: |
|
|
|
|
|
Building manually |
|
|
================= |
|
|
|
|
|
pybind11 is a header-only library, hence it is not necessary to link against |
|
|
any special libraries and there are no intermediate (magic) translation steps. |
|
|
|
|
|
On Linux, you can compile an example such as the one given in |
|
|
:ref:`simple_example` using the following command: |
|
|
|
|
|
.. code-block:: bash |
|
|
|
|
|
$ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix) |
|
|
|
|
|
The ``python3 -m pybind11 --includes`` command fetches the include paths for |
|
|
both pybind11 and Python headers. This assumes that pybind11 has been installed |
|
|
using ``pip`` or ``conda``. If it hasn't, you can also manually specify |
|
|
``-I <path-to-pybind11>/include`` together with the Python includes path |
|
|
``python3-config --includes``. |
|
|
|
|
|
On macOS: the build command is almost the same but it also requires passing |
|
|
the ``-undefined dynamic_lookup`` flag so as to ignore missing symbols when |
|
|
building the module: |
|
|
|
|
|
.. code-block:: bash |
|
|
|
|
|
$ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix) |
|
|
|
|
|
In general, it is advisable to include several additional build parameters |
|
|
that can considerably reduce the size of the created binary. Refer to section |
|
|
:ref:`cmake` for a detailed example of a suitable cross-platform CMake-based |
|
|
build system that works on all platforms including Windows. |
|
|
|
|
|
.. note:: |
|
|
|
|
|
On Linux and macOS, it's better to (intentionally) not link against |
|
|
``libpython``. The symbols will be resolved when the extension library |
|
|
is loaded into a Python binary. This is preferable because you might |
|
|
have several different installations of a given Python version (e.g. the |
|
|
system-provided Python, and one that ships with a piece of commercial |
|
|
software). In this way, the plugin will work with both versions, instead |
|
|
of possibly importing a second Python library into a process that already |
|
|
contains one (which will lead to a segfault). |
|
|
|
|
|
|
|
|
Building with Bazel |
|
|
=================== |
|
|
|
|
|
You can build with the Bazel build system using the `pybind11_bazel |
|
|
<https://github.com/pybind/pybind11_bazel>`_ repository. |
|
|
|
|
|
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 |
|
|
|
|
|
[AutoWIG]_ is a Python library that wraps automatically compiled libraries into |
|
|
high-level languages. It parses C++ code using LLVM/Clang technologies and |
|
|
generates the wrappers using the Mako templating engine. The approach is automatic, |
|
|
extensible, and applies to very complex C++ libraries, composed of thousands of |
|
|
classes or incorporating modern meta-programming constructs. |
|
|
|
|
|
.. [AutoWIG] https://github.com/StatisKit/AutoWIG |
|
|
|
|
|
[robotpy-build]_ is a is a pure python, cross platform build tool that aims to |
|
|
simplify creation of python wheels for pybind11 projects, and provide |
|
|
cross-project dependency management. Additionally, it is able to autogenerate |
|
|
customizable pybind11-based wrappers by parsing C++ header files. |
|
|
|
|
|
.. [robotpy-build] https://robotpy-build.readthedocs.io |
|
|
|
