Manifest mode¶

vcpkg manifest mode is the recommended way of consuming packages with vcpkg.

It allows reproducible per-project build environments using JSON files.

vcpkg manifest mode also enables the use of vcpkg registries, which are groups of custom vcpkg ports with finer versioning.

Project structure¶

myproject/
├── include/                    ← Example header files
├── src/                        ← Example source files
├── ...
├── CMakeLists.txt              ← Example CMakeLists
├── CMakePresets.json           ← Example CMake presets file
├── README.md                   ← Example README
├── vcpkg-configuration.json    ← vcpkg registry configuration
├── vcpkg.json                  ← vcpkg manifest configuration

The above structure presents an example of a project using vcpkg manifest mode. At the root are the two following JSON files.

vcpkg-configuration.json: describing the base curated registry to use, as well as custom registries, such as the Rat-vcpkg repository.
vcpkg.json: describing the project at hand and the packages to use.
CMakePresets.json: optional file describing the arguments to pass to CMake configuration for lighter terminal commands.

An example of the files can be found under the rat-vcpkg/examples/manifest-mode subdirectory within the Rat-vcpkg repository on GitLab.

Manifest file¶

vcpkg.json simply defines project metadata and following this structure:

vcpkg manifest file¶

{
    "name": "project-name",
    "version": "1.0.0",
    "dependencies": [
        "my-dependency-1",
        "my-dependency-2"
    ]
}

Configuration file¶

vcpkg-configuration.json defines registries to use along with their baselines defined as Git commit hashes and the ports to use:

vcpkg configuration file¶

{
    "default-registry": {
        "kind": "git",
        "baseline": "<commit hash of vcpkg to use>",
        "repository": "https://github.com/microsoft/vcpkg"
    },
    "registries": [
        {
            "kind": "git",
            "repository": "https://path/to/git/registry",
            "baseline": "<commit hash of registry to use>",
            "packages": [
                "my-registry-dependency-1",
                "my-registry-dependency-2"
            ]
        }
    ]
}

This configuration defines a version for the vcpkg default registry to use as well as an additional Git registry entry to access more dependencies for the project.

The configuration file can also be used to point to local registry to override specific ports like in rat-vcpkg/examples/manifest-mode:

vcpkg configuration file using overlay¶

{
    "overlay-ports": [
        "../../ports"
    ]
}

This is usefull for quick iterations and testing.

Note

To obtain a correct "baseline" value to use, one can leave a blank string. vcpkg will print out and error containing the most recent commit hash. Just copy it as the value for the registry baseline. Alternatively one can paste the output of the git rev-parse HEAD command in the repository of interest. Baselines should point to valid commit hash.
The path to the external registry can also be a file path to a local git repository:

{
    "kind": "git",
    "repository": "file:///C:/path/to/project-rat-extras/rat-vcpkg",
}

Warning

vcpkg seems pretty dumb when it comes to commit SHA (which is funny considering it is the base of registries…) and will not really use the provided commit SHA completely.

For instance, commits to a dev branch would be recognize, but versions and baseline will still be resolved using the main branch… One might need to have a more impactful commit such as a tag or push a new branch in order to have vcpkg property recognize the given commit SHA.

CMake presets file¶

CMakePresets.json defines CMake presets to use during project configuration, allowing for leaner and more concise terminal command

CMake preset file¶

{
  "version": 3,
  "configurePresets": [
    {
      "name": "main",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
        "CMAKE_BUILD_TYPE": "Release",
        "VCPKG_TARGET_TRIPLET": "x64-windows-release",
        "VCPKG_HOST_TRIPLET": "x64-windows-release"
      }
    }
  ]
}

Providing the VCPKG_ROOT environment variable, this allow to configure project with the simple following command:

cmake -B build -S . --preset main

Consume packages¶

vcpkg will recognize the two JSON files described above whenever running an install, configure or build command, either directly via vcpkg, or via CMake.

vcpkg first needs to build and install the project dependencies defined in the manifest and configuration files and will do so under a vcpkg_installed directory, either next to the JSON files or under a build directory if invoked via CMake.

Note

Depencies might take some time to build depending on the hardware.

The heaviest one for Rat seems to be VTK, which is even longer to build in Debug.

Local manifest installation¶

Run the following command to first build and install vcpkg dependencies for the local project following the manifest:

vcpkg install --triplet x64-windows-release --host-triplet x64-windows-release

It will trigger vcpkg to build dependencies inside a vcpkg_installed directory using the x64-windows-release triplet for faster and leaner builds. See vcpkg triplets.

This will serve as the dependency installation directory for the project and vcpkg will know to use it when instructed to configure projects with CMake pointing to its toolchain.

CMake configuration installation¶

Ensure the VCPKG_ROOT environment variable is defined and points to the local vcpkg repository installation.
Configure the CMake project using the vcpkg toolchain file:

cmake -B build -S . -G "Ninja" `
    -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" `
    -DCMAKE_BUILD_TYPE=Release `
    -DVCPKG_TARGET_TRIPLET=x64-windows-release `
    -DVCPKG_HOST_TRIPLET=x64-windows-release

or using the CMakePresets.json file above:

cmake -B build -S . -G "Ninja" --preset main

This will first trigger vcpkg to build dependencies just like the above local manifest installation before running the CMake configuration for the project.

Build the project:

cmake --build build

Warning

VTK ports recently changed to introduce a vtk-compile-tools port which is host specific and might break CMake configuration.

To fix this, ensure the vtk-compile-tools package is installed in global vcpkg using classic mode by running the following command from outside the current manifest project:

vcpkg install vtk-compile-tools