Skip to content

Latest commit

 

History

History
73 lines (49 loc) · 3.18 KB

overlay-ports.md

File metadata and controls

73 lines (49 loc) · 3.18 KB
Raw
title description author ms.author ms.date ms.topic
Overlay ports
This article describes overlay ports in vcpkg. Overlay ports are used to force a specific port definition to be used by vcpkg during the package installation process.
data-queue
danshaw2
01/10/2024
concept-article

Overlay ports

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:

:::image type="complex" source="../resources/ports-overlay-example.png" alt-text="Example with multiple overlay port directories"::: Overlay directory named team-ports contains ports sqlite3, rapidjson and curl. Overlay directory named my-ports contains ports sqlite3 and rapidjson. The vcpkg directory contains the default registry. :::image-end:::

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.