skip to content

Manifest Mode

A vcpkg.json lists a project's dependencies and features, and a builtin-baseline commit pins every version. Interviewers ask how versions are chosen and overridden.

on this pageshow

explore

questions

4

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%

answer

  1. per-project versus one shared tree
  2. a JSON file beside the sources
  3. vcpkg install with no package names
  4. vcpkg_installed next to the manifest

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.

solid answer

~40 s

vcpkg has two operation modes. In **classic mode** you run `vcpkg install zlib fmt` and the packages land in the `installed` tree inside that vcpkg instance, shared by every project that uses it, with one version of each port per triplet, much like a system package manager. In **manifest mode**, which the vcpkg docs recommend, the project carries a `vcpkg.json` file; running `vcpkg install` with no package arguments in that directory installs exactly what the manifest lists into a `vcpkg_installed` directory owned by the project. A project's `vcpkg.json` holds a `dependencies` array (port names, or objects adding `features`, `default-features`, `platform`, `host` and `version>=`), optional `features` of its own, a `builtin-baseline` and `overrides`. Versioning (`builtin-baseline`, `version>=` and `overrides`) works only in manifest mode, which is why a shared, pinned manifest is the normal setup.

code

json · 10 lines
json
{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "fmt",
    "zlib",
    { "name": "spdlog", "default-features": false },
    { "name": "openssl", "platform": "!windows" }
  ],
  "builtin-baseline": "9eec002df1cd109f8f104cd966a763daf9751489"
}

go deeper

for a junior

Recall the two modes, that manifest mode is the recommended one, and that vcpkg.json lists the project's dependencies. Say where packages end up in each mode.

for a middle

Explain why a per-project vcpkg_installed tree matters: two projects on one machine can use different versions, and the committed manifest makes every clone install the same list.

for a senior

Show you have moved a team off a shared classic-mode tree: dependencies listed in vcpkg.json, a baseline added, and build agents no longer relying on whatever happened to be installed before.

for a principal

Treat the manifest as the team's contract for third-party code: it is reviewed like source, and a library that is not in it does not exist for the build.

## Two ways to run vcpkg vcpkg is a source-based package manager for C and C++ libraries: each **port** is a recipe that downloads a library's sources and builds them for a **triplet** (an architecture, OS and linkage combination). vcpkg can drive those builds in two **operation modes**, and the difference decides where the packages go and who decides which ones exist. ## Classic mode: one shared installed tree In **classic mode** you name packages on the command line, as in `vcpkg install zlib fmt`, and remove them with `vcpkg remove`. The results accumulate in the `installed` directory at the root of that vcpkg instance. Every project that points at the instance sees the same set, much like `apt` or `brew`, and the instance can hold only one version of each port per triplet. Two projects that need different versions of the same library therefore cannot share one classic-mode instance. Classic mode also ignores versioning: there is no way to say "this project needs fmt at least 10.1". ## Manifest mode: the project declares what it needs In **manifest mode** the project carries a file that must be named `vcpkg.json`. vcpkg engages manifest mode when you run `vcpkg install` **without package arguments** in a directory containing that file (or point at it with `--x-manifest-root=<path>`). It then reads the manifest, resolves the full dependency graph from each port's own manifest, and installs the result into a `vcpkg_installed` directory created beside the `vcpkg.json`. The CMake integration runs the same install during configure and places that directory in the build tree instead; that wiring is covered with the CMake integration. Because each manifest gets its own installed tree, two projects on the same machine can use different versions of a port, and the manifest itself lives in source control next to the code. ## What a project's vcpkg.json can declare Manifests are strict JSON: no `//` comments and no trailing commas. A field whose name starts with `$` can carry a comment inside objects with a fixed set of keys. | Field | Purpose | |---|---| | `dependencies` | ports the project needs, as names or objects | | `features` | optional parts of the project, each with its own dependencies | | `default-features` | features enabled unless a consumer opts out | | `builtin-baseline` | registry commit whose versions act as the floor | | `overrides` | exact version pins, honoured only at the top level | | `name`, `version` | required for a library port, optional for an application | A dependency object can add: - `features`: extra features of that port to build; - `default-features`: `false` to drop the port's on-by-default features; - `platform`: a platform expression such as `"!windows"`, so the dependency applies only on matching triplets; - `host`: `true` when the dependency is a build tool that must run on the build machine; - `version>=`: a minimum version, which needs a baseline to be accepted. A manifest-mode project can also carry a `vcpkg-configuration.json` beside `vcpkg.json` (or embed the same content in a `configuration` field) to add registries and overlay locations. ## Moving an existing project from classic to manifest mode A team that has been running `vcpkg install` by hand on every build agent usually migrates in a few steps: 1. Run `vcpkg new --application` or write the file by hand, then list every library the code links against in `dependencies`. Only direct dependencies belong there; vcpkg finds the rest. 2. Add a `builtin-baseline` (for example with `vcpkg x-update-baseline --add-initial-baseline`) so every machine resolves the same versions. 3. Express needed options as features of the dependencies instead of relying on whatever features someone happened to install into the shared tree. 4. Stop relying on the agents' shared `installed` directory: let the build run the manifest install, or run `vcpkg install` in the project directory as a build step. 5. Use `vcpkg install --dry-run` to print the install plan and review it before the first real build. The result is that the dependency list, its versions and its features change only through a reviewed commit. ## Why teams default to manifest mode 1. **Reproducibility**: the dependency list is versioned with the code, so a fresh clone installs the same set. 2. **Isolation**: per-project installed trees end the "whatever is on the build agent" problem of a shared classic tree. 3. **Version control of versions**: `builtin-baseline`, `version>=` and `overrides` exist only in manifest mode. 4. **Build-system integration**: the CMake toolchain and MSBuild integration can run the install automatically. Classic mode is still handy for a quick experiment or for installing a tool globally, but for a desktop application whose every developer and CI agent must build against the same libraries, the manifest is the contract.

  • Does a top-level application's vcpkg.json need name and version fields?
    No. `name`, a version field and `description` are required for library ports, because the registry and search use them, but they are optional for a top-level project. An application's manifest can be nothing more than a `dependencies` array plus a `builtin-baseline`.
  • How do you put a comment in a vcpkg.json?
    Manifests are strict JSON, so `//` comments and trailing commas are rejected. Use a field whose name starts with `$`, such as `"$comment"` or `"$explanation"`, inside an object with a fixed set of keys. It is not allowed inside maps with user-defined keys, such as the `features` map.
  • Can classic mode use version>= constraints?
    No. Versioning, meaning `builtin-baseline`, `version>=` and `overrides`, is available only in manifest mode. Classic mode installs whatever version the ports in the vcpkg instance's own checkout describe, one version per port per triplet.

  • vcpkg.json only matters to people publishing a library to the vcpkg registry.
  • Manifest mode still installs into the shared installed folder of the vcpkg instance.
  • Manifest-mode vcpkg install needs the package names repeated on the command line.
  • Classic mode supports builtin-baseline and version>= just like manifest mode.
  • A project's vcpkg.json must list every transitive dependency by hand.
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 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

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