How do you make a CMake project consume vcpkg dependencies, and what does pointing CMAKE_TOOLCHAIN_FILE at vcpkg.cmake do during configure?
answer
- scripts/buildsystems/vcpkg.cmake
- set before the first project()
- manifest install during configure
- prefix path for find_package
basics
~10 sSet 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 svcpkg 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$ cmake -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
-- Running vcpkg install
...
-- Running vcpkg install - done
$ cmake --build buildgo deeper
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.
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.
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.
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.