From 47a81e74b8d206b919c8b710fa10323e22d2b43d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Fri, 15 Feb 2019 15:59:29 +0100
Subject: [PATCH] doc: include handy links for Xcode (AppleClang) and MSVC
 version mapping.

---
 doc/platforms-macos.dox   | 24 ++++++++++++++++++++++++
 doc/platforms-windows.dox | 21 +++++++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/doc/platforms-macos.dox b/doc/platforms-macos.dox
index c11c64ed8..1a79b02fb 100644
--- a/doc/platforms-macos.dox
+++ b/doc/platforms-macos.dox
@@ -124,6 +124,30 @@ advertised programmatically. In case of CMake, you have to supply a custom
 </plist>
 @endcode
 
+@section platforms-macos-clang-version-mapping Clang version mapping
+
+Apple Clang has a different versioning scheme from upstream Clang, making it
+hard to know which Clang version corresponds to which Apple Clang version.
+Wikipedia has a [handy version mapping table](https://en.wikipedia.org/wiki/Xcode#Latest_versions).
+
+CMake exposes Apple Clang as `AppleClang`, so a complete check for e.g.
+upstream version 5 needs to look like this:
+
+@code{.cmake}
+if((CMAKE_CXX_COMPILER_ID STREQUAL "Clang" AND NOT
+    CMAKE_CXX_COMPILER_VERSION VERSION_LESS "5.0") OR
+   (CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang" AND NOT
+    CMAKE_CXX_COMPILER_VERSION VERSION_LESS "9.3"))
+    # Code requiring Clang 5 and newer
+endif()
+@endcode
+
+@note CMake supports `VERSION_GREATER_EQUAL` in the @cb{.cmake} if() @ce
+    statement only [since version 3.7](https://cmake.org/cmake/help/latest/release/3.7.html#commands),
+    use a negated `VERSION_LESS` like above in older versions.
+
+@see @ref platforms-windows-msvc-version-mapping
+
 @section platforms-macos-opengl-best-practices Best practices
 
 Official Apple documentation:
diff --git a/doc/platforms-windows.dox b/doc/platforms-windows.dox
index 090fd7a8d..a295b79d1 100644
--- a/doc/platforms-windows.dox
+++ b/doc/platforms-windows.dox
@@ -88,6 +88,27 @@ property and optionally set their location with `VS_DEPLOYMENT_LOCATION`. If
 you are using `*.resw` files, these need to have the `VS_TOOL_OVERRIDE`
 property set to `PRIResource`.
 
+@section platforms-windows-msvc-version-mapping MSVC version mapping
+
+MSVC and Visual Studio use three, er, four different versioning schemes. CMake
+exposes compiler version equivalent to the `_MSC_VER` macro, see this
+[handy Wikipedia table](https://en.wikipedia.org/wiki/Microsoft_Visual_C%2B%2B#Internal_version_numbering)
+for mapping to Visual Studio versions. For example, a check for MSVC 2017
+would look like this:
+
+@code{.cmake}
+if(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC" AND NOT
+   CMAKE_CXX_COMPILER_VERSION VERSION_LESS "19.10")
+    # Code requiring MSVC 2017
+endif()
+@endcode
+
+@note CMake supports `VERSION_GREATER_EQUAL` in the @cb{.cmake} if() @ce
+    statement only [since version 3.7](https://cmake.org/cmake/help/latest/release/3.7.html#commands),
+    use a negated `VERSION_LESS` like above in older versions.
+
+@see @ref platforms-macos-clang-version-mapping
+
 @todoc DLL paths
 @todoc vcpkg
 @todoc desktop ES