mirror of
https://github.com/pybind/pybind11.git
synced 2024-12-05 03:17:11 +00:00
522c59ceb2
* chore: drop Python 3.5 support * chore: more fstrings with flynt's help * ci: drop Python 3.5 * chore: bump dependency versions * docs: touch up py::args * tests: remove deprecation warning * Ban smartquotes * Very minor tweaks (by-product of reviewing PR #3719). Co-authored-by: Aaron Gokaslan <skylion.aaron@gmail.com> Co-authored-by: Ralf W. Grosse-Kunstleve <rwgk@google.com>
636 lines
25 KiB
ReStructuredText
636 lines
25 KiB
ReStructuredText
.. _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", "wheel", "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.4...3.18)
|
|
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.
|
|
|
|
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.4)
|
|
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)
|
|
pybind11_strip(example)
|
|
|
|
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.4...3.18)
|
|
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
|