vcpkg.json Reference
For an overview of using manifests with vcpkg, see Manifest mode.
Manifests are strict JSON documents. They cannot contain C++-style comments (//
) nor trailing commas. However you can use field names that start with $
to write your comments in any object that has a well-defined set of keys. These comment fields are not allowed in any objects which permit user-defined keys (such as "features"
).
The latest JSON Schema is available at https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. IDEs with JSON Schema support such as Visual Studio and Visual Studio Code can use this file to provide autocomplete and syntax checking. For most IDEs, you should set "$schema"
in your vcpkg.json
to this URL.
{
"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
"dependencies": [
"boost-system",
{
"name": "cpprestsdk",
"default-features": false
},
"libxml2",
"yajl"
]
}
This example demonstrates a manifest for an application using boost-system
, cpprestsdk
, libxml2
, and yajl
. The example also includes a $schema
reference to enable better IDE validation and autocompletion.
Name | Required | Type | Description |
---|---|---|---|
builtin-baseline | No | string | Version pins to use when building as top-level |
default-features | No | Feature Object[] | Require the features listed as on-by-default |
dependencies | No | Dependency[] | List of dependencies required to build and use this project |
description | Libraries | string or string[] | The project description |
documentation | No | string | URI to the upstream project's documentation |
features | No | {string: Feature} | Optional features available for users of the project |
homepage | No | string | URI to the upstream project's homepage |
license | No | string or null | SPDX license expression |
maintainers | No | string or string[] | Maintainers of the package files |
name | Libraries | string | The project name |
overrides | No | Override[] | Version pins to use when building as top-level |
port-version | No | integer | Port files revision |
supports | No | Platform Expression | Supported platform and build configurations |
version version-semver version-date version-string |
Libraries | string | Upstream version information |
A shortcut for specifying the "baseline"
for version resolution in the default registry. A string. Optional, only used by top-level projects.
This field indicates the commit of https://github.com/microsoft/vcpkg which provides global minimum version information for your manifest. It is required for top-level manifest files using versioning without a specified "default-registry"
. It has the same semantic as defining your default registry to be:
{
"default-registry": {
"kind": "builtin",
"baseline": "<value>"
}
}
See versioning and Using registries for more semantic details.
The set of features needed for reasonable behavior without additional customization.
The default features are automatically selected if either:
- A port-to-port dependency for the port has
"default-features": true
-- the default value. - The top-level manifest does not have a dependency for the port with
"default-features": false
.
Default features handle the specific case of providing a "default" configuration for transitive dependencies that the top-level project may not know about. Ports used by others should almost always use "default-features": false
for their dependencies.
You can define platform-specific default features by using a Feature Object:
{
"name": "my-port",
"default-features": [
"png",
{
"name": "winssl",
"platform": "windows"
}
]
}
See "features"
for more information about features.
The description of the port. A string or array of strings. Required for libraries, optional for top-level projects.
This is used to help users discover the library as part of a search
or find
command and learn what the library does.
The list of dependencies required by the project. An array of Dependency objects. Optional.
This field lists all the dependencies needed to build and use your library or application.
"dependencies": [
{
"name": "arrow",
"default-features": false,
"features": [
"json",
{
"name": "mimalloc",
"platform": "windows"
}
]
},
"boost-asio",
"openssl",
{
"name": "picosha2",
"platform": "!windows"
}
]
The URI to the upstream project's documentation. A string. Optional.
The features available for users of the project. A map of names to Feature objects. Optional.
Features are boolean flags that add additional behaviors and dependencies to a build. See the Manifest Concept Documentation for more information about features.
The URI to the project's homepage. A string. Optional.
The SPDX short license expression of the project. A string or null. Optional.
The "license"
should either be an SPDX 3.19 license expression or should be null
to indicate that users must read the deployed /share/<port>/copyright
file. DocumentRefs are not supported.
Note
The licensing information provided for each package in the vcpkg registry represents Microsoft's best understanding of the licensing requirements. However, this information may not be definitive. Users are advised to verify the exact licensing requirements for each package they intend to use, as it is ultimately their responsibility to ensure compliance with the applicable licenses.
MIT
LGPL-2.1-only AND BSD-2-Clause
GPL-2.0-or-later WITH Bison-exception-2.2
vcpkg uses the following EBNF to parse the license field:
idchar = ? regex /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;
(* note that unrecognized license and license exception IDs will be warned against *)
license-id = idstring ;
license-exception-id = idstring ;
(* note that DocumentRefs are unsupported by this implementation *)
license-ref = "LicenseRef-", idstring ;
with = [ whitespace ], "WITH", [ whitespace ] ;
and = [ whitespace ], "AND", [ whitespace ] ;
or = [ whitespace ], "OR", [ whitespace ] ;
simple-expression = [ whitespace ], (
| license-id
| license-id, "+"
| license-ref
), [ whitespace ] ;
(* the following are split up from compound-expression to make precedence obvious *)
parenthesized-expression =
| simple-expression
| [ whitespace ], "(", or-expression, ")", [ whitespace ] ;
with-expression =
| parenthesized-expression
| simple-expression, with, license-exception-id, [ whitespace ] ;
(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
and-expression = with-expression, { and, with-expression } ;
or-expression = and-expression, { or, and-exression } ;
license-expression = or-expression ;
The list of package maintainers. A string or array of strings. Optional.
We recommend using the form "Givenname Surname <email>".
The name of the project. A string. Required for libraries, optional for top-level projects.
The name must be lowercase ASCII letters, digits, or hyphens (-
). It must not start nor end with a hyphen. Libraries are encouraged to include their organization or framework name as a prefix, such as msft-
or boost-
to help users find and describe associated libraries.
For example, a library with an official name of Boost.Asio
might be given the name boost-asio
.
Exact version pins to use for specific dependencies. An array of Override objects. Optional.
"overrides"
from transitive manifests (i.e. from dependencies) are ignored. Only overrides defined by the top-level project are used.
Name | Required | Type | Description |
---|---|---|---|
name | Yes | string | The port name |
version | Yes | string | Upstream version information to pin. |
version-semver version-date version-string |
Yes | string | Deprecated alternatives to version naming particular schemes. |
port-version | No | integer | Port files revision to pin. Deprecated in favor of being placed into the version itself. |
"port-version"
should be specified as a #N
suffix in "version"
. For example, "version": "1.2.3#7"
names version 1.2.3, port-version 7.
See also versioning for more semantic details.
"overrides": [
{
"name": "arrow", "version": "1.2.3#7"
},
{
"name": "openssl", "version": "1.1.1h#3"
}
]
A version suffix distinguishing revisions to the packaging files. An integer. Defaults to 0
.
The "port-version"
should be incremented whenever a new version of the port is published that does not change the upstream source version. When the upstream source version is changed, the version field should change and the "port-version"
should be reset to 0
(or removed).
See versioning for more details.
Supported platform and build configurations. A Platform Expression. Optional.
This field documents that a project is not expected to build or run successfully on certain platform configurations.
For example, if your library doesn't support building for Linux, you would use "supports": "!linux"
.
Allows to embed vcpkg configuration properties inside the vcpkg.json
file. Everything inside the vcpkg-configuration
property is treated as if it were defined in a vcpkg-configuration.json
file. For more details, see the vcpkg-configuration.json
documentation.
Having a vcpkg-configuration
defined in vcpkg.json
while also having a vcpkg-configuration.json
file is not allowed and will result in the vcpkg command terminating with an error message.
{
"name": "test",
"version": "1.0.0",
"dependencies": [ "beison", "zlib" ],
"vcpkg-configuration": {
"registries": [
{
"kind": "git",
"baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
"repository": "https://github.com/microsoft/vcpkg-docs",
"reference": "vcpkg-registry",
"packages": [ "beicode", "beison" ]
}
],
"overlay-ports": [ "./my-ports/fmt",
"./team-ports"
]
}
The version of the upstream project. A string. Required for libraries, optional for top-level projects.
A manifest must contain at most one version field. Each version field corresponds to a different versioning scheme:
"version"
- Relaxed Semantic Version 2.0.0, allowing more or less than 3 primary numbers. Example:1.2.3.4.10-alpha1
"version-semver"
- Strict Semantic Version 2.0.0. Example:2.0.1-rc5
"version-date"
- A date formatted asYYYY-MM-DD
with an optional trailing dot-separate numeric sequence. Used for packages which do not have numeric releases (for example, Live-at-HEAD). Example:2022-12-09.314562
"version-string"
- An arbitrary string. Used for packages that don't have orderable versions. This should be rarely used, however all ports created before the other version fields were introduced use this scheme.
See versioning for more details.
Each dependency is a string or an object with the following fields:
Name | Required | Type | Description |
---|---|---|---|
default-features | No | bool | Require the features listed as on-by-default |
features | No | Feature Object[] | The list of additional features to require |
host | No | bool | Require the dependency for the host machine instead of the target |
name | Yes | string | The name of the dependency |
platform | No | Platform Expression | Qualifier for which platforms to use the dependency |
version>= | No | string | Minimum required version. Port-version is identified with a #N suffix, for example, 1.2.3#7 names port-version 7. |
Strings are interpreted as an object with name defined to the string value.
Dependency: "default-features"
A boolean indicating that the project depends on the 'on-by-default' features of the dependency. Defaults to true
.
In most cases, this should be defined to false
and any needed features should be explicitly depended upon.
Dependency: "features"
The list of additional features to require. An array of Feature objects. Optional.
A Feature Object is an object with the following fields:
name
- The name of the feature. A string. Required.platform
- A Platform Expression that limits the platforms where the feature is required. Optional.
A simple string is also a valid Feature Object
equivalent to { "name": "<feature-name>" }
.
For example,
{
"name": "ffmpeg",
"default-features": false,
"features": [
"mp3lame",
{
"name": "avisynthplus",
"platform": "windows"
}
]
}
Uses the ffmpeg
library with mp3 encoding support. On Windows only, avisynthplus
support is also enabled.
Dependency: "host"
A boolean indicating that the dependency must be built for the host triplet instead of the current port's triplet. Defaults to false
.
Any dependency that provides tools or scripts which should be "executed" during a build (such as buildsystems, code generators, or helpers) should be marked as "host": true
. This enables correct cross-compilation in cases that the target is not executable -- such as when compiling for arm64-android
.
See Host dependencies for more information.
Dependency: "name"
The name of the dependency. A string. Required.
This follows the same restrictions as the "name"
property for a project.
Dependency: "platform"
An expression that limits the platforms where the dependency is required. A Platform Expression. Optional.
If the expression does not match the current configuration, the dependency will not be used. For example, if a dependency has "platform": "!windows"
, it only be required when targeting non-Windows systems.
Dependency: "version>="
A minimum version constraint on the dependency.
This field specifies the minimum version of the dependency, optionally using a
#N
suffix to also specify a minimum port-version if desired.
For more information on versioning semantics, see Versioning.
Each feature is an object with the following fields:
Name | Required | Type | Description |
---|---|---|---|
description | Yes | string | The description of the feature |
dependencies | No | Dependency[] | A list of dependencies |
supports | No | Platform Expression | Qualifier for which platforms and configurations the feature supports |
license | No | string or null | SPDX license expression |
Check out the Manifest mode documentation for a conceptual overview of features.
{
"features": {
"cbor": {
"description": "The CBOR backend",
"dependencies": [
{
"$explanation": [
"This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
],
"name": "libdb",
"default-features": false,
"features": [ "json" ]
}
]
},
"csv": {
"description": "The CSV backend",
"dependencies": [
"fast-cpp-csv-parser"
]
},
"json": {
"description": "The JSON backend",
"dependencies": [
"jsoncons"
]
}
}
}
Feature: "dependencies"
The list of dependencies required by the feature. An array of Dependency objects. Optional.
This field lists any additional dependencies needed to build and use the feature.
Feature: "description"
The description of the feature. A string or array of strings. Required.
This is used to help users discover the feature as part of a search
or find
command and learn what the feature does.
Feature: "supports"
The supported platform and build configurations for the feature. A Platform Expression. Optional.
This field documents the platform configurations where the feature will build and run successfully.
Feature: "license"
The SPDX short license expression of the feature. A string or null. Optional. If not provided, the license is the same as specified in the top level license field.
Note
The licensing information provided for each package in the vcpkg registry represents Microsoft's best understanding of the licensing requirements. However, this information may not be definitive. Users are advised to verify the exact licensing requirements for each package they intend to use, as it is ultimately their responsibility to ensure compliance with the applicable licenses.
A Platform Expression is a JSON string which describes when a dependency is required or when a library or feature is expected to build.
Expressions are built from primitive identifiers, logical operators, and grouping:
!<expr>
,not <expr>
- negation<expr>|<expr>
,<expr>,<expr>
- logical OR (the keywordor
is reserved but not valid in platform expressions)<expr>&<expr>
,<expr> and <expr>
- logical AND(<expr>)
- grouping/precedence
The following identifiers are defined based on the triplet settings and build configuration:
Identifier | Triplet Condition |
---|---|
x64 |
VCPKG_TARGET_ARCHITECTURE == "x64" |
x86 |
VCPKG_TARGET_ARCHITECTURE == "x86" |
arm |
VCPKG_TARGET_ARCHITECTURE == "arm" orVCPKG_TARGET_ARCHITECTURE == "arm64" |
arm32 |
VCPKG_TARGET_ARCHITECTURE == "arm" |
arm64 |
VCPKG_TARGET_ARCHITECTURE == "arm64" |
arm64ec |
VCPKG_TARGET_ARCHITECTURE == "arm64ec" |
wasm32 |
VCPKG_TARGET_ARCHITECTURE == "wasm32" |
mips64 |
VCPKG_TARGET_ARCHITECTURE == "mips64" |
windows |
VCPKG_CMAKE_SYSTEM_NAME == "" orVCPKG_CMAKE_SYSTEM_NAME == "WindowsStore" orVCPKG_CMAKE_SYSTEM_NAME == "MinGW" |
mingw |
VCPKG_CMAKE_SYSTEM_NAME == "MinGW" |
uwp |
VCPKG_CMAKE_SYSTEM_NAME == "WindowsStore" |
xbox |
VCPKG_CMAKE_SYSTEM_NAME == "" andXBOX_CONSOLE_TARGET is defined. |
linux |
VCPKG_CMAKE_SYSTEM_NAME == "Linux" |
osx |
VCPKG_CMAKE_SYSTEM_NAME == "Darwin" |
ios |
VCPKG_CMAKE_SYSTEM_NAME == "iOS" |
freebsd |
VCPKG_CMAKE_SYSTEM_NAME == "FreeBSD" |
openbsd |
VCPKG_CMAKE_SYSTEM_NAME == "OpenBSD" |
android |
VCPKG_CMAKE_SYSTEM_NAME == "Android" |
emscripten |
VCPKG_CMAKE_SYSTEM_NAME == "Emscripten" |
qnx |
VCPKG_CMAKE_SYSTEM_NAME == "QNX" |
vxworks |
VCPKG_CMAKE_SYSTEM_NAME == "VxWorks" |
static |
VCPKG_LIBRARY_LINKAGE == "static" |
staticcrt |
VCPKG_CRT_LINKAGE == "static" |
native |
TARGET_TRIPLET == HOST_TRIPLET |
- Needs
picosha2
for sha256 on non-Windows, but get it from the OS on Windows (BCrypt)
{
"name": "picosha2",
"platform": "!windows"
}
- Require zlib on arm64 Windows and amd64 Linux
{
"name": "zlib",
"platform": "(windows & arm64) | (linux & x64)"
}
vcpkg feedback
vcpkg is an open source project. Select a link to provide feedback: