1#[=============================================================================[.rst:
2
3pybind11Config.cmake
4####################
5
6Exported variables
7==================
8
9This module sets the following variables in your project:
10
11``pybind11_FOUND``
12  true if pybind11 and all required components found on the system
13``pybind11_VERSION``
14  pybind11 version in format Major.Minor.Release
15``pybind11_VERSION_TYPE``
16  pybind11 version type (dev, release)
17``pybind11_INCLUDE_DIRS``
18  Directories where pybind11 and python headers are located.
19``pybind11_INCLUDE_DIR``
20  Directory where pybind11 headers are located.
21``pybind11_DEFINITIONS``
22  Definitions necessary to use pybind11, namely USING_pybind11.
23``pybind11_LIBRARIES``
24  Compile flags and python libraries (as needed) to link against.
25``pybind11_LIBRARY``
26  Empty.
27
28Available components: None
29
30
31Exported targets
32================
33
34If pybind11 is found, this module defines the following ``IMPORTED``
35interface library targets:
36
37``pybind11::module``
38  for extension modules.
39``pybind11::embed``
40  for embedding the Python interpreter.
41
42Python headers, libraries (as needed by platform), and the C++ standard
43are attached to the target.
44
45Advanced targets are also supplied - these are primary for users building
46complex applications, and they are available in all modes:
47
48``pybind11::headers``
49  Just the pybind11 headers and minimum compile requirements.
50``pybind11::pybind11``
51  Python headers too.
52``pybind11::python_link_helper``
53  Just the "linking" part of ``pybind11:module``, for CMake < 3.15.
54``pybind11::python2_no_register``
55  Quiets the warning/error when mixing C++14+ and Python 2, also included in ``pybind11::module``.
56``pybind11::thin_lto``
57  An alternative to ``INTERPROCEDURAL_OPTIMIZATION``.
58``pybind11::lto``
59  An alternative to ``INTERPROCEDURAL_OPTIMIZATION`` (also avoids thin LTO on clang).
60``pybind11::windows_extras``
61  Adds bigobj and mp for MSVC.
62
63Modes
64=====
65
66There are two modes provided; classic, which is built on the old Python
67discovery packages in CMake, or the new FindPython mode, which uses FindPython
68from 3.12+ forward (3.15+ _highly_ recommended).
69
70New FindPython mode
71^^^^^^^^^^^^^^^^^^^
72
73To activate this mode, either call ``find_package(Python COMPONENTS Interpreter Development)``
74before finding this package, or set the ``PYBIND11_FINDPYTHON`` variable to ON. In this mode,
75you can either use the basic targets, or use the FindPython tools:
76
77.. code-block:: cmake
78
79  find_package(Python COMPONENTS Interpreter Development)
80  find_package(pybind11 CONFIG)
81
82  # pybind11 method:
83  pybind11_add_module(MyModule1 src1.cpp)
84
85  # Python method:
86  Python_add_library(MyModule2 src2.cpp)
87  target_link_libraries(MyModule2 pybind11::headers)
88  set_target_properties(MyModule2 PROPERTIES
89                                  INTERPROCEDURAL_OPTIMIZATION ON
90                                  CXX_VISIBILITY_PRESET ON
91                                  VISIBLITY_INLINES_HIDDEN ON)
92
93If you build targets yourself, you may be interested in stripping the output
94for reduced size; this is the one other feature that the helper function gives you.
95
96Classic mode
97^^^^^^^^^^^^
98
99Set PythonLibsNew variables to influence python detection and
100CMAKE_CXX_STANDARD to influence standard setting.
101
102.. code-block:: cmake
103
104  find_package(pybind11 CONFIG REQUIRED)
105
106  # Create an extension module
107  add_library(mylib MODULE main.cpp)
108  target_link_libraries(mylib PUBLIC pybind11::module)
109
110  # Or embed the Python interpreter into an executable
111  add_executable(myexe main.cpp)
112  target_link_libraries(myexe PUBLIC pybind11::embed)
113
114
115Hints
116=====
117
118The following variables can be set to guide the search for this package:
119
120``pybind11_DIR``
121  CMake variable, set to directory containing this Config file.
122``CMAKE_PREFIX_PATH``
123  CMake variable, set to root directory of this package.
124``PATH``
125  Environment variable, set to bin directory of this package.
126``CMAKE_DISABLE_FIND_PACKAGE_pybind11``
127  CMake variable, disables ``find_package(pybind11)`` when not ``REQUIRED``,
128  perhaps to force internal build.
129
130Commands
131========
132
133pybind11_add_module
134^^^^^^^^^^^^^^^^^^^
135
136This module defines the following commands to assist with creating Python modules:
137
138.. code-block:: cmake
139
140  pybind11_add_module(<target>
141    [STATIC|SHARED|MODULE]
142    [THIN_LTO] [OPT_SIZE] [NO_EXTRAS] [WITHOUT_SOBAI]
143    <files>...
144    )
145
146Add a module and setup all helpers. You can select the type of the library; the
147default is ``MODULE``. There are several options:
148
149``OPT_SIZE``
150  Optimize for size, even if the ``CMAKE_BUILD_TYPE`` is not ``RelSize``.
151``THIN_LTO``
152  Use thin TLO instead of regular if there's a choice (pybind11's selection
153  is disabled if ``CMAKE_INTERPROCEDURAL_OPTIMIZATIONS`` is set).
154``WITHOUT_SOABI``
155  Disable the SOABI component (``PYBIND11_NEWPYTHON`` mode only).
156``NO_EXTRAS``
157  Disable all extras, exit immediately after making the module.
158
159pybind11_strip
160^^^^^^^^^^^^^^
161
162.. code-block:: cmake
163
164  pybind11_strip(<target>)
165
166Strip a target after building it (linux/macOS), called by ``pybind11_add_module``.
167
168pybind11_extension
169^^^^^^^^^^^^^^^^^^
170
171.. code-block:: cmake
172
173    pybind11_extension(<target>)
174
175Sets the Python extension name correctly for Python on your platform, called by
176``pybind11_add_module``.
177
178pybind11_find_import(module)
179^^^^^^^^^^^^^^^^^^^^^^^^^^^^
180
181.. code-block:: cmake
182
183    pybind11_find_import(<module> [VERSION <number>] [REQUIRED] [QUIET])
184
185See if a module is installed. Use the registered name (the one on PyPI). You
186can specify a ``VERSION``, and you can specify ``REQUIRED`` or ``QUIET``. Only available if
187``NOPYTHON`` mode is not active.  Sets ``module_VERSION`` and ``module_FOUND``. Caches the
188result once a valid install is found.
189
190Suggested usage
191===============
192
193Using ``find_package`` with version info is not recommended except for release versions.
194
195.. code-block:: cmake
196
197  find_package(pybind11 CONFIG)
198  find_package(pybind11 2.0 EXACT CONFIG REQUIRED)
199
200#]=============================================================================]
201@PACKAGE_INIT@
202
203# Location of pybind11/pybind11.h
204set(pybind11_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/@CMAKE_INSTALL_INCLUDEDIR@")
205
206set(pybind11_LIBRARY "")
207set(pybind11_DEFINITIONS USING_pybind11)
208set(pybind11_VERSION_TYPE "@pybind11_VERSION_TYPE@")
209
210check_required_components(pybind11)
211
212if(TARGET pybind11::python_link_helper)
213  # This has already been setup elsewhere, such as with a previous call or
214  # add_subdirectory
215  return()
216endif()
217
218include("${CMAKE_CURRENT_LIST_DIR}/pybind11Targets.cmake")
219
220# Easier to use / remember
221add_library(pybind11::headers IMPORTED INTERFACE)
222set_target_properties(pybind11::headers PROPERTIES INTERFACE_LINK_LIBRARIES
223                                                   pybind11::pybind11_headers)
224
225include("${CMAKE_CURRENT_LIST_DIR}/pybind11Common.cmake")
226
227if(NOT pybind11_FIND_QUIETLY)
228  message(
229    STATUS
230      "Found pybind11: ${pybind11_INCLUDE_DIR} (found version \"${pybind11_VERSION}\" ${pybind11_VERSION_TYPE})"
231  )
232endif()
233