Manifest mode
vcpkg has two modes for consuming packages - Classic mode and Manifest mode. For most users, we recommend Manifest mode.
In Manifest mode, vcpkg creates separate installed trees for each project and configuration. This allows separate projects to use different versions of libraries. The vcpkg.json file and optional vcpkg-configuration.json file form a project's manifest. The manifest declares the project's direct dependencies, version constraints, and registries used.
Check out the manifest CMake example for an example project using CMake and manifest mode.
Check out the vcpkg.json Syntax Reference for a full list of fields and functionality.
Example
{
"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
"name": "my-application",
"version": "0.15.2",
"dependencies": [
"boost-system",
"libxml2",
"yajl"
]
}
Features
Manifests can define additive sets of functionality, behavior, and dependencies called features.
Each feature should be additive with other features: if a project provides features A and B, then it should build successfully with both A and B enabled together. Features should not be used to define alternatives. For example, features cannot be used to choose between multiple, exclusive graphics APIs since it is not possible to choose both. Features can depend on other features within same project if the project's manifest has a "name".
The set of features available are defined by the "features" field.
Example 1: Multiple File Formats
For example, an image manipulation library might optionally support several different image types by depending on different sets of other libraries.
{
"name": "my-image-lib",
"version": "0.1",
"features": {
"png": { "description": "Support PNG files", "dependencies": ["libpng"]},
"jpeg": { "description": "Support JPEG files", "dependencies": ["libjpeg-turbo"]},
"tiff": { "description": "Support TIFF files", "dependencies": ["libtiff"]},
}
}
In a single dependency graph, multiple libraries can depend on features from a common core library.
{
"name": "library-a",
"version": "1",
"dependencies": [{"name": "my-image-lib", "features": ["png"]}]
}
{
"name": "library-b",
"version": "1",
"dependencies": [{"name": "my-image-lib", "features": ["jpeg"]}]
}
When resolving these dependencies, all required features and dependencies will be unioned together. In this example, if a top-level project used library-a and library-b, they would see an install plan similar to:
libjpeg-turbo[core]
libpng[core]
library-a[core]
library-b[core]
my-image-lib[core,png,jpeg]
The build of my-image-lib would activate PNG and JPEG support but deactivate TIFF support.
Example 2: Multiple Related Projects in a Single Repository
When a single repository contains several separate buildable components, for example client and server applications with some shared code, developers of each piece may want to avoid installing expensive dependencies required by other pieces.
{
"name": "my-game",
"dependencies": ["grpc"],
"features": {
"client": { "description": "Client Game Executable", "dependencies": ["sdl2", "bullet3"]},
"server": { "description": "Multiplayer Server Executable", "dependencies": ["proxygen"]},
"tests": { "description": "Build tests", "dependencies": ["gtest"] }
}
}
Individual developers can then select which features to install:
- On the install command line, pass
--x-feature= - When using CMake Integration, set
VCPKG_MANIFEST_FEATURESbefore theproject()command. - When using MSBuild Integration, pass
--x-feature=viaVcpkgAdditionalInstallOptions
Default Features
Default features are a set of features to be automatically activated if the top-level project does not explicitly request a build without them. Default features are intended to ensure a minimum level of functionality regardless of how complex and customizable the dependency graph of a project grows. They are not intended to model "curation" or "suggestions".
For example, consider a library "extract-any" that supports over 10 different archive formats, including several that are quite obscure. Because they are all optional, if none are selected the library is not functional: it cannot extract any files.
Default features ensure that a user who simply adds "extract-any" to the list of dependencies in their vcpkg.json:
{
"name": "my-application",
"version": "0.15.2",
"dependencies": [
"extract-any"
]
}
will get a baseline level of functionality, for example automatically selecting .zip and .tar.gz decompressors.
If the user wants to explicitly disable the default features, they can do so by adding "default-features": false to the dependency:
{
"name": "my-application",
"version": "0.15.2",
"dependencies": [
{
"name": "extract-any",
"default-features": false
}
]
}
Feedback
Submit and view feedback for