What does the `Target Platform Version` mean for a VS C++ project?

Question

BACKGROUND

As I understand it, in a C++ project:

• Project Properties => Configuration Properties => General => Platform Toolset
  • Tells the compiler which SDK to physically compile against.
  • For example: v140 will tell Visual Studio 2015 to use the latest and greatest v8.1 Windows SDK
• _WIN32_WINNT, WINVER, and NTDDI_VERSION macros
  • Depending on the underlying operating system, an SDK function can have a different function signature from OS-to-OS.
  • SDKs are suppose to be backward compatible. 1
  • The before mentioned macros enable you to specify which version of a function you wish to compile against.

MY QUESTION

If I compile my application with the following setup:

• project properties => configuration properties => General => Platform Toolset
  • set to: v140_xp (Visual Studio 2015 - Windows XP)
  • Setting tells compiler to use the 7.1 SDK, which makes sense.
• content of: StdAfh.h
  • #include <WinSDKVer.h>
  • #define _WIN32_WINNT 0x0501
  • #define WINVER 0x0501
  • #define NTDDI_VERSION 0x05010000
  • #include <SDKDDKVer.h>
  • Macros tell compiler which function signatures to use, which makes sense.

From what I can tell, it looks like Target Platform Version is an suposed to be an alternative to the _WIN32_WINNT, WINVER, and NTDDI_VERSION macros. The weird thing is, with the above configuration you can set the Target Platform Version to 1 or 99... and the compiler doesn't generate any errors or warnings.

This this leaves me wondering: What is the Target Platform Version for?

ADDITIONAL CONTEXT

• Compiler: Visual Studio 2015

REFERENCES

• Windows SDK Brokenness
• Target Platform Version general project property on VS2015
• Using the Windows Headers
• What is WINVER?
• Modifying WINVER and _WIN32_WINNT
• Visual Studio setting WINVER/_WIN32_WINNT to Windows 8 on Windows 7?

EDIT HISTORY

• 2016/09/21: As per Hans' comment, macros have been updated to reference Windows XP.

Answer 1

The following summarizes the differences between the Windows SDK Version & the Platform Toolset configuration properties.

Windows SDK Version

Important: Sometimes this property is referred to as Target Platform Version

Thankfully, this subject has been updated in Microsoft's MSDN. The following was taken directly from C++ project property pages.

this specifies the version of the Windows SDK that your project requires. When you install a C++ Workload by using the Visual Studio installer, the required parts of the Windows SDK are also installed. If you have other Windows SDK versions on your computer, each version of the SDK tools that you have installed appears in the dropdown.

To target Windows 7 or Windows Vista, use the value 8.1, since Windows SDK 8.1 is backward compatible to those platforms. In addition, you should define the appropriate value for _WIN32_WINNT in targetver.h. For Windows 7, that's 0x0601.

For those of you who don't know, any given Windows SDK is [mostly] backwards compatible with older versions of the Windows SDK. For example, you could configure your C++ project with the following:

1. C++ project => Properties => Configuration Properties => General
   • Target Platform Version = 10
     • This SDK enables you to leverage the capabilities of the Windows 10 operating system.
2. Add a header file called TargetVer.h to your project that includes the following pre-processor macros:
   • #define WINVER 0x0603 // Windows 8.1
   • #define _WIN32_WINNT 0x0603 // Windows 8.1

For more information, please see:

• What is SDKDDKVer.h for?
• Modifying WINVER and _WIN32_WINNT
  • Includes a list of constants for the various SDKs.
• See summary of: Windows SDK options

Platform Toolset

This property specifies the following for your C++ project:

1. the compiler
   • For example: v142 results in the the Visual Studio 2019 compiler being used
2. the Visual C++ library
   • For example: v142 indicates that you are using the Visual Studio 2019 C++ library
     • Which means that, your application will need the Visual Studio 2019 C++ Redistributable (MSVCRxxx.dll) during deployment.
   • MSVCR
     • MS = Microsoft
     • V = Visual
     • C = C++
     • R = Redistributable
   • The redistributable is installed to:
     • C:\Windows\
     • C:\Windows\SysWOW64\
   • Your application can determine which C++ library is being used by referencing the _MSC_VER pre-processor macro.

It is worth noting that:

1. The Platform Toolset is a project level setting (see PlatformToolset in *.vcxproj), whereas, the selected Windows SDK Version is saved elsewhere.
2. The name of a Platform Toolset value can be somewhat confusing because:
   • The value (e.g. v142) is associated with a Visual Studio release (e.g. Visual Studio 2019)
   • Rather than install the Visual Studio IDE, you can install Build Tools. This is useful when working with build machines.

For more information, please see:

• See summary of: Platform Toolset options
• C++ Binary Compatibility and Pain-Free Upgrades to Visual Studio 2019
• Predefined PreProcessor Macros
  • Includes a list of possible _MSC_VER values and their meanings
• Announcing Visual C++ Build Tools 2015