C++20

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

By the end of this guide
  • 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:

JSON
{
  "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:

Output
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:

JSON
{
  "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:

Terminal
$ 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:

Output
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:

JSON
{ "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:

Terminal
$ 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:

Terminal
$ 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:

JSON
{ "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:

Terminal
$ 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:

JSON
{
  "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:

CMake
set(CHAINLOAD_MARKER "loaded-from-my-toolchain" CACHE STRING "")

Configure prints the marker, proving the custom toolchain file was evaluated, and the build runs:

Terminal
-- 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:

JSON
{
  "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:

JSON
{
  "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:

Terminal
$ 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:

JSON
{
  "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:

Terminal
$ 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:

Output
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
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)
Terminal
$ 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.

Source

  • Microsoft Learn, vcpkg in CMake projects — toolchain file mechanism, manifest versus classic mode, VCPKG_CHAINLOAD_TOOLCHAIN_FILE, CMakeUserPresets.json for the machine-specific path, and the per-variable reference including VCPKG_MANIFEST_MODE and VCPKG_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