CMakePresets and vcpkg on a Real C++20 Modules Project
The modules guide builds a C++20 module with CMake. The moment that project grows a dependency, four decisions land at once: where the vcpkg path lives, manifest or classic mode, how a second toolchain file fits in, and how presets inherit without duplicating the toolchain setting.
Written November 6, 2026 · Tested with CMake 3.28.3 · 13 min read
- Decision 1: where VCPKGROOT lives
- Decision 2: manifest or classic mode
- Decision 3: chainload a second toolchain, or include the vcpkg toolchain
- Decision 4: one base preset for debug, release, and CI
What you will build
The same small math module from the modules guide — add and sub in a named module — plus a fmt dependency pulled in through vcpkg, all driven by presets. The four decisions are made on this one project so each answer is a run you can repeat, not a claim:
| Decision | Short answer |
|---|---|
Where does VCPKG_ROOT live? |
In CMakeUserPresets.json, under its own preset name |
| Manifest or classic mode? | Manifest, unless you need the shared install — and check for a stray vcpkg.json first |
| Second toolchain file? | Chainload it with VCPKG_CHAINLOAD_TOOLCHAIN_FILE |
| Presets for debug, release, and CI? | One hidden base preset; the toolchain is set once |
Tested with CMake 3.28.3 and Ninja 1.13.2 on Ubuntu 24.04, vcpkg version 2026-10-29-139f2e53, GCC 13.3.0 for the classic and manifest legs and GCC 16.2.0 for the compiler-specific legs. MSVC was not available for this guide.
Decision 1: where VCPKG_ROOT lives
Microsoft's documentation recommends presets for the toolchain file, with the vcpkg root coming from the VCPKG_ROOT environment variable:
{
"version": 3,
"configurePresets": [
{
"name": "debug",
"cacheVariables": {
"CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
}
}
]
}
That keeps the shared CMakePresets.json portable: it names no machine path. The machine-specific path belongs in CMakeUserPresets.json, which is ignored by Git and never committed. The subtle part is the preset name. A user preset that reuses the shared preset's name is an error, not an override. This run tried it — a user preset named vcpkg inheriting the shared preset also named vcpkg — and CMake refused to read any presets at all:
CMake Error: Could not read presets from /home/user/presets-probe-2026-11-06/work/userpreset:
Duplicate preset: "vcpkg"
The working shape gives the user preset its own name and inherits the shared one:
{
"version": 6,
"configurePresets": [
{
"name": "vcpkg-local",
"inherits": "vcpkg",
"environment": { "VCPKG_ROOT": "/home/user/vcpkg" }
}
],
"buildPresets": [
{ "name": "vcpkg-local", "configurePreset": "vcpkg-local" }
]
}
Run with VCPKG_ROOT unset in the environment, so the user preset is the only source of the path:
$ env -u VCPKG_ROOT cmake --preset vcpkg-local
$ cmake --build --preset vcpkg-local
$ ./out/build/vcpkg/probe
fmt-ok-userpreset 42
Configure, build, and run all return zero. The rule: shared presets name the mechanism ($env{VCPKG_ROOT}), user presets supply the machine path under a different name, and the two files never share a preset name.
Decision 2: manifest or classic mode
vcpkg has two modes, and the toolchain file picks one for you. In classic mode you install packages yourself (vcpkg install fmt) and the toolchain makes them available to find_package, find_library, and find_path. In manifest mode a vcpkg.json next to your CMakeLists.txt flips the mode on — the toolchain detects the manifest and runs vcpkg install itself during configure. The documentation states the default plainly: manifest mode is on when VCPKG_MANIFEST_DIR is non-empty or ${CMAKE_SOURCE_DIR}/vcpkg.json exists.
The two modes install into different places, and that is the decision that matters. Classic mode installs into the shared ${VCPKG_ROOT}/installed tree. Manifest mode installs per project, under ${CMAKE_BINARY_DIR}/vcpkg_installed. A manifest-mode project cannot see a classic-mode install, and the failure is silent about why. This run proved it by accident first: a manifest project whose vcpkg.json declared only nlohmann-json, but whose CMakeLists.txt called find_package(fmt), failed at configure with:
CMake Error at /home/user/vcpkg/scripts/buildsystems/vcpkg.cmake:957 (_find_package):
Could not find a package configuration file provided by "fmt" with any of
the following names:
fmtConfig.cmake
fmt-config.cmake
fmt was installed — in classic mode, in the shared tree, the day before. The manifest project looks only in its own vcpkg_installed directory, where fmt was never declared. Per-project installed directories are separate worlds; a package is available to a project only if that project's manifest declares it, or the project runs in classic mode against the shared tree.
Manifest mode, done correctly, is the shorter path. With this manifest:
{ "name": "manifest-probe", "version": "1.0.0", "dependencies": [ "fmt" ] }
configure restores fmt 12.2.0#1 from the binary cache in about 20 milliseconds, builds, and runs:
$ cmake --preset vcpkg
$ cmake --build --preset vcpkg
$ ./out/build/vcpkg/probe
fmt-ok-manifest 42
Classic mode, for comparison, needed the install up front — vcpkg install fmt took 6.9 seconds the first time, pulling vcpkg-cmake-config as a dependency — and then the same preset shape:
$ cmake --preset vcpkg
$ cmake --build --preset vcpkg
$ ./out/build/vcpkg/probe
fmt-ok 42
Choose manifest mode when the project owns its dependencies and you want the install to follow the source tree. Choose classic mode when several projects share one installed set and you are willing to install explicitly. Either way, declare every package the project actually uses — the mode boundary does not forgive an undeclared dependency.
The stray manifest trap
Manifest mode has one sharp edge, and it is the reason to check for a stray vcpkg.json before configuring any project. A vcpkg.json sitting in a project directory flips that project into manifest mode even when nobody intended it, and the toolchain installs everything the manifest declares — even when no target uses it. This run built a plain project whose CMakeLists.txt never mentions a JSON library, with this stray file beside it:
{ "name": "stray-probe", "version": "1.0.0", "dependencies": [ "nlohmann-json" ] }
Configure installed nlohmann-json 3.12.0#2 in 16.5 milliseconds and the build ran clean:
$ cmake --preset stray
$ ls out/build/stray/vcpkg_installed/x64-linux/
nlohmann-json
$ ./out/build/stray/probe
stray-ok
Nothing in the project uses the library; it is installed anyway, and it stays installed in the project's vcpkg_installed directory. Before configuring a project you did not set up, list the directory for a vcpkg.json you did not expect. If one is there, either honor it — add the dependency to your mental model of the project — or remove it. Do not configure past it and wonder later where the extra library came from.
Decision 3: chainload a second toolchain, or include the vcpkg toolchain
Sometimes the project already has its own toolchain file — a compiler selection, a cross-compilation setup — and vcpkg has to fit alongside it. The documentation gives two forms. The first is the VCPKG_CHAINLOAD_TOOLCHAIN_FILE cache variable: vcpkg's toolchain is the main one, and it loads yours after itself. The second is to include the vcpkg toolchain at the end of your own toolchain file. Both were executed.
The chainload variable, set in a preset:
{
"name": "chain2",
"generator": "Ninja",
"binaryDir": "out/build/chain2",
"cacheVariables": {
"CMAKE_TOOLCHAIN_FILE": "/home/user/vcpkg/scripts/buildsystems/vcpkg.cmake",
"VCPKG_CHAINLOAD_TOOLCHAIN_FILE": "${sourceDir}/my-toolchain.cmake"
}
}
with a custom toolchain that sets a marker variable:
set(CHAINLOAD_MARKER "loaded-from-my-toolchain" CACHE STRING "")
Configure prints the marker, proving the custom toolchain file was evaluated, and the build runs:
-- CHAINLOAD_MARKER=loaded-from-my-toolchain
-- Configuring done (0.2s)
$ cmake --build --preset chain2
$ ./out/build/chain2/probe
fmt-ok-chainload2 8
The preset-level form is the same idea from the other side: put the vcpkg toolchain in the preset's toolchainFile key instead of in a cache variable:
{
"name": "chain",
"generator": "Ninja",
"binaryDir": "out/build/chain",
"toolchainFile": "/home/user/vcpkg/scripts/buildsystems/vcpkg.cmake"
}
That also configures, builds, and runs clean (fmt-ok-chainload 7). Either form works; the chainload variable is the one to reach for when your own toolchain already exists and vcpkg must sit on top of it.
One limit to carry with either form: vcpkg does not apply your toolchain's compiler or flag settings to the libraries it builds. Changing how vcpkg builds its ports needs a custom triplet file, not a toolchain file. Your toolchain controls your project; the triplet controls the ports.
Decision 4: one base preset for debug, release, and CI
Presets inherit, and the inheritance is the whole answer to the fourth decision. A hidden base preset holds the generator and the output directory; debug and release inherit it and add only their build type. The toolchain file is set once, in the preset that needs it, and never repeated:
{
"version": 6,
"configurePresets": [
{
"name": "base", "hidden": true, "generator": "Ninja",
"binaryDir": "out/build/${presetName}"
},
{
"name": "debug", "inherits": "base",
"cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" }
},
{
"name": "release", "inherits": "base",
"cacheVariables": { "CMAKE_BUILD_TYPE": "Release" }
}
],
"buildPresets": [
{ "name": "debug", "configurePreset": "debug" },
{ "name": "release", "configurePreset": "release" }
]
}
Both presets configure, build, and run with the same command shape:
$ cmake --preset debug && cmake --build --preset debug
$ ./out/build/debug/probe
preset probe ok
$ cmake --preset release && cmake --build --preset release
$ ./out/build/release/probe
preset probe ok
A CI preset is a third inheritor, not a copy: it inherits base, adds the toolchain cache variable and the compiler selection, and nothing else is duplicated.
GCC 16 under a preset
The compiler selection is a cache variable, so it sits in the preset like anything else. The GCC 16 preset pins both compilers by absolute path:
{
"name": "gcc16",
"generator": "Ninja",
"binaryDir": "out/build/gcc16",
"cacheVariables": {
"CMAKE_TOOLCHAIN_FILE": "/home/user/vcpkg/scripts/buildsystems/vcpkg.cmake",
"CMAKE_C_COMPILER": "/home/user/gcc16/usr/bin/gcc-16",
"CMAKE_CXX_COMPILER": "/home/user/gcc16/usr/bin/g++-16"
}
}
Configure identifies GNU 16.2.0, builds, and runs:
$ cmake --preset gcc16
-- The CXX compiler identification is GNU 16.2.0
$ cmake --build --preset gcc16
$ ./out/build/gcc16/probe
fmt-ok-gcc16 42
The binary ran with and without the GCC 16 library path set — this program links the system libstdc++, so it needs no help. Do not generalize that: the jthread programs from the earlier C++20 guides need the path, and the requirement is per program. Test each binary both ways instead of assuming.
The binary cache does not distinguish compilers
One correction earned while running these legs: vcpkg's binary cache restored fmt 12.2.0#1 under GCC 16 in 24.5 milliseconds with an ABI hash byte-identical to the GCC 13 restore — the first eight characters are 5da22fc7, and the full 64-character hash is the same in both runs:
5da22fc7f931d7eda9a50e20b464c73b7eca131333179fa7fc877984d7ac5e8f
The GCC 16 build reused the GCC 13-built archive. For this port, at least, the cache does not distinguish compilers. Do not claim per-compiler rebuilds from a cache restore; the hash is the evidence, and here it is the same hash.
The modules project under a preset
The four decisions land on the modules project itself, not on a toy. The math module from the modules guide, plus a fmt dependency, under the GCC 16 vcpkg preset:
cmake_minimum_required(VERSION 3.28)
project(modules_vcpkg CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(fmt CONFIG REQUIRED)
add_library(math)
target_sources(math PUBLIC FILE_SET CXX_MODULES FILES math.cppm)
add_executable(app main.cpp)
target_link_libraries(app PRIVATE math fmt::fmt)
enable_testing()
add_test(NAME app-runs COMMAND app)
$ cmake --preset gcc16
$ cmake --build --preset gcc16
$ ctest --preset gcc16 --output-on-failure
1/1 Test #1: app-runs ......................... Passed 0.00 sec
100% tests passed, 0 tests failed out of 1
The CMake compiler floor from the modules guide carries over unchanged: module dependency scanning needs GCC 14 or newer, so the modules project configures under GCC 16 and fails at configure under GCC 13. The preset is where that floor lives now — the compiler cache variables, not a comment in the guide.
Diagnose from the first error
Two of the failures in this guide's history came from reading the tail of an error instead of its head. With VCPKG_ROOT unset, a preset that expands $env{VCPKG_ROOT} fails at configure with the first error Could not find toolchain file: /scripts/buildsystems/vcpkg.cmake — the empty expansion, visible at once — followed by a cascade claiming no build program corresponds to the generator and no C++ compiler is set. The toolchain file itself is fine; the compiler lookup is what failed. The same shape appears whenever the shell PATH is missing /usr/bin: configure fails with CMAKE_CXX_COMPILER not set, after EnableLanguage and the build-preset error after it is a cascade, not a second defect. Export a full PATH before probing, and read the first error line.
What breaks, and the fix
| Error | Cause | Fix |
| Duplicate preset: "vcpkg" | User preset reuses the shared preset's name | Give the user preset its own name and inherit the shared one |
| Could not find a package configuration file provided by "fmt" | Manifest project never declared fmt; classic install is invisible to it | Declare every package the project uses in its own vcpkg.json, or run classic mode |
| Could not find toolchain file: /scripts/buildsystems/vcpkg.cmake | VCPKG_ROOT unset, $env{VCPKG_ROOT} expands empty | Set VCPKG_ROOT in CMakeUserPresets.json or the environment |
| CMAKE_CXX_COMPILER not set, after EnableLanguage | Shell PATH lacks /usr/bin | Export a full PATH before configuring |
| Unexpected package in vcpkg_installed | Stray vcpkg.json flipped the project to manifest mode | Remove the stray manifest, or honor it deliberately |
Frequently asked questions
Should every project use manifest mode?
No. Manifest mode is the right default when the project owns its dependencies: the install follows the source tree, and a fresh checkout configures without a separate install step. Classic mode is the right choice when several projects share one installed set and you want a single vcpkg install to serve them all. The cost of classic mode is the install step; the cost of manifest mode is a per-project installed directory and the stray-manifest trap above.
Can I put the toolchain file in CMakeLists.txt instead of a preset?
You can, with set(CMAKE_TOOLCHAIN_FILE ...) before the first project() call — the documentation says every vcpkg-affecting variable must be set before project(). Presets are the recommended form because the path stays out of the build files, and because a preset can carry the compiler selection and the build type in the same place. A CMakeLists.txt that sets its own toolchain file is harder to reuse across machines.
Does the preset replace the command-line toolchain flag?
It replaces it for the presets that set it. The command-line form — cmake -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake — still works and is what older CMake versions need. A preset that sets the same cache variable does the same thing with less typing and fewer chances to mistype a path.
What about MSVC?
Not tested here. The CMake documentation lists MSVC support for modules, but no MSVC toolchain was available.
Where does this sit?
The modules guide, C++20 Modules with CMake 3.28 and Ninja, builds the module project this guide extends. The header-only install guide, Installing a Header-Only C++20 Modules Library with CMake, answers the follow-on packaging question. This guide answers the dependency question: how the project gets its libraries, and how the presets hold the whole setup together.
Related guides on this site
- Testing C++20 Modules: Direct Commands, Then CMake and CTest
- Installing a Header-Only C++20 Modules Library with CMake
- C++20 Modules with CMake 3.28 and Ninja
- Read a C++20 Concepts Error — "Constraints Not Satisfied", Clause by Clause
Source
- Microsoft Learn, vcpkg in CMake projects — toolchain file mechanism, manifest versus classic mode,
VCPKG_CHAINLOAD_TOOLCHAIN_FILE,CMakeUserPresets.jsonfor the machine-specific path, and the per-variable reference includingVCPKG_MANIFEST_MODEandVCPKG_INSTALLED_DIR. - CMake, cmake-cxxmodules(7) — scanning strategy, compiler and generator support, and the GCC 14+ floor for module dependency scanning that the modules project carries into its preset.
Keep Exploring
Seven tips and seven puzzles so far, each one a short runnable example with the fix explained.
Paste an AddressSanitizer, UBSan, or ThreadSanitizer report and get the bug, the file and line, and the fix \u2014 in plain language.
C++20 and C++23 features, migration paths, and measured trade-offs.
The full C++ hub \u2014 language basics, the standard library, coroutines, and measured comparisons.
Paste a [Service] section and get a plain-language verdict on every sandboxing setting it finds.