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

In Visual Studio 2015 the Target Platform Version field just sets the version of the Windows SDK to use. See this MSDN article for reference. In Visual Studio 2019, this field has been renamed Windows SDK Version. You still need to set _WIN32_WINNT, WINVER, and NTDDI_VERSION macros, as well as the Platform Toolset field. Taken together they determine the versions of Windows your app can run on.

If your applications need to run on Windows XP, you have to pick a Platform Toolset ending in _xp, select an older Windows SDK Version (you need 7.1A, but picking 7.0 or 8.1 should work; see below), and set _WIN32_WINNT, WINVER, and NTDDI_VERSION macros accordingly. See this Stack Overflow posting for tips on setting these macros and including related SDK headers via targetver.h.

If building from a Command Prompt with an _xp platform toolset see this Stack Overflow posting for tips on setting the /SUBSYSTEM linker option and for defining _USING_V110_SDK71_.

Windows SDKs are backward-compatible, but I haven't yet found a clear reference which lists the oldest version of Windows you can target when building with a given version of the Windows SDK (see EDIT at the bottom of this post). Each SDK lists "System Requirements", but these list the minimum version of Windows needed to develop with the SDK, not the minimum version of Windows that executables built with that SDK can target. The best reference I know of is the sdkddkver.h header in each of the newer Windows SDKs. Within this header are a list of _WIN32_WINNT version constants. For example, in the Windows 7.1A SDK, sdkddkver.h defines _WIN32_WINNT_NT4 as the oldest supported Windows platform (but I do not know if this is definitive).

The rest of this answer are notes regarding targeting for native VC++ apps using Visual Studio 2019. These notes may apply to older Visual Studio versions as well.

---

In Visual Studio 2019, selecting a Platform Toolset which ends in _xp has certain quirks. For v120_xp, the Windows SDK Version field is hidden, but the inherited VC++ Directories will show that the Windows SDK 7.1A directory is specified. For v140_xp and v141_xp platform toolsets, you can pick Windows SDK 7.0 or 8.1 (for either, the inherited VC++ Directories will show that the Windows SDK 7.1A directory is specified).

I am not sure what the difference is - if any - between specifying Windows SDK Version 7.0 or 8.1 when using Platform Toolset v140_xp or v141_xp in Visual Studio 2019.

In Visual Studio 2019, when setting native C++ project properties for a Windows Desktop app, depending on the Platform Toolset you select, the read-only Target Platform field may change to "Windows 10". But this DOES NOT mean your Win32 desktop app will be built as a Universal Windows Platform app. It will still work on older versions of Windows depending on the Platform Toolset, Windows SDK Version and the values for the _WIN32_WINNT, WINVER, and NTDDI_VERSION macros.

Microsoft could update VS2019 so the Target Platform field value would show just "Windows" when setting properties for Win32/desktop projects, regardless of the selected Platform Toolset or Windows SDK Version.

EDIT: See the article A Brief History of Windows SDKs from Chuck Walbourn, Senior Engineer for Xbox at Microsoft, for details regarding backward compatibility of various Windows SDKs.

Answer 2

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