For many users of vcpkg, the built-in repository of packages is completely sufficient. If you only need public, non-experimental libraries, the default vcpkg registry is completely fine. However, once you go outside of this world – once you have company-internal libraries, or you want to use experimental libraries, the recommended solution is to use a registry.

Quite a few people have already set up their own registries, and if you want to learn to set up your own, you can check out the last blogpost. However, if you want to use an existing registry, this tutorial is for you.

We also have reference documentation in the vcpkg repository.

Getting Started

Before anything else, you’ll need a vcpkg installation, and you’ll need to decide whether you’re using manifest mode or classic mode (in other words, installing packages manually using the command line). The use of registries is the same either way.

You’ll want to create a vcpkg-configuration.json file; in manifest mode, you’d place it alongside your vcpkg.json file, while in classic mode you’d place it in the vcpkg root directory. There are two important keys in this file: "default-registry", and "registries".

"default-registry" allows you to set the fallback registry, for packages that aren’t covered by any of the registries in the "registries" array. "registries" allows you to set up registries for specific packages.

Example: North Wind Traders

Your company, North Wind Traders, has decided to mirror the default vcpkg registry (from https://github.com/microsoft/vcpkg) in order to ensure business continuity and control of sources for purposes of security, and you’ve set it up as your default registry so that it’s used for every package that isn’t explicitly listed in a package registry. Your vcpkg-configuration.json file should look like this:

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/northwindtraders/vcpkg-mirror",
    "baseline": "eefee7408133f3a0fef711ef9c6a3677b7e06fd7"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/northwindtraders/vcpkg-registry",
      "baseline": "dacf4de488094a384ca2c202b923ccc097956e0c",
      "packages": [ "beison", "beicode" ]
    }
  ]
}

You also depend on your private registry for two of your internal libraries: beison and beicode. These libraries are neither open source nor public, but they are still managed via vcpkg, and you don’t have to be concerned about different processes for different libraries (at least at the consumption side). With manifests, you write your dependencies down, and the CMake or MSBuild integration will install all of those dependencies into your project, whether from the default, built-in registry, or from third-party registries. Private dependencies are exactly the same as public dependencies, as far as vcpkg is concerned. For classic mode, you tell vcpkg to install the packages you need from the command line. vcpkg will install them into the vcpkg git repository you’ve cloned, and you can access them either via direct usage or via the CMake and MSBuild integration. These existing use cases all “just work”, without any extra work from you on top of existing workflows. All you need is a configuration file.

Give us your feedback!

Try out vcpkg by visiting our GitHub repo.

This is a relatively new feature, and the user experience is still being actively worked on. We want to create the best and simplest experience possible for our users, and so we welcome your feedback on this new feature in our issue tracker!

The current up-to-date documentation on using registries can be found in our GitHub repository.