Open patrikhuber opened 3 weeks ago
I saw that the example registry repo actually has a vcpkg.json: https://github.com/microsoft/vcpkg-docs/blob/vcpkg-registry/vcpkg.json. But I don't think this is what the registries docs refer to. I think there are two (separate) confusing issues here:
@vicroms I'm currently trying to create a registry. Any advice on this?
@patrikhuber have you looked at https://learn.microsoft.com/vcpkg/produce/publish-to-a-git-registry. That article explains how to use the x-add-version
command to update these files in your own Git-based registries. If you need further assistance feel free to email me at viromer@microsoft.com.
- What I believe is the typo in the docs mentioned above - the text above probably means baseline.json, not vcpkg.json
The article needs to be reworked a lot, so please read the clarifications below. In this case it is not a typo, the vcpkg.json
the docs are referring to is the one in the port's directory.
- There is a vcpkg.json in the example registry repo, and it says "The dependency list should be populated with every port in the registry". However this is not documented at all in the registries docs. Also the main vcpkg registry (https://github.com/microsoft/vcpkg/) doesn't contain a vcpkg.json. So is this file required, or recommended, or not? This should be documented on https://learn.microsoft.com/en-us/vcpkg/maintainers/registries.
That vcpkg.json
file has a different purpose, it is used for Continuous Integration testing. Its purpose is described here: https://learn.microsoft.com/vcpkg/produce/test-registry-ports-gha. The curated registry at Microsoft/vcpkg doesn't contain that file because it uses a different method for its CI testing that is not suited for registry maintainers.
The versions database is comprised of two components, the baseline file and a set of versions files. The x-add-version
command should be used to maintain these files up to date without need of manual editing. It is expected that the versions database is updated each time a port is changed.
All registries must contain a file named baseline.json
located in <registry root>/versions/baseline.json
.
The purpose of the baseline file is to describe the set of versions that are considered to be the latest for all ports in the registry.
The layout of the file is a dictionary of named baselines. And each baseline must contain a dictionary that maps a port to its current version. For Git-based registries, a baseline named "default" is required to exist.
Example baseline.json
file:
{
"default": {
"foo": { "baseline": "1.0.0", "port-version": 0 },
"bar": { "baseline": "2024-08-01", "port-version": 1 },
"baz": { "baseline": "vista-xp", "port-version": 0 },
}
}
Each baseline version entry is an object with the following properties:
baseline
: the value is the port's version as it appears in the version
field in the port's vcpkg.json
file.port-version
: the value is the port's port-version
as it appears in the port's vcpkg.json
file. Each port in the registry must have a corresponding versions file. The versions file is a JSON file named the same as its corresponding port, for example, a port named foo
must have a corresponding foo.json
file.
vcpkg expects the versions files to be stored in the following location <registry root>/versions/<prefix>/<port name>.json
, where <prefix>
is the first letter of the port name followed by a hyphen. For example, the versions file for port foo
must be stored in <registry root>/versions/f-/foo.json
.
The purpose of the versions file is two-fold:
The layout of the version file is an object containing a "versions" array, with each entry in that array being a version object. A version object must contain the following properties:
vcpkg.json
file. The key must be one of version
, version-semver
, version-date
, or version-string
; the value must be the version as it appears in the port's manifest file (vcpkg.json
).port-version
: the value is the port's port-version
as it appears in the port's vcpkg.json
file.git-tree
: (only on Git-based registries) the value is the git-tree SHA corresponding to the port's directory. This is a SHA calculated by hashing the contents of the port's directory; this git-tree SHA can be used by Git to retrieve the contents of the port matching the provided git-tree. This makes it possible for vcpkg to retrieve old versions of ports from the registries Git history.path
: (only on filesystem registries) the value is the full path to a directory containing the port files for the specific version.Example of 3fd
's version file (<registry root>/3-/3fd.json
):
{
"versions": [
{
"git-tree": "81e9fd75ff6a4fee6ab7a5d4d09e7e3a735fbaaa",
"version": "2.6.3",
"port-version": 4
},
{
"git-tree": "0bfff492ed0b9ee3f31bb7593443572bc0fcf2d4",
"version": "2.6.3",
"port-version": 3
},
{
"git-tree": "3b52e6aff44ca4e11335754570701f692ea14184",
"version": "2.6.3",
"port-version": 2
},
{
"git-tree": "622078647d4fff0a51a26a4ecff2ba9109e5764d",
"version": "2.6.3",
"port-version": 1
},
{
"git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07",
"version-string": "2.6.3",
"port-version": 0
},
{
"git-tree": "70ed3ae824a2f31ed56b6c6105232bfe2aebe43e",
"version-string": "2.6.2",
"port-version": 3
},
{
"git-tree": "abd29087cbcde4a7416618fea70094c09fa16c37",
"version-string": "2.6.2-3",
"port-version": 0
},
{
"git-tree": "963060040c3ca463d17136e39c7317efb15eb6a5",
"version-string": "2.6.2-2",
"port-version": 0
},
{
"git-tree": "548c90710d59c174aa9ab10a24deb69f1d75ff8f",
"version-string": "2.6.2-1",
"port-version": 0
},
{
"git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e",
"version-string": "2.6.2",
"port-version": 0
}
]
}
Type of issue
Typo
Description
Here: You meant to write
baseline.json
, notvcpkg.json
, right? As far as I am aware, there's novcpkg.json
in a registry.The same text occurs once more further down on the docs page (two times in total).
Page URL
https://learn.microsoft.com/en-us/vcpkg/maintainers/registries
Content source URL
https://github.com/Microsoft/vcpkg-docs/blob/main/vcpkg/maintainers/registries.md
Document Version Independent Id
90493daf-4ff2-0055-23a9-f22ea9a63e26
Article author
@vicroms
Metadata