Using Registries
For information on creating your own registries, see Creating Registries.
vcpkg uses Registries to manage ports and versions. By default, vcpkg finds libraries from the public curated registry at https://github.com/microsoft/vcpkg. This default set can be extended by adding additional registry definitions or replaced with your own mirror of the public registry.
Registries are configured in the vcpkg-configuration.json.
Example vcpkg-configuration.json
{
"default-registry": {
"kind": "git",
"repository": "https://internal/mirror/of/github.com/Microsoft/vcpkg",
"baseline": "eefee7408133f3a0fef711ef9c6a3677b7e06fd7"
},
"registries": [
{
"kind": "git",
"repository": "https://github.com/northwindtraders/vcpkg-registry",
"baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
"packages": [ "beicode", "beison" ]
}
]
}
This example adds a private registry, https://github.com/northwindtraders/vcpkg-registry, as the source for the libraries beicode and beison. All other ports are found from an internal mirror of the Curated Catalog hosted at https://internal/mirror/of/github.com/Microsoft/vcpkg.
Package name resolution
vcpkg determines the responsible registry (or overlay) for each package before reaching out to the network. This prevents Package Dependency Confusion Attacks because name resolution does not depend on any external state.
The name resolution algorithm steps are:
- If the name is found in an overlay, use that overlay; otherwise
- If there is a
"packages"pattern that matches the port name, use that registry; otherwise - If the default registry is not
null, use that registry; otherwise - Fail to resolve the port to a registry.
When there are multiple "packages" patterns that match the name, we break ties as follows:
- Exact match --
boostis chosen overboost* - Longest pattern --
boost*is chosen overb* - First match -- The first registry declaring the best pattern is chosen
Example #1: Package name resolution
vcpkg-configuration.json
{
"registries": [
{
"kind": "git",
"repository": "https://github.com/northwindtraders/vcpkg-registry",
"baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
"packages": ["bei*"]
},
{
"kind": "git",
"repository": "https://github.com/vicroms/vcpkg-registry",
"baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
"packages": ["beicode", "bei*"]
}
]
}
vcpkg.json
{
"dependencies": [
"beicode",
"beison",
"fmt"
],
"builtin-baseline": "7e7c62d863b1bf599c1d104b76cd8b74475844d4"
}
Given this configuration, each package name resolves to:
beicode: from registryhttps://github.com/vicroms/vcpkg-registry(exact match onbeicode)beison: from registryhttps://github.com/northwindtraders/vcpkg-registry(pattern match onbeisonand declared first in"registries"array)fmt: from default registry (no matches)
Because multiple registries declare bei*, vcpkg will also emit a warning:
Found the following problems in configuration (path/to/vcpkg-configuration.json):
$ (a configuration object): warning: Package "bei*" is duplicated.
First declared in:
location: $.registries[0].packages[0]
registry: https://github.com/northwindtraders/vcpkg-registry
The following redeclarations will be ignored:
location: $.registries[1].packages[1]
registry: https://github.com/vicroms/vcpkg-registry
Example #2: Assign multiple patterns to the default registry
You can change the default registry in two ways. First, by defining the "default-registry":
{
"default-registry": {
"kind": "git",
"repository": "https://github.com/Microsoft/vcpkg",
"baseline": "e79c0d2b5d72eb3063cf32a1f7de1a9cf19930f3"
}
}
Second, by setting the "default-registry" to null and using the "*" pattern in the "registries" array:
{
"default-registry": null,
"registries": [
{
"kind": "git",
"repository": "https://github.com/Microsoft/vcpkg",
"baseline": "e79c0d2b5d72eb3063cf32a1f7de1a9cf19930f3",
"packages": ["*"]
}
]
}
An advantage of the second form is that you can add more entries to the packages array, while the "default-registry" object doesn't allow you to define a packages array at all. This difference becomes important in cases where you need to ensure that a package comes from the default registry.
Let's consider a registry that provides the Qt Framework libraries.
vcpkg-configuration.json
{
"default-registry": {
"kind": "git",
"repository": "https://github.com/Microsoft/vcpkg",
"baseline": "7e7c62d863b1bf599c1d104b76cd8b74475844d4"
},
"registries": [
{
"kind": "git",
"repository": "https://github.com/custom-qt/custom-qt-registry",
"baseline": "adfc4de488094a384ca2c202b923ccc097956e0c",
"packages": ["qt*"]
}
]
}
And the following project dependencies:
vcpkg.json
{
"dependencies": [
"qt5",
"qt-advanced-docking-system",
"qtkeychain"
]
}
The "qt*" pattern matches all port names in vcpkg.json. But there is a problem! The ports qt-advanced-docking-system and qtkeychain are not part of the official Qt Framework libraries and since vcpkg won't be able to find the ports in the custom registry the installation will fail.
This can be fixed by assigning these packages to the default registry instead. We accomplish that by changing the way we declare the default registry and adding qt-advanced-docking-system and qtkeychain to its "packages" array:
vcpkg-configuration.json
{
"default-registry": null,
"registries": [
{
"kind": "git",
"repository": "https://github.com/Microsoft/vcpkg",
"baseline": "e79c0d2b5d72eb3063cf32a1f7de1a9cf19930f3",
"packages": ["*", "qt-advanced-docking-system", "qtkeychain"]
},
{
"kind": "git",
"repository": "https://github.com/custom-qt/custom-qt-registry",
"baseline": "adfc4de488094a384ca2c202b923ccc097956e0c",
"packages": ["qt*"]
}
]
}
Because exact matches are preferred over pattern matches, qt-advanced-docking-system and qtkeychain will resolve to the default registry.
Overlays
Overlays are a way to extend vcpkg with additional ports and additional triplets, without creating a full registry. Overlays are considered before performing any registry lookups or versioning and will replace any builtin triplets or ports.
Overlay settings are evaluated in this order:
- Overlays from the command line in the order passed; then
- Overlays from
vcpkg-configuration.jsonin order; then - Overlays from the
VCPKG_OVERLAY_[PORTS|TRIPLETS]environment variables in order
Feedback
Submit and view feedback for