Merge branch 'msvc-version-abi-compat'

Add wxMSVC_VERSION_ABI_COMPAT.

See https://github.com/wxWidgets/wxWidgets/pull/1576

docs/doxygen/mainpages/const_cpp.h

@@ -208,16 +208,47 @@ Currently the following symbols exist:
 
 
 
-@section page_cppconst_msvc_setup_h Library Selection for MSVC
+@section page_cppconst_msvc_setup_h MSVC-specific Symbols
 
 Microsoft Visual C++ users may use the special @c wx/setup.h file for this
 compiler in @c include/msvc subdirectory. This file implicitly links in all the
 wxWidgets libraries using MSVC-specific pragmas which usually is much more
 convenient than manually specifying the libraries list in all of the project
-configurations. However sometimes linking with all the libraries is not
+configurations.
-desirable, for example because some of them were not built and this is where
+
-the symbols in this section can be helpful: defining them allows to not link
+By default, the pragmas used in this file to actually link with wxWidgets
-with the corresponding library. The following symbols are honoured:
+libraries suppose that the libraries are located in @c vc_lib or @c vc_dll
+directory which is used by default. However when using multiple MSVC versions,
+or when using the @ref plat_msw_binaries "official binaries", the libraries are
+in a directory containing the compiler version number, e.g. @c vc140_dll. To
+make linking work in this case, you must predefine @c wxMSVC_VERSION as @c
+vc140 <em>before</em> include @c wx/setup.h file, i.e. typically in the MSVS
+project options. Alternatively, you can predefine @c wxMSVC_VERSION_AUTO symbol
+(without any value), which means that the appropriate compiler version should
+be used automatically, e.g. "vc100" for VC 10 (MSVS 2010), "vc140" for VC 14
+(MSVS 2015) etc. Additionally, VC 14 is a special case as it has 3 minor
+versions: VC 14.0, 14.1 and 14.2, corresponding to MSVS 2015, 2017 and 2019;
+that are ABI-compatible with each other. Due to this, it can also be useful to
+reuse the single build of wxWidgets with all versions of the compiler and this
+is supported if @c wxMSVC_VERSION_ABI_COMPAT is defined: the compiler prefix
+"vc14x" is used in this case.
+
+If the makefiles have been used to build the libraries from source and the @c CFG
+variable has been set to specify a different output path for that particular
+configuration of build then the @c wxCFG preprocessor symbol should be set in
+the project that uses wxWidgets to the same value as the @c CFG variable in
+order for the correct @c wx/setup.h file to automatically be included for that
+configuration.
+
+
+@subsection page_cppconst_msvc_setup_h_no_libs Library Selection for MSVC
+
+As explained above, MSVC users don't need to explicitly specify wxWidgets
+libraries to link with, as this is done by @c wx/setup.h. However sometimes
+linking with all the libraries, as is done by default, is not desirable, for
+example because some of them were not built and this is where the symbols in
+this section can be helpful: defining them allows to not link with the
+corresponding library. The following symbols are honoured:
 
     - wxNO_AUI_LIB
     - wxNO_HTML_LIB
@@ -238,13 +269,6 @@ with the corresponding library. The following symbols are honoured:
 Notice that the base library is always included and the core is always included
 for the GUI applications (i.e. those which don't define @c wxUSE_GUI as 0).
 
-If the makefiles have been used to build the libraries from source and the @c CFG
-variable has been set to specify a different output path for that particular
-configuration of build then the @c wxCFG preprocessor symbol should be set in
-the project that uses wxWidgets to the same value as the @c CFG variable in
-order for the correct @c wx/setup.h file to automatically be included for that
-configuration.
-
 
 @section page_cppconst_compatibility Compatibility Macros
 

include/msvc/wx/setup.h

@@ -44,9 +44,16 @@
 // COMPILER_PREFIX=vcXX and in this case you may want to either predefine
 // wxMSVC_VERSION as "XX" or define wxMSVC_VERSION_AUTO to use the appropriate
 // version depending on the compiler used
+//
+// There is an additional complication with MSVC 14.0, 14.1 and 14.2 versions
+// (a.k.a. MSVS 2015, 2017 and 2019): as they're all ABI-compatible with each
+// other, it is convenient to use the same "vc14x" compiler prefix for all of
+// them, but this is not how wxMSVC_VERSION_AUTO behaves by default, so you
+// need to additionally define wxMSVC_VERSION_ABI_COMPAT to opt in into using
+// this "vc14x" prefix.
 #ifdef wxMSVC_VERSION
     #define wxCOMPILER_PREFIX wxCONCAT(vc, wxMSVC_VERSION)
-#elif defined(wxMSVC_VERSION_AUTO)
+#elif defined(wxMSVC_VERSION_AUTO) || defined(wxMSVC_VERSION_ABI_COMPAT)
     #if _MSC_VER == 1200
         #define wxCOMPILER_PREFIX vc60
     #elif _MSC_VER == 1300
@@ -63,12 +70,20 @@
         #define wxCOMPILER_PREFIX vc110
     #elif _MSC_VER == 1800
         #define wxCOMPILER_PREFIX vc120
-    #elif _MSC_VER == 1900
+    #elif _MSC_VER >= 1900 && _MSC_VER < 2000
-        #define wxCOMPILER_PREFIX vc140
+        #ifdef wxMSVC_VERSION_ABI_COMPAT
-    #elif _MSC_VER >= 1910 && _MSC_VER < 1920
+            #define wxCOMPILER_PREFIX vc14x
-        #define wxCOMPILER_PREFIX vc141
+        #else
-    #elif _MSC_VER >= 1920 && _MSC_VER < 2000
+            #if _MSC_VER < 1910
-        #define wxCOMPILER_PREFIX vc142
+                #define wxCOMPILER_PREFIX vc140
+            #elif _MSC_VER >= 1910 && _MSC_VER < 1920
+                #define wxCOMPILER_PREFIX vc141
+            #elif _MSC_VER >= 1920 && _MSC_VER < 2000
+                #define wxCOMPILER_PREFIX vc142
+            #else
+                #error "Unknown MSVC 14.x compiler version, please report to wx-dev."
+            #endif
+        #endif
     #else
         #error "Unknown MSVC compiler version, please report to wx-dev."
     #endif