Lines Matching +full:pybind11 +full:- +full:tests
6 .. _build-setuptools:
18 A helper file is provided with pybind11 that can simplify usage with setuptools.
20 To use pybind11 inside your ``setup.py``, you have to have some system to
21 ensure that ``pybind11`` is installed when you build your package. There are
22 four possible ways to do this, and pybind11 supports all four: You can ask all
23 users to install pybind11 beforehand (bad), you can use
24 :ref:`setup_helpers-pep518` (good, but very new and requires Pip 10),
25 :ref:`setup_helpers-setup_requires` (discouraged by Python packagers now that
27 :ref:`setup_helpers-copy-manually` (always works but you have to manually sync
30 An example of a ``setup.py`` using pybind11's helpers:
32 .. code-block:: python
36 from pybind11.setup_helpers import Pybind11Extension
54 .. code-block:: python
58 from pybind11.setup_helpers import Pybind11Extension, build_ext
73 Since pybind11 does not require NumPy when building, a light-weight replacement
76 .. code-block:: python
78 from pybind11.setup_helpers import ParallelCompile
95 using ``pip install -e .`` and do not have local headers, you can skip the
99 .. code-block:: python
101 from pybind11.setup_helpers import ParallelCompile, naive_recompile
108 pip install -e .`` would be the way to use it with GCC, for example. Unlike the
117 or use Pip's ``--no-cache-dir`` option.
123 .. _setup_helpers-pep518:
126 ---------------------------------------
128 If you use `PEP 518's <https://www.python.org/dev/peps/pep-0518/>`_
129 ``pyproject.toml`` file, you can ensure that ``pybind11`` is available during
137 .. code-block:: toml
139 [build-system]
140 requires = ["setuptools>=42", "wheel", "pybind11~=2.6.1"]
141 build-backend = "setuptools.build_meta"
152 `pypa-build`_ is the recommended offical tool.
154 .. _PEP 517: https://www.python.org/dev/peps/pep-0517/
156 .. _pypa-build: https://pypa-build.readthedocs.io/en/latest/
158 .. _setup_helpers-setup_requires:
161 --------------------------
164 ``setup_requires=["pybind11"]`` keyword argument to setup, which triggers a
165 two-phase ``setup.py`` run, then you will need to use something like this to
169 .. code-block:: python
172 from pybind11.setup_helpers import Pybind11Extension
184 .. _setup_helpers-copy-manually:
187 -------------
191 set ``include_pybind11=False`` to skip including the pybind11 package headers,
197 Closely related, if you include pybind11 as a subproject, you can run the
199 the correct include for pybind11, though you can turn it off as shown above if
202 Suggested usage if you have pybind11 as a submodule in ``extern/pybind11``:
204 .. code-block:: python
208 sys.path.append(os.path.join(DIR, "extern", "pybind11"))
209 from pybind11.setup_helpers import Pybind11Extension # noqa: E402
211 del sys.path[-1]
223 compiled as a Python extension using pybind11 and placed in the same folder as
233 For C++ codebases that have an existing CMake-based build system, a Python
236 .. code-block:: cmake
241 add_subdirectory(pybind11)
244 This assumes that the pybind11 repository is located in a subdirectory named
245 :file:`pybind11` and that the code is located in a file named :file:`example.cpp`.
246 The CMake command ``add_subdirectory`` will import the pybind11 project which
261 -------------------
263 To ease the creation of Python extension modules, pybind11 provides a CMake
266 .. code-block:: cmake
274 will take care of all the Python-specific compiler and linker flags as well
275 as the OS- and Python-version-specific file extension. The produced target
280 Python-exclusive module. Specifying ``SHARED`` will create a more traditional
284 Since pybind11 is a template library, ``pybind11_add_module`` adds compiler
287 sets default visibility to *hidden*, which is required for some pybind11
288 features and functionality when attempting to load multiple pybind11 modules
289 compiled under different pybind11 versions. It also adds additional flags
299 regular LTO if ``-flto=thin`` is not available. If
301 that will be respected instead of the built-in flag search.
308 no-op) to disable pybind11's ipo flags.
310 The ``OPT_SIZE`` flag enables size-based optimization equivalent to the
311 standard ``/Os`` or ``-Os`` compiler flags and the ``MinSizeRel`` build type,
314 into performance-critical parts and associated bindings. In this case, we can
319 a per-target level and takes precedence over the global CMake build type
326 -----------------------
328 By default, pybind11 will compile modules with the compiler default or the
329 minimum standard required by pybind11, whichever is higher. You can set the
333 .. code-block:: cmake
340 the ``-D<variable>=<value>`` flag. You can also manually set ``CXX_STANDARD``
341 on a target or use ``target_compile_features`` on your targets - anything that
348 .. code-block:: bash
350 cmake -DPYBIND11_PYTHON_VERSION=3.6 ..
353 cmake -DPYTHON_EXECUTABLE=/path/to/python ..
356 cmake -DPYTHON_EXECUTABLE=$(python3 -c "import sys; print(sys.executable)") ..
360 ---------------------------------
362 For CMake-based projects that don't include the pybind11 repository internally,
363 an external installation can be detected through ``find_package(pybind11)``.
366 .. code-block:: cmake
371 find_package(pybind11 REQUIRED)
374 Note that ``find_package(pybind11)`` will only work correctly if pybind11
376 the pybind11 repository :
378 .. code-block:: bash
381 cd pybind11
388 cd pybind11
389 cmake -S . -B build
390 cmake --build build -j 2 # Build on 2 cores
391 cmake --install build
395 if pybind11 is added as a subdirectory or found as an installed package. You
397 -- just swap out ``add_subdirectory`` for ``find_package``.
399 .. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in
402 .. _find-python-mode:
405 ---------------
409 and tools. If you use FindPython, pybind11 will detect this and use the
412 .. code-block:: cmake
418 find_package(pybind11 CONFIG REQUIRED)
419 # or add_subdirectory(pybind11)
424 ``PYBIND11_FINDPYTHON``, pybind11 will perform the FindPython step for you
425 (mostly useful when building pybind11's own tests, or as a way to change search
426 algorithms from the CMake invocation, with ``-DPYBIND11_FINDPYTHON=ON``.
430 If you use FindPython2 and FindPython3 to dual-target Python, use the
451 -----------------------------------
453 Pybind11 supports modern CMake usage patterns with a set of interface targets,
456 ``pybind11::headers``
457 Just the pybind11 headers and minimum compile requirements
459 ``pybind11::python2_no_register``
462 ``pybind11::pybind11``
463 Python headers + ``pybind11::headers`` + ``pybind11::python2_no_register`` (Python 2 only)
465 ``pybind11::python_link_helper``
466 Just the "linking" part of pybind11:module
468 ``pybind11::module``
469 …Everything for extension modules - ``pybind11::pybind11`` + ``Python::Module`` (FindPython CMake 3…
471 ``pybind11::embed``
472 …Everything for embedding the Python interpreter - ``pybind11::pybind11`` + ``Python::Embed`` (Find…
474 ``pybind11::lto`` / ``pybind11::thin_lto``
475 An alternative to `INTERPROCEDURAL_OPTIMIZATION` for adding link-time optimization.
477 ``pybind11::windows_extras``
480 ``pybind11::opt_size``
481 ``/Os`` for MSVC, ``-Os`` for other compilers. Does nothing for debug builds.
494 .. code-block:: cmake
499 find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11)
503 target_link_libraries(example PRIVATE pybind11::module pybind11::lto pybind11::windows_extras)
515 Since pybind11 is a metatemplate library, it is crucial that certain
524 .. _nopython-mode:
527 -----------------------
532 freedom to integrate into an existing system (like `Scikit-Build's
533 <https://scikit-build.readthedocs.io>`_ ``PythonExtensions``).
540 --------------------------------
542 In addition to extension modules, pybind11 also supports embedding Python into
543 a C++ executable or library. In CMake, simply link with the ``pybind11::embed``
545 headers and libraries are attached to the target. Unlike ``pybind11::module``,
549 .. code-block:: cmake
554 find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11)
557 target_link_libraries(example PRIVATE pybind11::embed)
564 pybind11 is a header-only library, hence it is not necessary to link against
570 .. code-block:: bash
572 …$ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$…
577 The ``python3 -m pybind11 --includes`` command fetches the include paths for
578 both pybind11 and Python headers. This assumes that pybind11 has been installed
580 ``-I <path-to-pybind11>/include`` together with the Python includes path
581 ``python3-config --includes``.
584 use ``example.so`` instead of ``example$(python3-config --extension-suffix)``.
585 Besides, the ``--extension-suffix`` option may or may not be available, depending
590 the ``-undefined dynamic_lookup`` flag so as to ignore missing symbols when
593 .. code-block:: bash
595 …$ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup $(python3 -m pybind11 --includes) exa…
599 :ref:`cmake` for a detailed example of a suitable cross-platform CMake-based
608 system-provided Python, and one that ships with a piece of commercial
623 The ``Binder`` project is a tool for automatic generation of pybind11 binding
630 high-level languages. It parses C++ code using LLVM/Clang technologies and
633 classes or incorporating modern meta-programming constructs.
637 [robotpy-build]_ is a is a pure python, cross platform build tool that aims to
638 simplify creation of python wheels for pybind11 projects, and provide
639 cross-project dependency management. Additionally, it is able to autogenerate
640 customizable pybind11-based wrappers by parsing C++ header files.
642 .. [robotpy-build] https://robotpy-build.readthedocs.io