awesome-copilot/skills/vcpkg/references/registries.md

vcpkg: Custom Registries & Overlay Ports

Reference for the vcpkg skill. Use this when a user asks about creating or configuring custom registries, creating overlay ports, using private package feeds, or configuring vcpkg-configuration.json registries.

Private / Custom Registry Install

1. Create vcpkg-configuration.json alongside your vcpkg.json:

{
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/your-org/vcpkg-registry",
      "baseline": "<commit-sha>",
      "packages": ["company-utils", "internal-lib"]
    }
  ],
  "default-registry": {
    "kind": "builtin",
    "baseline": "<commit-sha>"
  }
}

2. Then add the dependency normally in vcpkg.json:

{
  "dependencies": ["company-utils"]
}

The "packages" array in the registry entry controls which packages are resolved from that registry. Packages not listed fall through to default-registry.

---

Configuring Registries in vcpkg-configuration.json

{
  "default-registry": {
    "kind": "builtin",
    "baseline": "<vcpkg-commit-sha>"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/your-org/vcpkg-registry.git",
      "baseline": "<registry-commit-sha>",
      "packages": ["your-package-1", "your-package-2"]
    }
  ]
}

Place this file next to vcpkg.json in your project root.

---

Creating an Overlay Port

An overlay port overrides or adds a port locally. Directory structure:

my-overlays/
  telemetry-sdk/
    portfile.cmake
    vcpkg.json

vcpkg.json (port metadata):

{
  "name": "telemetry-sdk",
  "version": "1.0.0",
  "description": "Internal telemetry SDK",
  "dependencies": [
    "curl",
    "nlohmann-json",
    { "name": "vcpkg-cmake", "host": true },
    { "name": "vcpkg-cmake-config", "host": true }
  ]
}

portfile.cmake (build instructions):

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO your-org/telemetry-sdk
    REF v1.0.0
    SHA512 <hash>
)

vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")
vcpkg_cmake_install()
vcpkg_cmake_config_fixup()

file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

Classic mode: vcpkg install telemetry-sdk --overlay-ports=./my-overlays

Manifest mode: add telemetry-sdk to vcpkg.json, then run vcpkg install --overlay-ports=./my-overlays. Or in vcpkg-configuration.json:

{
  "overlay-ports": ["./my-overlays"]
}

---

Default Features

Control whether a dependency's existing default features are enabled, and request additional features in a project manifest:

{
  "dependencies": [
    {
      "name": "curl",
      "default-features": true,
      "features": ["ssl", "http2"]
    }
  ]
}

To disable default features: "default-features": false

In a portfile's vcpkg.json, default features are listed under:

{
  "name": "curl",
  "default-features": ["ssl", "http2"],
  "features": {
    "ssl": { "description": "SSL/TLS support" },
    "http2": { "description": "HTTP/2 support" }
  }
}