skip to content

CMake and Binary Caching

Pointing CMAKE_TOOLCHAIN_FILE at vcpkg.cmake installs manifest dependencies during configure, and binary caching reuses builds in CI. Interviewers ask how vcpkg fits a CMake project.

on this pageshow

explore

questions

4

How do you make a CMake project consume vcpkg dependencies, and what does pointing CMAKE_TOOLCHAIN_FILE at vcpkg.cmake do during configure?

level: juniorimportance: must knowfreq 55%

answer

  1. scripts/buildsystems/vcpkg.cmake
  2. set before the first project()
  3. manifest install during configure
  4. prefix path for find_package

basics

~10 s

Set CMAKE_TOOLCHAIN_FILE to <vcpkg root>/scripts/buildsystems/vcpkg.cmake on the first configure. During project() it runs vcpkg install for the vcpkg.json, then adds the installed tree to CMake's search paths so find_package finds the libraries.

solid answer

~40 s

vcpkg integrates with CMake through a toolchain file. You pass `-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake` when the build tree is first configured, or put it in a configure preset as `$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake`. CMake evaluates the toolchain inside the first `project()` call, so it and every `VCPKG_*` setting must be in place before then. In manifest mode, meaning a `vcpkg.json` beside the top-level `CMakeLists.txt`, the script runs `vcpkg install` with the chosen triplet into `${CMAKE_BINARY_DIR}/vcpkg_installed`, bootstrapping the vcpkg executable if needed and logging to `vcpkg-manifest-install.log`. It then prepends that triplet's tree to `CMAKE_PREFIX_PATH` and `CMAKE_FIND_ROOT_PATH` (and its `lib/manual-link` folder to `CMAKE_LIBRARY_PATH`), so ordinary `find_package(fmt CONFIG REQUIRED)` and `target_link_libraries` work; vcpkg adds no include or link paths on its own. Editing `vcpkg.json` re-runs configure. To combine with another toolchain, set `VCPKG_CHAINLOAD_TOOLCHAIN_FILE`.

code

console · 5 lines
console
$ cmake -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
-- Running vcpkg install
...
-- Running vcpkg install - done
$ cmake --build build

go deeper

for a junior

Recall the path of vcpkg.cmake, that it goes in CMAKE_TOOLCHAIN_FILE before the first project(), and that find_package then finds vcpkg libraries.

for a middle

Explain what the toolchain does during configure: manifest install into the build tree, configure dependencies on vcpkg.json, and prepending the installed triplet to the search paths.

for a senior

Show the failure modes you have debugged: toolchain set too late or on an old cache, install failures read from vcpkg-manifest-install.log, and chain-loading a cross toolchain.

for a principal

Standardise how every repository wires vcpkg, ideally through shared presets, so developer machines and CI configure the same way.

