GitLab

builds against a python debug library were unreliable and
could lead to symbol errors during linking.

Setting the `Py_DEBUG` define is necessary when linking
against a debug build:

https://stackoverflow.com/questions/39161202/how-to-work-around-missing-pymodule-create2-in-amd64-win-python35-d-lib

https://docs.python.org/2/c-api/intro.html#debugging-builds

https://docs.python.org/3.6/c-api/intro.html#debugging-builds

CMAKE_CXX_STANDARD is only available on CMake >= 3.1. If the flag is
set, we avoid initializing PYBIND11_CPP_STANDARD.

This updates the compilation to always apply hidden visibility to
resolve the issues with default visibility causing problems under debug
compilations.  Moreover using the cmake property makes it easier for a
caller to override if absolutely needed for some reason.

For `pybind11_add_module` we use cmake to set the property; for the
targets, we append to compilation option to non-MSVC compilers.

Currently select_cxx_standard(), which sets PYBIND11_CPP_STANDARD when
not externally set, is only called from pybind11_add_module(), but the
embed target setup (which runs unconditionally) makes use of
${PYBIND11_CPP_STANDARD}, which isn't set yet.  This commit removes the
`select_cxx_standard` function completely and just always runs the
standard detection code.

This also tweaks the detection code to not bothering checking for the
`-std=c++11` flag when the `-std=c++14` detection succeeded.

Under MSVC we were ignoring PYBIND11_CPP_STANDARD and simply not
passing any standard (which makes MSVC default to its C++14 mode).

MSVC 2015u3 added the `/std:c++14` and `/std:c++latest` flags; the
latter, under MSVC 2017, enables some C++17 features (such as
`std::optional` and `std::variant`), so it is something we need to
start supporting under MSVC.

This makes the PYBIND11_CPP_STANDARD cmake variable work under MSVC,
defaulting it to /std:c++14 (matching the default -std=c++14 for
non-MSVC).

It also adds a new appveyor test running under MSVC 2017 with
/std:c++latest, which runs (and passes) the
`std::optional`/`std::variant` tests.

Also updated the documentation to clarify the c++ flags and add show
MSVC flag examples.

This both lets us not bother rechecking LTO flags when cmake reinvokes
itself, and also lets the cmake invoker override to specify custom or
no LTO flags by setting the cache variable with
-DPYBIND11_LTO_CXX_FLAGS= when invoking cmake.

Clang on linux currently fails to run cmake:

    $ CC=clang CXX=clang++ cmake ..
    ...
    -- Configuring done
    CMake Error at tools/pybind11Tools.cmake:135 (target_compile_options):
      Error evaluating generator expression:

        $<:-flto>

      Expression did not evaluate to a known generator expression
    Call Stack (most recent call first):
      tests/CMakeLists.txt:68 (pybind11_add_module)

But investigating this led to various other -flto detection problems;
this commit thus overhauls LTO flag detection:

- -flto needs to be passed to the linker as well
- Also compile with -fno-fat-lto-objects under GCC
- Pass the equivalent flags to MSVC
- Enable LTO flags for via generator expressions (for non-debug builds
  only), so that multi-config builds (like on Windows) still work
  properly.  This seems reasonable, however, even on single-config
  builds (and simplifies the cmake code a bit).
- clang's lto linker plugins don't accept '-Os', so replace it with
  '-O3' when doing a MINSIZEREL build
- Enable trying ThinLTO by default for test suite (only affects clang)
- Match Clang$ rather than ^Clang$ because, for cmake with 3.0+
  policies in effect, the compiler ID will be AppleClang on macOS.

This way a non-CACHE variable can also be used. For example:
```
set(PYBIND11_PYTHON_VERSION <value>)
add_subdirectory(...)
```

See the documentation for a description of the options.

Add a BUILD_INTERFACE and a pybind11::pybind11 alias for the interface
library to match the installed target.

Add new cmake tests for add_subdirectory and consolidates the
.cpp and .py files needed for the cmake build tests:

Before:
tests
|-- test_installed_module
|   |-- CMakeLists.txt
|   |-- main.cpp
|   \-- test.py
\-- test_installed_target
    |-- CMakeLists.txt
    |-- main.cpp
    \-- test.py

After:
tests
\-- test_cmake_build
    |-- installed_module/CMakeLists.txt
    |-- installed_target/CMakeLists.txt
    |-- subdirectory_module/CMakeLists.txt
    |-- subdirectory_target/CMakeLists.txt
    |-- main.cpp
    \-- test.py