Registry docs: vcpkg.json should be baseline.json

[patrikhuber]

Type of issue

Typo

Description

Here:

You meant to write baseline.json, not vcpkg.json, right? As far as I am aware, there's no vcpkg.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

• ID: 90493daf-4ff2-0055-23a9-f22ea9a63e26
• Service: vcpkg

[patrikhuber]

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:

1. What I believe is the typo in the docs mentioned above - the text above probably means baseline.json, not vcpkg.json
2. 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.

@vicroms I'm currently trying to create a registry. Any advice on this?

[vicroms]

@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.

1. 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.

2. 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.

---

Versions database

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.

Baseline

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.

Version files

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:

• List all available versions of each port
• Point to the retrieval locations of each of these versions.

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:

• A version property: The property's key and value must match the ones used by the port in its 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
    }
  ]
}

[vicroms]

Should be fixed by #429