## The toolchain file is the integration CMake lets a project customise toolchain detection with a **toolchain file**, a CMake script named by the `CMAKE_TOOLCHAIN_FILE` variable and read early, during the first `project()` call. vcpkg ships one at `scripts/buildsystems/vcpkg.cmake` and uses that hook to wire itself in. Two consequences follow from how CMake treats the variable: - it must be set **before the first `project()`**: on the command line, in a preset's `cacheVariables`, or with `set()` above `project()`; - it is honoured when the build tree is **first created**; later it persists in the cache, so switching toolchains means a fresh build directory. The vcpkg docs recommend presets, with the root taken from an environment variable: ```json { "version": 3, "configurePresets": [ { "name": "debug", "cacheVariables": { "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake" } } ] } ``` ## What vcpkg.cmake does during configure In order, for a manifest-mode project: 1. **Finds the vcpkg root** by walking up from its own location until it finds the `.vcpkg-root` marker file. The `VCPKG_ROOT` environment variable matters for locating the script (as in the preset above) and for the command-line tool, not for this step. 2. **Detects manifest mode**: `VCPKG_MANIFEST_MODE` turns on when `${CMAKE_SOURCE_DIR}/vcpkg.json` exists or `VCPKG_MANIFEST_DIR` is set. 3. **Chooses the triplet** from `VCPKG_TARGET_TRIPLET` or the compiler settings, and the install directory, `${CMAKE_BINARY_DIR}/vcpkg_installed` by default in manifest mode. 4. **Bootstraps** the vcpkg executable if it is missing, then runs `vcpkg install --triplet <t> --x-manifest-root=<dir> --x-install-root=<dir>` plus features, overlays and extra options, while `VCPKG_MANIFEST_INSTALL` is on (its default in manifest mode). 5. **Writes** the tool's output to `vcpkg-manifest-install.log` in the build directory and fails the configure if the install fails. 6. **Registers** `vcpkg.json` and `vcpkg-configuration.json` as configure dependencies, so editing either re-runs CMake. 7. **Prepends** `<installed>/<triplet>` and its `debug` twin to `CMAKE_PREFIX_PATH` and `CMAKE_FIND_ROOT_PATH`, and their `lib/manual-link` folders to `CMAKE_LIBRARY_PATH`; the order puts these paths ahead of system locations unless the deprecated `VCPKG_PREFER_SYSTEM_LIBS` is on. ## Consuming the libraries After that, the project uses CMake's normal discovery: ```cmake find_package(fmt CONFIG REQUIRED) target_link_libraries(app PRIVATE fmt::fmt) ``` vcpkg prints the usage lines for each installed package. It **does not** add include directories or libraries to targets by itself; header-only libraries without a CMake package are found with `find_path`. How `find_package` locates config files is a CMake topic of its own. ## Combining with another toolchain A cross-compiling or custom-compiler toolchain still works: - set `VCPKG_CHAINLOAD_TOOLCHAIN_FILE` to your toolchain and keep `CMAKE_TOOLCHAIN_FILE` on vcpkg.cmake; or - `include()` vcpkg.cmake at the end of your own toolchain file. Either way, your toolchain's compiler and flags apply to **your** targets; the libraries vcpkg builds follow the triplet, so settings that must reach them belong in a custom triplet. ## Other build systems | Build system | How vcpkg plugs in | |---|---| | CMake | `CMAKE_TOOLCHAIN_FILE` pointing at vcpkg.cmake | | MSBuild, user-wide | `vcpkg integrate install` once per user | | MSBuild, per repository | import `vcpkg.props` and `vcpkg.targets`, often via `Directory.Build.props` and `Directory.Build.targets` | With MSBuild, manifest mode is off until `VcpkgEnableManifest` is `true`; the property still defaults to `false`. ## Diagnosing a failed configure When `Running vcpkg install - failed` appears, CMake stops with a pointer to the log. A short routine finds most causes: 1. Read `vcpkg-manifest-install.log` in the build directory; it holds the full tool output, including which port failed and the path of that port's own build logs under `buildtrees`. 2. Re-run the same install from a shell with the same triplet and the manifest directory to iterate faster than a full CMake configure. 3. If the install succeeded but `find_package` still fails, set `VCPKG_TRACE_FIND_PACKAGE` to `ON` before `project()`; vcpkg.cmake then prints every `find_package` call, nested ones indented, which shows whether the package was even searched. 4. Check that the package printed usage lines for the name you are searching; config-package names and target names often differ from the port name. ## Common mistakes - Setting the toolchain after `project()`, or on a second configure of an existing build tree. - Expecting `vcpkg_installed` beside `vcpkg.json` when building through CMake; the integration installs into the build directory instead. - Linking libraries by path instead of the imported targets the package provides.

  • Why does adding CMAKE_TOOLCHAIN_FILE to an existing build directory not enable vcpkg?
    CMake reads the toolchain file only when a build tree is first created; afterwards the value lives in the cache and toolchain detection has already happened. Configure a fresh build directory, or delete the cache, with the toolchain set from the start.
  • How do you enable vcpkg manifest mode in an MSBuild project?
    Integrate first, either user-wide with `vcpkg integrate install` or by importing `vcpkg.props` and `vcpkg.targets`, then set `VcpkgEnableManifest` to `true`, since it currently defaults to `false`. vcpkg then installs the manifest's dependencies during the build into `vcpkg_installed` beside the `vcpkg.json`.
  • Where does vcpkg.cmake install packages in manifest mode?
    Into `${CMAKE_BINARY_DIR}/vcpkg_installed/<triplet>` by default, unlike the command line, which creates `vcpkg_installed` beside `vcpkg.json`. Set `VCPKG_INSTALLED_DIR` before `project()` to share one installed tree between several build directories.

  • vcpkg.cmake can be included anywhere in CMakeLists.txt, even after project().
  • vcpkg automatically adds every installed library's include path and link line to all targets.
  • vcpkg.cmake locates vcpkg only through the VCPKG_ROOT environment variable.
  • You must run vcpkg install by hand before every CMake configure in manifest mode.
  • Using vcpkg's toolchain means you can no longer cross-compile with your own toolchain file.
open as a page

In a CMake build using vcpkg.cmake, how is VCPKG_TARGET_TRIPLET chosen, and why must it and the other VCPKG_ settings be fixed before project()?

level: middleimportance: should knowfreq 35%

basics

~20 s

vcpkg.cmake uses VCPKG_TARGET_TRIPLET if set; otherwise it builds a name like x64-windows or arm64-osx from the generator platform, processor and system. It reads every VCPKG_ setting inside the first project(), so they must be set earlier, and a changed triplet needs a fresh cache.

open as a page

A GitHub-hosted CI pipeline rebuilds every vcpkg dependency on every run; why does that happen, and how do you configure vcpkg binary caching to stop it?

level: seniorimportance: should knowfreq 40%

basics

~20 s

vcpkg's default binary cache is a local folder, such as ~/.cache/vcpkg/archives, and hosted runners start empty, so every package is built from source. Set VCPKG_BINARY_SOURCES to durable storage, such as clear;nuget,<feed>,readwrite, so packages are restored by ABI hash.

open as a page

How would you set up vcpkg binary caching for a team, deciding where the cache lives, who may write to it, and how to keep hit rates high?

level: principalimportance: should knowfreq 25%

basics

~20 s

Give trusted CI builds of protected branches readwrite access and everyone else, including pull-request builds and developers, read access. Choose stable storage the team can authenticate to, and pin compilers, images and baselines, because they decide the ABI hash and so the hit rate.

open as a page