Make PYBIND11_CPP_STANDARD work under MSVC

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.

.appveyor.yml

@@ -11,11 +11,20 @@ platform:
 environment:
   matrix:
   - CONDA: 36
+    CPP: 14
   - CONDA: 27
+    CPP: 14
+  - CONDA: 36
+    CPP: latest
 matrix:
   exclude:
     - image: Visual Studio 2015
       platform: x86
+    - image: Visual Studio 2015
+      CPP: latest
+    - image: Visual Studio 2017
+      CPP: latest
+      platform: x86
 install:
 - ps: |
     if ($env:PLATFORM -eq "x64") { $env:CMAKE_ARCH = "x64" }
@@ -37,7 +46,7 @@ install:
     7z x 3.3.3.zip -y > $null
     $env:CMAKE_INCLUDE_PATH = "eigen-eigen-67e894c6cd8f"
 build_script:
-- cmake -G "%CMAKE_GENERATOR%" -A "%CMAKE_ARCH%" -DPYBIND11_WERROR=ON -DCMAKE_SUPPRESS_REGENERATION=1
+- cmake -G "%CMAKE_GENERATOR%" -A "%CMAKE_ARCH%" -DPYBIND11_CPP_STANDARD=/std:c++%CPP% -DPYBIND11_WERROR=ON -DCMAKE_SUPPRESS_REGENERATION=1
 - set MSBuildLogger="C:\Program Files\AppVeyor\BuildAgent\Appveyor.MSBuildLogger.dll"
 - cmake --build . --config Release --target pytest -- /v:m /logger:%MSBuildLogger%
 - cmake --build . --config Release --target test_cmake_build -- /v:m /logger:%MSBuildLogger%

docs/compiling.rst

@@ -92,17 +92,28 @@ regular LTO if ``-flto=thin`` is not available.
 Configuration variables
 -----------------------
 
-By default, pybind11 will compile modules with the latest C++ standard
-available on the target compiler. To override this, the standard flag can
-be given explicitly in ``PYBIND11_CPP_STANDARD``:
+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
+``PYBIND11_CPP_STANDARD``:
 
 .. code-block:: cmake
 
+    # Use just one of these:
+    # GCC/clang:
     set(PYBIND11_CPP_STANDARD -std=c++11)
+    set(PYBIND11_CPP_STANDARD -std=c++14)
+    set(PYBIND11_CPP_STANDARD -std=c++1z) # Experimental C++17 support
+    # MSVC:
+    set(PYBIND11_CPP_STANDARD /std:c++14)
+    set(PYBIND11_CPP_STANDARD /std:c++latest) # Enables some MSVC C++17 features
+
     add_subdirectory(pybind11)  # or find_package(pybind11)
 
 Note that this and all other configuration variables must be set **before** the
-call to ``add_subdiretory`` or ``find_package``. The variables can also be set
+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 target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION``

tools/pybind11Tools.cmake

@@ -19,7 +19,8 @@ include(CheckCXXCompilerFlag)
 include(CMakeParseArguments)
 
 function(select_cxx_standard)
-  if(NOT MSVC AND NOT PYBIND11_CPP_STANDARD)
+  if(NOT PYBIND11_CPP_STANDARD)
+    if(NOT MSVC)
       check_cxx_compiler_flag("-std=c++14" HAS_CPP14_FLAG)
       check_cxx_compiler_flag("-std=c++11" HAS_CPP11_FLAG)
 
@@ -30,9 +31,12 @@ function(select_cxx_standard)
       else()
         message(FATAL_ERROR "Unsupported compiler -- pybind11 requires C++11 support!")
       endif()
+    elseif(MSVC)
+      set(PYBIND11_CPP_STANDARD /std:c++14)
+    endif()
 
     set(PYBIND11_CPP_STANDARD ${PYBIND11_CPP_STANDARD} CACHE STRING
-        "C++ standard flag, e.g. -std=c++11 or -std=c++14. Defaults to latest available." FORCE)
+        "C++ standard flag, e.g. -std=c++11, -std=c++14, /std:c++14.  Defaults to C++14 mode." FORCE)
   endif()
 endfunction()
 
@@ -162,10 +166,8 @@ function(pybind11_add_module target_name)
   endif()
 
   select_cxx_standard()
-  if(NOT MSVC)
   # Make sure C++11/14 are enabled
   target_compile_options(${target_name} PUBLIC ${PYBIND11_CPP_STANDARD})
-  endif()
 
   if(ARG_NO_EXTRAS)
     return()