Tutorial: Install a dependency from a Git-based registry

vcpkg uses a concept called registries to manage repositories of packages. By default, vcpkg finds libraries from the public curated registry at https://github.com/Microsoft/vcpkg. You can add third-party or private registries to make additional packages available to install.

For information on creating your own registries, read the tutorial to publish packages to a registry.

Registries are configured using a vcpkg-configuration.json file.

In this tutorial, you will learn to:

• Create a project
• Create the manifest and configuration files
• Add private registries to your vcpkg configuration file
• Install packages from custom registries

Prerequisites

• A terminal
• A C++ compiiler
• vcpkg
• CMake

1 - Create a project

In a new folder, create the following project files:

A source file (main.cpp):

#include <iostream>
#include <beison.h>

int main()
{
    beison::Object obj;
    obj.insert("name", beison::Value::string("demo"));
    std::cout << beison::stringify(obj) << std::endl;
    return 0;
}

A CMake project file (CMakeLists.txt):

cmake_minimum_required(VERSION 3.18)

project(demo CXX)

add_executable(main main.cpp)

find_package(beicode CONFIG REQUIRED)
find_package(beison CONFIG REQUIRED)
target_link_libraries(main PRIVATE beicode::beicode beison::beison)

2 - Create the manifest and configuration files

Run the following command:

vcpkg new --application

The new commmand creates two files: a manifest (vcpkg.json) file and a configuration(vcpkg-configuration.json) file. Usually, the command requires the --name and --version arguments to be provided, but since this tutorial is an end-user application, we use the --application option instead.

The generated files will have the following contents:

vcpkg.json

{}

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "baseline": "7476f0d4e77d3333fbb249657df8251c28c4faae",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ]
}

The generated configuration file includes two registry definitions. The default-registry which points to the curated vcpkg registry at https://github.com/Microsoft/vcpkg, using the latest commit as the baseline, and an additional "artifacts" registry, which for the purpose of this tutorial is unnecessary and can be deleted.

3 - Add private registries to your vcpkg configuration file

The source code references two libraries that are not available in the vcpkg curated registry. In order to satisfy these dependencies we need to add https://github.com/microsoft/vcpkg-docs as an additional registry.

Modify the contents of vcpkg-configuration.json to:

{
  "default-registry": {
    "kind": "git",
    "baseline": "7476f0d4e77d3333fbb249657df8251c28c4faae",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/microsoft/vcpkg-docs",
      "reference": "vcpkg-registry",
      "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
      "packages": [ "beicode", "beison" ]
    }
  ]
}

The configuration file adds an external registry as the source for the beicode and beison packages. Additional registries must explicitly declare the packages they provide using the "packages" list. When vcpkg resolves packages names to a registry, any package name not found in an additional registry will be defaulted to the "default-registry". Learn more about package name resolution in the registries documentation.

4 - Install packages from a registry

Once a registry has been added to the configuration file, nothing special needs to be done to install packages from it. vcpkg will transparently resolve package names in your vcpkg.json to the correct registry when following the usual installation machinery.

Add the beicode and beison dependencies in your vcpkg.json file:

vcpkg add port beicode beison

Build and run the project (substitute $VCPKG_ROOT with your vcpkg installation path):

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build

Run the program, the output should look like this:

{
    "name": "demo"
}

Next steps

• Lock down your versions for repeatable builds using versioning
• Reuse binaries across local or continuous integration runs using binary caching
• Manage your private libraries using custom registries