feat: drop CMake 3.6 and below, modernize CMake
fix: include PYTHON_IS_DEBUG
diff --git a/docs/compiling.rst b/docs/compiling.rst
index bfb1cd8..dce44c8 100644
--- a/docs/compiling.rst
+++ b/docs/compiling.rst
@@ -33,7 +33,7 @@
.. code-block:: cmake
- cmake_minimum_required(VERSION 2.8.12)
+ cmake_minimum_required(VERSION 3.7)
project(example)
add_subdirectory(pybind11)
@@ -59,7 +59,7 @@
.. code-block:: cmake
pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL]
- [NO_EXTRAS] [SYSTEM] [THIN_LTO] source1 [source2 ...])
+ [NO_EXTRAS] [THIN_LTO] 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
@@ -86,10 +86,6 @@
given, they will always be disabled, even in ``Release`` mode. However, this
will result in code bloat and is generally not recommended.
-By default, pybind11 and Python headers will be included with ``-I``. In order
-to include pybind11 as system library, e.g. to avoid warnings in downstream
-code with warn-levels outside of pybind11's scope, set the option ``SYSTEM``.
-
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
@@ -100,25 +96,22 @@
Configuration variables
-----------------------
-By default, pybind11 will compile modules with the C++14 standard, if available
-on the target compiler, falling back to C++11 if C++14 support is not
-available. Note, however, that this default is subject to change: future
-pybind11 releases are expected to migrate to newer C++ standards as they become
-available. To override this, the standard flag can be given explicitly in
-`CMAKE_CXX_STANDARD <https://cmake.org/cmake/help/v3.17/variable/CMAKE_CXX_STANDARD.html>`_:
+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
# Use just one of these:
- set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD 14)
- set(CMAKE_CXX_STANDARD 17) # Experimental C++17 support
+ set(CMAKE_CXX_STANDARD 17)
- add_subdirectory(pybind11) # or find_package(pybind11)
-Note that this and all other configuration variables must be set **before** the
-call to ``add_subdirectory`` or ``find_package``. The variables can also be set
-when calling CMake from the command line using the ``-D<variable>=<value>`` flag.
+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.
The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION``
or an exact Python installation can be specified with ``PYTHON_EXECUTABLE``.
@@ -128,7 +121,7 @@
cmake -DPYBIND11_PYTHON_VERSION=3.6 ..
# or
- cmake -DPYTHON_EXECUTABLE=path/to/python ..
+ cmake -DPYTHON_EXECUTABLE=$(python3 -c "import sys; print(sys.executable)") ..
find_package vs. add_subdirectory
---------------------------------
@@ -139,7 +132,7 @@
.. code-block:: cmake
- cmake_minimum_required(VERSION 2.8.12)
+ cmake_minimum_required(VERSION 3.7)
project(example)
find_package(pybind11 REQUIRED)
@@ -171,13 +164,13 @@
When using a version of CMake greater than 3.0, pybind11 can additionally
be used as a special *interface library* . The target ``pybind11::module``
is available with pybind11 headers, Python headers and libraries as needed,
-and C++ compile definitions attached. This target is suitable for linking
+and C++ compile features attached. This target is suitable for linking
to an independently constructed (through ``add_library``, not
``pybind11_add_module``) target in the consuming project.
.. code-block:: cmake
- cmake_minimum_required(VERSION 3.0)
+ cmake_minimum_required(VERSION 3.7)
project(example)
find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11)
@@ -201,6 +194,17 @@
Studio (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an
explanation on why these are needed.
+ If you want to add these in yourself, you can use:
+
+ .. code-block:: cmake
+
+ cmake_minimum_required(3.9)
+ set(CMAKE_CXX_VISIBILITY_PRESET hidden)
+ set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON)
+
+ or set teh corisponding property (without the ``CMAKE_``) on the targets
+ manually.
+
Embedding the Python interpreter
--------------------------------
@@ -213,7 +217,7 @@
.. code-block:: cmake
- cmake_minimum_required(VERSION 3.0)
+ cmake_minimum_required(VERSION 3.7)
project(example)
find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11)