skip to content

vcpkg

vcpkg builds C and C++ libraries from source ports per triplet, pinned per project in manifest mode, and plugs into CMake through a toolchain file. Asked as Conan's counterpart.

on this pageshow

explore

questions

13

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 vcpkg, what is the difference between manifest mode and classic mode, and what does a project's vcpkg.json declare?

level: juniorimportance: must knowfreq 50%

basics

~20 s

Manifest mode reads the project's vcpkg.json, which lists its dependencies, features and version pins, and installs them into a per-project vcpkg_installed directory. Classic mode installs packages named on the command line into one tree shared by the whole vcpkg instance.

open as a page

In a vcpkg.json, what does the builtin-baseline field pin, and how does it give every developer and CI agent the same library versions?

level: middleimportance: must knowfreq 45%

basics

~20 s

builtin-baseline is a commit SHA of the vcpkg registry repository. vcpkg reads versions/baseline.json at that commit and uses each port's version there as its minimum, so every machine resolves the same versions whatever its local vcpkg checkout contains.

open as a page

In vcpkg, what does a triplet such as x64-windows or arm64-osx define, and which triplet is used when none is given?

level: juniorimportance: should knowfreq 45%

basics

~20 s

A triplet is a named CMake file that sets the target architecture, system and library and CRT linkage for every port built with it. Without --triplet or VCPKG_DEFAULT_TRIPLET, vcpkg targets the host triplet detected from the machine, such as arm64-osx on arm64 Macs.

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

In a vcpkg.json, how do a dependency's features and default-features settings control which optional parts of a library get built?

level: middleimportance: should knowfreq 35%

basics

~20 s

A port's features are optional parts that add build options and dependencies. A dependency entry lists extra features to build and can set default-features to false; features are additive across the graph, so defaults come back if another port asks for them.

open as a page

In vcpkg, how do VCPKG_LIBRARY_LINKAGE and VCPKG_CRT_LINKAGE differ, and which triplet ships a Windows tool without dependency DLLs or a separate MSVC runtime?

level: middleimportance: should knowfreq 40%

basics

~20 s

VCPKG_LIBRARY_LINKAGE chooses static libraries or DLLs for each port; VCPKG_CRT_LINKAGE chooses whether the MSVC runtime is linked statically (/MT) or as a DLL (/MD). x64-windows-static sets both to static, so the tool needs neither dependency DLLs nor the runtime installed.

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

With vcpkg manifests, how do builtin-baseline, version>= constraints and overrides combine under minimum version selection to pick each library's version?

level: seniorimportance: should knowfreq 35%

basics

~20 s

vcpkg selects, per port, the lowest version satisfying every minimum: the baseline's version, top-level version>= and version>= from dependencies' manifests. There are no upper bounds; a top-level override replaces all of that with one exact version.

open as a page

A library in the vcpkg registry needs a local bug fix before your release; how do you patch it with an overlay port, and what changes about its versioning?

level: seniorimportance: should knowfreq 30%

basics

~20 s

Copy the port's directory into an overlay folder in your repository, add your .patch to the PATCHES list of its source-fetching call, and register the folder in overlay-ports. The overlay then wins name resolution, and version constraints and overrides stop applying.

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

How do you write a custom vcpkg triplet, such as release-only static libraries with one port built as a DLL, and make vcpkg find it?

level: middleimportance: nice to knowfreq 25%

basics

~20 s

Copy a built-in triplet into a project directory under a new name, set VCPKG_BUILD_TYPE release and branch on the PORT variable for per-port linkage, then list that directory in overlay-triplets (or pass --overlay-triplets) and select the new triplet name.

open as a page

When should a team publish its own ports in a custom vcpkg Git registry instead of overlay ports, and what must that registry contain?

level: seniorimportance: nice to knowfreq 20%

basics

~20 s

Use a Git registry when private or patched ports must be shared, versioned and pinned across repositories. It needs ports/<name> directories and a versions database: versions/baseline.json plus versions/<letter>-/<name>.json entries holding each version's git-tree, maintained with vcpkg x-add-version.

open as a page