Edit

Overlay ports

  • Article

Usually, vcpkg ports are obtained from registries. It is very likely that most of the ports you install come from the official vcpkg registry at https://github.com/Microsoft/vcpkg. vcpkg lets you install ports available to you via the file system, we call these ports, overlay ports.

An overlay port can act as a drop-in replacement for an existing port or as a new port that is otherwise not available in a registry. While resolving package names, overlay ports take priority.

Overlay ports are evaluated in the following order:

When resolving port names, the first location that contains a matching overlay port is selected.

Using an overlay port

A directory can represent a set of overlay ports and can be specified in one of two ways:

  • Single overlay port: <directory>/sqlite3 refers to a single port
  • Directory of overlay ports: <directory> refers to a directory of ports A valid port must contain both vcpkg.json and portfile.cmake.

You can add an overlay port in several ways:

  • Command-line: Add one or multiple --overlay-ports=<directory> options to your vcpkg command
  • Manifest: Populate the "overlay-ports" array in vcpkg-configuration.json
  • Environmental variable: Set VCPKG_OVERLAY_PORTS to a list of directory paths

Example: Overlay Ports Example

Given this directory structure:

Example with multiple overlay port directories

Run:

vcpkg install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports

To install:

  • sqlite3 from my-ports

Run:

vcpkg install sqlite3 rapidjson curl 
    --overlay-ports=my-ports/rapidjson 
    --overlay-ports=vcpkg/ports/curl
    --overlay-ports=team-ports

To install:

  • sqlite3 from team-ports
  • rapidjson from my-ports
  • curl from `vcpkg/ports

Example: Using overlay ports to use a system package manager dependency

To use a system package manager dependency over a vcpkg one, refer to our blog post.