fix: address review points from @YannickJadoul

.appveyor.yml

@@ -26,7 +26,7 @@ install:
     $env:CMAKE_INCLUDE_PATH = "eigen-eigen-67e894c6cd8f;$env:CMAKE_INCLUDE_PATH"
 build_script:
 - cmake -G "%CMAKE_GENERATOR%" -A "%CMAKE_ARCH%"
-    -DPYBIND11_CPP_STANDARD=/std:c++14
+    -DCMAKE_CXX_STANDARD=14
     -DPYBIND11_WERROR=ON
     -DDOWNLOAD_CATCH=ON
     -DCMAKE_SUPPRESS_REGENERATION=1

docs/compiling.rst

@@ -103,9 +103,9 @@ standard explicitly with
 
 .. code-block:: cmake
 
-    # Use just one of these:
-    set(CMAKE_CXX_STANDARD 14)
-    set(CMAKE_CXX_STANDARD 17)
+    set(CMAKE_CXX_STANDARD 14)  # or 11, 14, 17, 20
+    set(CMAKE_CXX_STANDARD_REQUIRED ON)  # optional, ensure standard is supported
+    set(CMAKE_CXX_EXTENSIONS OFF)  # optional, keep compiler extensionsn off
 
 
 The variables can also be set when calling CMake from the command line using
@@ -120,7 +120,11 @@ For example:
 .. code-block:: bash
 
     cmake -DPYBIND11_PYTHON_VERSION=3.6 ..
-    # or
+
+    # Another method:
+    cmake -DPYTHON_EXECUTABLE=/path/to/python ..
+
+    # You will often see this idiom:
     cmake -DPYTHON_EXECUTABLE=$(python3 -c "import sys; print(sys.executable)") ..
 
 find_package vs. add_subdirectory
@@ -144,12 +148,19 @@ 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
@@ -198,11 +209,11 @@ to an independently constructed (through ``add_library``, not
 
     .. code-block:: cmake
 
-        cmake_minimum_required(3.9)
         set(CMAKE_CXX_VISIBILITY_PRESET hidden)
-        set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON)
+        set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)
+        set(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON)  # CMake 3.9+ required
 
-    or set teh corisponding property (without the ``CMAKE_``) on the targets
+    or set the corresponding property (without the ``CMAKE_``) on the targets
     manually.
 
 Embedding the Python interpreter

tools/pybind11Config.cmake.in

@@ -60,17 +60,15 @@
 
 @PACKAGE_INIT@
 
-set(PN pybind11)
+# Location of pybind11/pybind11.h
+set(pybind11_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/@CMAKE_INSTALL_INCLUDEDIR@")
 
-# location of pybind11/pybind11.h
-set(${PN}_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/@CMAKE_INSTALL_INCLUDEDIR@")
+set(pybind11_LIBRARY "")
+set(pybind11_DEFINITIONS USING_pybind11)
 
-set(${PN}_LIBRARY "")
-set(${PN}_DEFINITIONS USING_${PN})
+check_required_components(pybind11)
 
-check_required_components(${PN})
-
-# make detectable the FindPythonLibsNew.cmake module
+# Make the FindPythonLibsNew.cmake module available
 list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR})
 
 include(pybind11Tools)
@@ -79,19 +77,20 @@ include(pybind11Tools)
 # Don't include targets if this file is being picked up by another
 # project which has already built this as a subproject
 #-----------------------------------------------------------------------------
-if(NOT TARGET ${PN}::pybind11)
-    include("${CMAKE_CURRENT_LIST_DIR}/${PN}Targets.cmake")
+if(NOT TARGET pybind11::pybind11)
+    include("${CMAKE_CURRENT_LIST_DIR}/pybind11Targets.cmake")
 
     find_package(PythonLibsNew ${PYBIND11_PYTHON_VERSION} MODULE REQUIRED)
-    set_property(TARGET ${PN}::pybind11 APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES ${PYTHON_INCLUDE_DIRS})
-    set_property(TARGET ${PN}::pybind11 APPEND PROPERTY INTERFACE_SYSTEM_INCLUDE_DIRECTORIES ${PYTHON_INCLUDE_DIRS})
-    set_property(TARGET ${PN}::embed APPEND PROPERTY INTERFACE_LINK_LIBRARIES ${PYTHON_LIBRARIES})
-    if(WIN32 OR CYGWIN)
-      set_property(TARGET ${PN}::module APPEND PROPERTY INTERFACE_LINK_LIBRARIES ${PYTHON_LIBRARIES})
-    endif()
 
-    get_property(_iid TARGET ${PN}::pybind11 PROPERTY INTERFACE_INCLUDE_DIRECTORIES)
-    get_property(_ill TARGET ${PN}::module PROPERTY INTERFACE_LINK_LIBRARIES)
-    set(${PN}_INCLUDE_DIRS ${_iid})
-    set(${PN}_LIBRARIES ${_ico} ${_ill})
+    set_property(TARGET pybind11::pybind11 APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES ${PYTHON_INCLUDE_DIRS})
+    set_property(TARGET pybind11::pybind11 APPEND PROPERTY INTERFACE_SYSTEM_INCLUDE_DIRECTORIES ${PYTHON_INCLUDE_DIRS})
+
+    set_property(TARGET pybind11::embed APPEND PROPERTY INTERFACE_LINK_LIBRARIES ${PYTHON_LIBRARIES})
+    set_property(TARGET pybind11::module APPEND PROPERTY INTERFACE_LINK_LIBRARIES
+        "$<$<OR:$<PLATFORM_ID:Windows>,$<PLATFORM_ID:Cygwin>>:$<BUILD_INTERFACE:${PYTHON_LIBRARIES}>>")
+
+    get_property(_iid TARGET pybind11::pybind11 PROPERTY INTERFACE_INCLUDE_DIRECTORIES)
+    get_property(_ill TARGET pybind11::module PROPERTY INTERFACE_LINK_LIBRARIES)
+    set(pybind11_INCLUDE_DIRS ${_iid})
+    set(pybind11_LIBRARIES ${_ico} ${_ill})
 endif()

tools/pybind11Tools.cmake

@@ -27,15 +27,20 @@ find_package(PythonLibsNew ${PYBIND11_PYTHON_VERSION} REQUIRED)
 include(CheckCXXCompilerFlag)
 include(CMakeParseArguments)
 
-# Use the language standards abstraction if CMake supports it with the current compiler
+# Warn or error if old variable name used
 if(PYBIND11_CPP_STANDARD)
-    message(WARNING "USE -DCMAKE_CXX_STANDARD=11 instead of PYBIND11_PYTHON_VERSION")
     if(NOT CMAKE_CXX_STANDARD)
         string(REGEX MATCH
             [=[..^]=]
             VAL
             "${PYBIND11_CPP_STANDARD}")
+        set(supported_standards 11 14 17 20)
+        if("${VAL}" IN_LIST supported_standards)
+            message(WARNING "USE -DCMAKE_CXX_STANDARD=${VAL} instead of PYBIND11_PYTHON_VERSION")
             set(CMAKE_CXX_STANDARD ${VAL})
+        else()
+            message(FATAL_ERROR "PYBIND11_CPP_STANDARD should be replaced with CMAKE_CXX_STANDARD")
+        endif()
     endif()
 endif()