Tutorial: Publish packages to a private vcpkg registry using Git

Article
01/10/2024

You can create your own private registry of packages to consume via vcpkg using Git. Private registries are ideal if you want to use private libraries or want to make non-public modifications to existing packages. You have full control over your packages' versions and contents, so there's really no limit on what you can put in a private registry.

In this tutorial we show how to:

Create a vcpkg registry using Git
Create the registry layout
Add ports to the registry
Update the versions database

Prerequisites:

vcpkg
Git
A terminal

1 - Create a vcpkg registry using Git

vcpkg's Git-based registries are Git repositories with a specific layout that vcpkg understands.

Initialize a Git registry:

mkdir vcpkg-registry
cd vcpkg-registry
git init

2 - Create the registry layout

A vcpkg Git-based registry requires the following:

a folder named ports to contain the registry's ports,
a folder named versions to contain the versions database,
a file named baseline.json in the versions folder.

Your repository can contain any other files you want, for example: scripts, a LICENSE file, a README.md file, documentation, etc.

1 - Create the ports and versions folders:

mkdir ports
mkdir versions

2 - Create a file named baseline.json in the versions folder with the following contents:

{
  "default": {}
}

The minimal valid baseline.json file should include the above contents. Read the versioning documentation to learn more about the baseline.json file and the versions database.

3 - Commit your changes to the repository

git add versions/baseline.json
git commit -m "Initial commit"

Optionally, if you have a remote Git repository set up, this is a good point to push your changes.

git remote add origin https://example.com/vcpkg-registry.git
git push --set-upstream origin HEAD

3 - Add ports to the registry

Copy all your package ports in the ports folder in the registry. Each port must have its own directory containing at least a vcpkg.json file and a portfile.cmake file. Learn more about creating ports in the tutorial on packaging GitHub repositories.

git add ports/.
git commit -m "Add registry ports"

4 - Update the versions database

Each port in the registry must have a corresponding version file. Version files are generated by the vcpkg x-add-version command. This command also updates the baseline entry for each port in version/baseline.json.

To update the versions database for all your ports at once, run:

vcpkg --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions x-add-version --all --verbose

The --x-builtin-ports-root and --x-builtin-registry-versions-dir are redirection options. Normally, the x-add-version command operates on vcpkg's built-in registry; but by using the redirection options, it is possible to use the command on local Git registries.

The --all option makes vcpkg scan the ports directory for all available ports and updates them all at once. Lastly, the --verbose option makes the command print each operation it executes to standard output, you can suppress the output by removing this option.

The x-add-version requires that all port changes have been committed to the registry's Git repository. Read the [x-add-version command] documentation to learn more.

When all the output looks correct, run:

git add .
git commit -m "Update versions database"

If you have a remote Git repository, don't forget to push your changes:

git push

Next Steps

And that's it! You have set up your own private Git-based registry to use with vcpkg.

Here are some additional tasks to try next:

Share via