A CMake toolchain file describes the set of tools and utilities for compiling code in CMake. This repo provides toolchains that describes how to compile using MSVC and Clang in CMake, with the goal of making Windows CMake builds more canonical to reduce the 'barrier-to-entry' to build code for Windows.
This repo contains three toolchains:
-
Windows.MSVC.toolchain.cmake - Uses the MSVC compiler from an installed Visual Studio instance.
-
Windows.Clang.toolchain.cmake - Uses Clang from either an LLVM installation or from a Visual Studio installation.
-
Windows.EWDK.toolchain.cmake - Uses the MSVC compiler from an Enterprise Windows Driver Kit. This toolchain requires that CMake be invoked from an EWDK build prompt.
Each toolchain will find a compiler, runtime and a Windows SDK.
The CMake scripts for Windows-specific build tasks that used to be in this repository can now be found in MarkSchofield/WindowsCMake.
Yes, but you're probably either:
-
using a "Visual Studio Generator". In which case, CMake will emit - and then build - a Visual Studio Solution file that knows how to find the build tools and utilities.
-
running from a Visual Studio "Command Prompt". In which case, the command prompt is hard-coded to use a set of tools and utilities, which means that you always need to initialize your command prompt before getting started.
By using a Toolchain file to describe the tools and utilities to build in CMake-terms, you can use other generators (e.g. Ninja) and don't have to initialize an environment to run a build.
No, no. This uses the tools and utilities from installed Visual Studio but from a CMake build.
No. This is an early attempt at making Visual Studio tooling easier to use from CMake. There's definitely gaps - there's no support for "Windows Universal" builds, for example. But it gets enough of a stake-in-the-ground to start a conversation.
Simply specify one of the toolchain files to your CMake builds. See the documentation for CMake toolchains for more details on Toolchain files and how to consume them.
Each toolchain file ('Windows.MSVC.toolchain.cmake', 'Windows.Clang.toolchain.cmake', or Windows.EWDK.toolchain.cmake) has details on the various CMake properties that can be used to configure the build. And the example folder provides a CMake project that builds a variety of Windows projects, using each of the toolchain files.
VCPkg - https://github.com/microsoft/vcpkg - is a Package Manager for C++. When using WindowsToolchain with VCPkg:
-
The
vcpkg.cmake
script must be specified as the toolchain for CMake builds - as per the VCPkg documentation. -
The path to the WindowsToolchain file -
Windows.MSVC.toolchain.cmake
- should be specified as theVCPKG_CHAINLOAD_TOOLCHAIN_FILE
. The VCPkg toolchain will load the specifiedVCPKG_CHAINLOAD_TOOLCHAIN_FILE
.
Note:
-
VCPkg has default functionality to copy runtime dependencies from VCPkg-based packages during a CMake build. The functionality - implemented in
applocal.ps1
- requires thatdumpbin
,llvm-objdump
orobjdump
be found by PowerShell'sGet-Command
. On Windows,applocal.ps1
is typically executed so that it would finddumpbin
through thePATH
environment variable, but since WindowsToolchain doesn't configure thePATH
environment variableapplocal.ps1
fails.To disable this behavior,
VCPKG_APPLOCAL_DEPS
toOFF
in yourCMakePresets.json
, on the CMake configuration command-line, or before the top-levelproject()
call. If dependencies need to be copied during a build, use custom commands to copy them. For example, the following CMake snippet will copy dependencies for a target calledCommandLine
, for dependencies that support the$<TARGET_RUNTIME_DLLS:tgt>
generator expression:if(WIN32) add_custom_command(TARGET CommandLine POST_BUILD COMMAND "${CMAKE_COMMAND};-E;$<IF:$<BOOL:$<TARGET_RUNTIME_DLLS:CommandLine>>,copy;$<TARGET_RUNTIME_DLLS:CommandLine>;$<TARGET_FILE_DIR:CommandLine>,true>" COMMAND_EXPAND_LISTS ) endif()
Note: The
$<TARGET_RUNTIME_DLLS:tgt>
generator expression requires CMake 3.21 or higher.
WindowsToolchain uses cmakelang
for linting the CMake files in the codebase. The
.cmake-format.yaml file describes the formatting style for the codebase. To run the linting
tools:
-
Install
cmakelang
following the installation instuctions. Note: Since WindowsToolchain uses a.yaml
file for configuration, make sure to install thecmakelang[YAML]
package. -
Run
./analyze.ps1
The Toolchain CI GitHub Workflow enforces the linting rules during PR and CI.