[feature] More customization options for Platform and PlatformToolset in MSBuildToolchain

[sykhro]

What is your suggestion?

I use conan to manage packages built against the GDK, the Microsoft framework for developing games.
This platform

• is Windows
• has a Win32 partition, WINAPI_PARTITION_GAMES (as WINAPI_PARTITION_APP is to UWP)
• targets Gaming.Desktop.x64, Xbox if you are licensed

Most of this knowledge is public and vcpkg implements support for it: info.

The GDK is therefore a set of additional platforms/toolset for VS.
CMake is supported via VS_*_PROPS and there are examples of usage with Ninja.
However, due to the nature (industry) of the platform and the fact it's still Windows, it's very useful to have MSBuildToolchain support since many projects (and ports) are native to VS. SDL, to name one*

For now, I have settled on the following, using a custom arch to override the VS platform

[settings]
os=Windows
arch=Gaming.Xbox.Scarlett.x64
build_type=Debug

compiler=clang
compiler.version=17
compiler.runtime=dynamic
compiler.runtime_type=Debug
compiler.runtime_version=v143
 
[conf]
tools.cmake.cmaketoolchain:generator=Visual Studio 17
tools.cmake.cmaketoolchain:user_toolchain=['path/to/the/toolchain.cmake']

[buildenv]
GXDKEDITION=240300
CMAKE_C_COMPILER=clang-cl.exe
CMAKE_CXX_COMPILER=clang-cl.exe

*not the greatest choice of example since I'll contribute adding it to CMake soon, but oh well

Have you read the CONTRIBUTING guide?

• I've read the CONTRIBUTING guide

[memsharded]

Hi @sykhro

Thanks for your suggestion.

I am trying to understand these customizations, but I don't know about these platforms, so I am a bit lost at the moment.
It would be great to understand what properties are changed in the project.vcxproj to be able to know what properties can MSBuildToolchain define in its conantoolchain.props file to inject the necessary definitions to define such an Xbox build.

Also, what kind of things goes into tools.cmake.cmaketoolchain:user_toolchain=['path/to/the/toolchain.cmake']? Because they would also be needed in the MSBuild .vcxproj, or .props files?

Do you have any suggestion or recommendation of Conan settings to model these platforms? Are these subsettings of the Windows "os"? It is even Windows OS to start, or it should be a different OS?

[sykhro]

It would be great to understand what properties are changed in the project.vcxproj to be able to know what properties can MSBuildToolchain define in its conantoolchain.props file to inject the necessary definitions to define such an Xbox build.

If GDK is installed system-wide as a VS add-on, the main thing that needs changing is the Platform property. With GDK, there are three platforms at the moment:

• Gaming.Desktop.x64: Windows Desktop, x64
• Gaming.Xbox.Scarlett.x64: Xbox Series X|S (covered by NDA)
• Gaming.Xbox.XboxOne.x64: Xbox One X (covered by NDA)

You can use the public GDK from the VS installer. This will give you Gaming.Desktop.x64.
After you have sourced a specific vcvars ("Gaming Command Prompt"), VS will know what headers and libraries to pick by just changing Platform to one of these.
If you don't rely on that or are using a portable archive (BWOI), the process is described in the GDK docs and it's much more complicated.

Also, what kind of things goes into tools.cmake.cmaketoolchain:user_toolchain=['path/to/the/toolchain.cmake']?

• CMAKE_GENERATOR_PLATFORM
• CMAKE_VS_PLATFORM_NAME
• A couple macro defines

Essentially telling CMake "hey, use the VS generator with the props for this platform when you compile". The core compiler flags and system includes are set by the VS props and we don't control those.

You can look at one of the official examples here.

Because they would also be needed in the MSBuild .vcxproj, or .props files?

Yes, it would be shared

Are these subsettings of the Windows "os"? It is even Windows OS to start, or it should be a different OS?

Yes, this is Windows. The compiler defines _WIN32 and uses the Windows SDK. The peculiarity is that it defines WINAPI_PARTITION_GAMES, and that disables some stuff in Windows.h.
Developers are supposed to check the value of WINAPI_PARTITION to avoid compiling unsupported api calls.
For example, WINAPI_PARTITION_GAMES doesn't implement: Clipboard, cmd stuff to set the text foreground/background color, shell calls such as _chdir, pre-unicode wstring manipulation functions (it's all UTF-8), ...

Xbox has some extra things that don't exist on Windows Desktop. The community has chosen to check for XBOX_CONSOLE_TARGET when CMAKE_SYSTEM_NAME = Windows to be able to differentiate the two. This is currently used by some OSS DirectX projects. With MSBuild you wouldn't care much about this obviously, since you distinguish things by Platform

Please note that this approach of defining a custom platform in VS is common among game console vendors. On those, at the moment, we scrape by with Ninja and custom CMake toolchain files: better build performance, the setup is simpler but also more flexible in defining post-build steps that are necessary to package executables to.. make them executable. They are also proprietary operating systems.