pybind/pybind11
1
0
Fork 0
mirror of https://github.com/pybind/pybind11.git synced 2026-03-14 20:27:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

add CMake exported interface library and Config detection file

Browse Source
This commit is contained in:
Lori A. Burns
2016-12-13 10:55:38 -05:00
committed by Wenzel Jakob
parent 44d7c59c55
commit 5cafc99884
5 changed files with 191 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/compiling.rst
View File

@@ -51,3 +51,67 @@ A working sample project, including a way to invoke CMake from :file:`setup.py`
PyPI integration, can be found in the [cmake_example]_ repository.
.. [cmake_example] https://github.com/pybind/cmake_example
For CMake-based projects that don't include the pybind11
repository internally, an external installation can be detected
through `find_package(pybind11 ... CONFIG ...)`. See the `Config file
<https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in>`_
docstring for details of relevant CMake variables.
Once detected, and after setting any variables to guide Python and C++
standard detection, the aforementioned ``pybind11_add_module``
wrapper to ``add_library`` can
be employed as described above (after ``include(pybind11Tools)``). This
procedure is available when using CMake >= 2.8.12. A
working example can be found at [test_installed_module]_ .
.. code-block:: cmake
cmake_minimum_required(VERSION 2.8.12)
project(example)
find_package(pybind11 REQUIRED)
pybind11_add_module(example example.cpp)
.. [test_installed_module] https://github.com/pybind/pybind11/blob/master/tests/test_installed_module/CMakeLists.txt
When using a version of CMake greater than 3.0, pybind11 can
additionally be used as a special *interface library* following the call
to ``find_package``. CMake
variables to guide Python and C++ standard detection should be set
*before* ``find_package``. When ``find_package`` returns, the target
``pybind11::pybind11`` is available with pybind11 headers, Python headers
and libraries as needed, and C++ compile definitions attached. This
target is suitable for linking to an independently constructed (through
``add_library``, not ``pybind11_add_module``) target in the consuming
project. A working example can be found at [test_installed_target]_ .
.. code-block:: cmake
cmake_minimum_required(VERSION 3.0)
project(example)
add_library(example MODULE main.cpp)
find_package(pybind11 REQUIRED)
target_link_libraries(example PRIVATE pybind11::pybind11)
set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}"
SUFFIX "${PYTHON_MODULE_EXTENSION}")
.. warning::
Since pybind11 is a metatemplate library, it is crucial that certain
compiler flags are provided to ensure high quality code generation. In
contrast to the ``pybind11_add_module()`` command, the CMake interface
library only provides the *minimal* set of parameters to ensure that the
code using pybind11 compiles, but it does **not** pass these extra compiler
flags (i.e. this is up to you).
These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL``
and ``/LTCG`` on Visual Studio). Default-hidden symbols on GCC/Clang/ICPC
(``-fvisibility=hidden``) and .OBJ files with many sections on Visual Studio
(``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
explanation on why these are needed.
.. [test_installed_target] https://github.com/pybind/pybind11/blob/master/tests/test_installed_target/CMakeLists.txt