What is manifest mode?

Artikel
07/22/2024

vcpkg has two operation modes: classic mode and manifest mode. For most users, we recommend manifest mode.

Manifest mode uses declarative JSON files to describe metadata about your project or package. Manifest files are required to have the vcpkg.json name.

Manifest mode is engaged by running the vcpkg install command while there's a manifest file (vcpkg.json) in the working directory. Read ahead for details on how to install packages in manifest mode.

Manifest mode is also required to use advanced features like versioning and custom registries.

Manifest files in ports

All vcpkg ports must include a vcpkg.json file that describes metadata about the package they install.

vcpkg uses the metadata in the package manifest for various purposes, such as, calculating dependency trees, searching for packages by name or description, resolving features, etc.

Package manifest example

{
  "name": "fmt",
  "version": "10.1.1",
  "description": "Formatting library for C++. It can be used as a safe alternative to printf or as a fast alternative to IOStreams.",
  "homepage": "https://github.com/fmtlib/fmt",
  "license": "MIT",
  "dependencies": [
    {
      "name": "vcpkg-cmake",
      "host": true
    },
    {
      "name": "vcpkg-cmake-config",
      "host": true
    }
  ]
}

Manifest files in projects

The main purpose of using a manifest file in your project is to declare your dependencies. When using a project manifest, you're able to specify version constraints and overrides to lock specific versions of your dependencies. This feature is not available in classic mode.

Project manifest example

{
  "dependencies": [ "fmt", "zlib" ],
  "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
  "overrides": [
    { "name": "zlib", "version": "1.2.8" }
  ]
}

Configuration file

vcpkg can be configured through a vcpkg-configuration.json file to add more package registries or overlay ports and triplets locations.

Configuration file example

{
  "default-registry": {
    "kind": "git",
    "baseline": "7476f0d4e77d3333fbb249657df8251c28c4faae",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/microsoft/vcpkg-docs",
      "reference": "vcpkg-registry",
      "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
      "packages": [ "beicode", "beison" ]
    }
  ],
  "overlay-ports": [
    "C:\\dev\\my_vcpkg_ports"
  ]
}

Installing packages in manifest mode

To install packages using a manifest file you use the vcpkg install command without any package arguments. The command must be executed from a directory containing a manifest (vcpkg.json) file, or the path to a manifest file provided by using the --x-manifest-root=<path> option.

Packages installed in manifest mode will not be installed in the global installed directory as they do in classic mode. Instead, each manifest gets its own installation directory named vcpkg_installed; the vcpkg_installed directory is created in the same directory that contains the manifest file.

Having independent installation trees per manifest allows separation of dependencies between different projects. This circumvents a crucial limitation of classic mode, which only allows one version of each port to be installed. Manifest mode keeps versions of ports separated per project.

Using features in project manifests

Manifest files can define additive sets of functionality, behavior, and dependencies through the use of "features".

In your projects, you may define features to enable or disable dependencies that apply to parts of your project. For example, if your project contains multiple components, you may want to keep common dependencies in the "dependencies" list but limit some others to their respective components.

To enable features of your project you can use one of the following methods:

Pass the --x-feature option to your vpckg install command.
On CMake, set the VCPKG_MANIFEST_FEATURES before the first call to project().
On MSBuild, pass the --x-feature option via `VcpkgAdditionalInstallOptions.

Example: Features in project manifests

{
  "name": "my-game",
  "dependencies": [ "grpc" ],
  "features": {
    "client": {
      "description": "client game executable",
      "dependencies": [ "sdl2", "bullet3" ]
    },
    "server": {
      "description": "multiplayer server executable",
      "dependencies": [ "proxygen" ]
    },
    "tests": {
      "description": "development tests",
      "dependencies": [ "gtest" ]
    }
  }
}

To build only the "client" component's dependencies run:

vcpkg install --x-feature=client

Next steps

Here are some tasks to try next:

Complete the manifest mode tutorial
Read the vcpkg.json and vcpkg-configuration.json reference articles.
Lock down your versions for repeatable builds using versioning

Delen via