| | .. _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) |
| | 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.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 |
| |
|
