From ed0f1f3ab1f4f6f060240d0514ef3a8dcec678d9 Mon Sep 17 00:00:00 2001 From: Billy Robert O'Neal III Date: Fri, 1 Nov 2024 20:09:13 -0700 Subject: [PATCH 1/6] Document "overlay-port-dirs". --- vcpkg/commands/common-options.md | 10 +++- vcpkg/commands/help.md | 6 ++- vcpkg/concepts/manifest-mode.md | 3 ++ vcpkg/concepts/overlay-ports.md | 47 ++++++++++++++----- vcpkg/concepts/package-name-resolution.md | 39 +++++++++++---- vcpkg/get_started/get-started-packaging.md | 4 +- vcpkg/produce/test-registry-ports-ado.md | 2 +- vcpkg/produce/test-registry-ports-gha.md | 2 +- vcpkg/reference/vcpkg-configuration-json.md | 23 ++++++--- vcpkg/reference/vcpkg-json.md | 5 +- vcpkg/users/buildsystems/cmake-integration.md | 4 ++ vcpkg/users/config-environment.md | 9 +++- 12 files changed, 115 insertions(+), 39 deletions(-) diff --git a/vcpkg/commands/common-options.md b/vcpkg/commands/common-options.md index 2e3d9b03..861da871 100644 --- a/vcpkg/commands/common-options.md +++ b/vcpkg/commands/common-options.md @@ -107,9 +107,15 @@ Defaults to searching upwards from the current working directory for the nearest ### `--overlay-ports=` -Specifies a directory containing [overlay ports](../concepts/package-name-resolution.md#overlays). +Specifies a directory either an [overlay port](../concepts/package-name-resolution.md#overlays), or subdirectories that are themselves overlay-ports. If `` does not contain a `CONTROL` or `vcpkg.json`, `--overlay-ports` is equivalent to `--overlay-port-dirs`. -This option can be specified multiple times; ports will resolve to the first match. +This option can be specified multiple times; ports will resolve to the first match. `--overlay-port-dirs` will be considered first. + +### `--overlay-port-dirs=` + +Specifies a directory to be subdirectories that are [overlay port](../concepts/package-name-resolution.md#overlays). + +This option can be specified multiple times; ports will resolve to the first match. `--overlay-port-dirs` will be considered before `--overlay-ports`. ### `--overlay-triplets=` diff --git a/vcpkg/commands/help.md b/vcpkg/commands/help.md index 230c7f4c..3d5f0131 100644 --- a/vcpkg/commands/help.md +++ b/vcpkg/commands/help.md @@ -95,7 +95,11 @@ Options: --host-triplet=... Host triplet. See 'vcpkg help triplet' (default: %VCPKG_DEFAULT_HOST_TRIPLET%) --x-install-root=... Installed directory (experimental) - --overlay-ports=... Directories of overlay ports (also: %VCPKG_OVERLAY_PORTS%) + --overlay-port-dirs=... + Directories containing overlay-port directories (also: + %VCPKG_OVERLAY_PORT_DIRS%) + --overlay-ports=... Overlay-port directories, or directories containing overlay-port + directories (also: %VCPKG_OVERLAY_PORTS%) --overlay-triplets=... Directories of overlay triplets (also: %VCPKG_OVERLAY_TRIPLETS%) --x-packages-root=... Packages directory (experimental) --triplet=... Target triplet. See 'vcpkg help triplet' (default: %VCPKG_DEFAULT_TRIPLET%) diff --git a/vcpkg/concepts/manifest-mode.md b/vcpkg/concepts/manifest-mode.md index 23a35a00..5fe36a35 100644 --- a/vcpkg/concepts/manifest-mode.md +++ b/vcpkg/concepts/manifest-mode.md @@ -100,6 +100,9 @@ vcpkg can be configured through a `vcpkg-configuration.json` file to add more "packages": [ "beicode", "beison" ] } ], + "overlay-port-dirs": [ + "C:\\dev\\my_vcpkg_port\\directories" + ], "overlay-ports": [ "C:\\dev\\my_vcpkg_ports" ] diff --git a/vcpkg/concepts/overlay-ports.md b/vcpkg/concepts/overlay-ports.md index 56cc4822..2823db3e 100644 --- a/vcpkg/concepts/overlay-ports.md +++ b/vcpkg/concepts/overlay-ports.md @@ -15,25 +15,50 @@ An overlay port can act as a drop-in replacement for an existing port or as a ne Overlay ports are evaluated in the following order: -* Overlay locations specified in the command-line via [`--overlay-ports`](../commands/common-options.md#overlay-ports). -* Overlay locations specified in a `vcpkg-configuration.json` file via [`overlay-ports`](../reference/vcpkg-configuration-json.md). -* Overlay locations specified by the [`VCPKG_OVERLAY_PORTS`](../users/config-environment.md#vcpkg_overlay_ports) environment variable. +* Named subdirectories of directories specified in the command-line via [`--overlay-port-dirs`](../commands/common-options.md#overlay-port-dirs). +* Named subdirectories of directories specified in a `vcpkg-configuration.json` file via [`overlay-port-dirs`](../reference/vcpkg-configuration-json.md). +* Named subdirectories of directories specified by the [`VCPKG_OVERLAY_PORT_DIRS`](../users/config-environment.md#vcpkg_overlay_port_dirs) environment variable. +* The directory specified in the command-line via [`--overlay-ports`](../commands/common-options.md#overlay-ports), or named subdirectories if that directory has no `CONTROL` or `vcpkg.json` file. +* The directory specified in a `vcpkg-configuration.json` file via [`overlay-ports`](../reference/vcpkg-configuration-json.md), or named subdirectories if that directory has no `CONTROL` or `vcpkg.json` file. +* The directory specified by [`VCPKG_OVERLAY_PORTS`](../users/config-environment.md#vcpkg_overlay_ports) environment variable entries, or named subdirectories if that directory has no `CONTROL` or `vcpkg.json` file. 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: +If an overlay port is specified, first, vcpkg attempts to load that directory as a port. If that succeeds, the directory itself is itself treated as a port, and the name of the overlay is derived from the `CONTROL` or `vcpkg.json` file. Otherwise, subdirectories with the overlay port name are considered. -* Single overlay port: `/sqlite3` refers to a single port -* Directory of overlay ports: `` refers to a directory of ports -A valid port must contain both `vcpkg.json` and `portfile.cmake`. +If an overlay port dir is specified, never attempts to load that as a port, and proceeds to the subdirectories with overlay port names. -You can add an overlay port in several ways: +Valid ports contain `portfile.cmake`, and either `vcpkg.json` or `CONTROL`. -* Command-line: Add one or multiple `--overlay-ports=` options to your vcpkg command -* [Manifest](../reference/vcpkg-configuration-json.md#overlay-ports): Populate the `"overlay-ports"` array in `vcpkg-configuration.json` -* [Environmental variable](../users/config-environment.md#vcpkg_overlay_ports): Set `VCPKG_OVERLAY_PORTS` to a list of directory paths +For example, consider the following directory structure: + +* `x/vcpkg.json`, the `"name"` field is set to `"a"`. +* `x/portfile.cmake`, the associated build instructions for `a`. +* `x/b/vcpkg.json`, the `"name"` field is set to `"b"`. +* `x/b/portfile.cmake`, the associated build instructions for `b`. +* `x/c/vcpkg.json`, the `"name"` field is set to `"c"`. +* `x/c/portfile.cmake`, the associated build instructions for `c`. +* `y/d/vcpkg.json`, the `"name"` field is set to `"d"`. +* `y/d/portfile.cmake`, the associated build instructions for `d`. +* `y/e/vcpkg.json`, the `"name"` field is set to `"e"`. +* `y/e/portfile.cmake`, the associated build instructions for `e`. + +vcpkg will consider the following ports given the following settings: + +* `--overlay-ports=x`: There is one port in this overlay, `a`. The name is derived from `vcpkg.json`. +* `--overlay-ports=x/b`: There is one port in this overlay, `b`. The name is derived from `vcpkg.json`. +* `--overlay-ports=y`: There are two ports in this overlay, `d` and `e`. Their names are derived from the subdirectories of `y`, and the names declared in their `vcpkg.json` must match, or an error will be generated if vcpkg is asked to install `d` or `e`. +* `--overlay-port-dirs=x`: There are two ports from this overlay, `b` and `c`. Their names are derived from the subdirectories of `x`, and the names declared in their `vcpkg.json` must match, or an error will be generated if vcpkg is asked to install `b` or `c`. +* `--overlay-port-dirs=x/b`: There are no ports from this overlay as there are no subdirectories. +* `--overlay-port-dirs=y`: This is the same case as `--overlay-ports=y`, because there is no `y/CONTROL` or `y/vcpkg.json`. There are two ports in this overlay, `d` and `e`. Their names are derived from the subdirectories of `y`, and the names declared in their `vcpkg.json` must match, or an error will be generated if vcpkg is asked to install `d` or `e`. + +You can add to overlay port configuration in several ways: + +* Command-line: Add one or more `--overlay-port-dirs=` or `--overlay-ports=` options to the command-line. +* [Manifest](../reference/vcpkg-configuration-json.md#overlay-ports): Populate the `"overlay-port-dirs"` or `"overlay-ports"` arrays in `vcpkg-configuration.json`. +* [Environmental variable](../users/config-environment.md#vcpkg_overlay_ports): Set `VCPKG_OVERLAY_PORT_DIRS` or `VCPKG_OVERLAY_PORTS` to a path character delimited list. ### Example: Overlay Ports Example diff --git a/vcpkg/concepts/package-name-resolution.md b/vcpkg/concepts/package-name-resolution.md index eab92e15..995041c7 100644 --- a/vcpkg/concepts/package-name-resolution.md +++ b/vcpkg/concepts/package-name-resolution.md @@ -194,19 +194,38 @@ Because exact matches are preferred over pattern matches, `qt-advanced-docking-system` and `qtkeychain` will resolve to the default registry. -## Overlays +## Overlay ports -Overlays are a way to extend vcpkg with additional ports and additional -triplets, without creating a full registry. Overlays are considered before -performing any registry lookups or versioning and will replace any builtin -triplets or ports. See [overlay ports](../concepts/overlay-ports.md) to learn more. +Overlay ports are a way to extend vcpkg with additional ports without creating a full registry. Overlays are considered before any registry lookups, or versioning considerations. Overlays replace any builtin triplets or ports. See [overlay ports](../concepts/overlay-ports.md) to learn more. -Overlay settings are evaluated in this order: +Overlay triplets are evaluated in this order: -1. Overlays from the [command line](../commands/common-options.md#overlay-ports) +1. Overlays from the [command line](../commands/common-options.md#overlay-port-dirs) `--overlay-port-dirs` in the order passed; then 2. Overlays from - [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md#overlay-ports) + [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md#overlay-port-dirs) `"overlay-port-dirs"` in order; then -3. Overlays from the `VCPKG_OVERLAY_[PORTS|TRIPLETS]` [environment - variables](../users/config-environment.md#vcpkg_overlay_ports) in order. +3. Overlays from the `VCPKG_OVERLAY_PORT-DIRS` [environment + variable](../users/config-environment.md#vcpkg_overlay_port_dirs) in order. +4. Overlays from the [command line](../commands/common-options.md#overlay-ports) `--overlay-ports` + in the order passed; then +5. Overlays from + [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md#overlay-ports) `"overlay-ports"` + in order; then +6. Overlays from the `VCPKG_OVERLAY_PORTS` [environment + variable](../users/config-environment.md#vcpkg_overlay_ports) in order. + +## Overlay triplets + +Overlay triplets are a way to extend vcpkg with additional triplets, without modifying vcpkg's installation directory. Overlays are considered before any builtin triplets. + +Overlay triplets are evaluated in this order: + +1. Overlays from the [command line](../commands/common-options.md#overlay-triplets) + in the order passed; then +2. Overlays from + [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md#overlay-triplets) + in order; then +3. Overlays from the `VCPKG_OVERLAY_TRIPLETS` [environment + variable](../users/config-environment.md#vcpkg_overlay_triplets) in order. + diff --git a/vcpkg/get_started/get-started-packaging.md b/vcpkg/get_started/get-started-packaging.md index 0b8c1ea6..43c8e535 100644 --- a/vcpkg/get_started/get-started-packaging.md +++ b/vcpkg/get_started/get-started-packaging.md @@ -212,7 +212,7 @@ For more information, refer to the [maintainer guide](../contributing/maintainer Run: ```console -vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay +vcpkg install vcpkg-sample-library --overlay-port-dirs=C:\path\to\custom-overlay ``` You will get a long error message. Scan the output until you find: @@ -229,7 +229,7 @@ and replace the `SHA512` value in the `portfile.cmake` with its value. Re-run the install command: ```console -vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay +vcpkg install vcpkg-sample-library --overlay-port-dirs=C:\path\to\custom-overlay ``` ```console diff --git a/vcpkg/produce/test-registry-ports-ado.md b/vcpkg/produce/test-registry-ports-ado.md index aa79d38d..7a4d713c 100644 --- a/vcpkg/produce/test-registry-ports-ado.md +++ b/vcpkg/produce/test-registry-ports-ado.md @@ -228,7 +228,7 @@ ports currently in the working directory as opposed to the versions published in your repository. To that goal, you need to add your registry's ports as [overlay -ports](../concepts/overlay-ports.md) by setting the `VCPKG_OVERLAY_PORTS` +ports](../concepts/overlay-ports.md) by setting the `VCPKG_OVERLAY_PORT_DIRS` environment variable to your registry's `ports` directory. The snippet below shows how to set up your registry's ports as overlay ports and diff --git a/vcpkg/produce/test-registry-ports-gha.md b/vcpkg/produce/test-registry-ports-gha.md index 6ade76bb..2043afa3 100644 --- a/vcpkg/produce/test-registry-ports-gha.md +++ b/vcpkg/produce/test-registry-ports-gha.md @@ -207,7 +207,7 @@ ports currently in the working directory as opposed to the versions published in your repository. To that goal, you need to add your registry's ports as [overlay -ports](../concepts/overlay-ports.md) by setting the `VCPKG_OVERLAY_PORTS` +ports](../concepts/overlay-ports.md) by setting the `VCPKG_OVERLAY_PORT_DIRS` environment variable to your registry's `ports` directory. The snippet below shows how to set up your registry's ports as overlay ports and diff --git a/vcpkg/reference/vcpkg-configuration-json.md b/vcpkg/reference/vcpkg-configuration-json.md index 3a3a585a..b5929677 100644 --- a/vcpkg/reference/vcpkg-configuration-json.md +++ b/vcpkg/reference/vcpkg-configuration-json.md @@ -43,9 +43,11 @@ The latest JSON Schema is available at [https://raw.githubusercontent.com/micros "packages": [ "beicode", "beison" ] } ], + "overlay-ports-dirs": [ + "./team-ports" + ], "overlay-ports": [ - "./team-ports", - "./custom-ports" + "./custom-ports/zlib" ], "overlay-triplets": [ "./my-triplets" ] } @@ -60,7 +62,8 @@ The example also configures custom overlays for ports and triplets that are pres | Name | Type | Description | |------|--------|-------------| | [default-registry](#default-registry) | [Registry][] or null | Registry used for all ports without a specific registry | -| [overlay-ports](#overlay-ports) | string[] | List of paths to use as overlay ports | +| [overlay-port-dirs](#overlay-port-dirs) | string[] | List of paths to use as overlay port directories | +| [overlay-ports](#overlay-ports) | string[] | List of paths to use as overlay port locations | | [overlay-triplets](#overlay-triplets) | string[] | List of paths to use as overlay triplets | | [registries](#registries) | [Registry][][] | Additional registries to use for subsets of ports | @@ -74,14 +77,22 @@ Ports that do not match any [`"packages"`](#registry-packages) pattern are resol Additional registries to use for specific ports. An array of [Registries](#registry). Optional. +### `"overlay-port-dirs"` + +A list of port overlay directories. An array of strings. Optional. + +Each path in the array must name a directory containing port directories named after the ports (`zlib`'s `vcpkg.json` must be at `zlib/vcpkg.json`). + +Relative paths are resolved relative to the `vcpkg-configuration.json` file. Absolute paths can be used but are discouraged. + ### `"overlay-ports"` A list of port overlay paths. An array of strings. Optional. -Each path in the array must point to either: +Each path in the array must name either: -- A port directory containing `vcpkg.json` and `portfile.cmake` -- A directory containing port directories named after the ports (`zlib`'s `vcpkg.json` must be at `zlib/vcpkg.json`). +- A directory containing a port, with `vcpkg.json` and `portfile.cmake` files, or +- A directory containing directories named after the ports (`zlib`'s `vcpkg.json` must be at `zlib/vcpkg.json`). Relative paths are resolved relative to the `vcpkg-configuration.json` file. Absolute paths can be used but are discouraged. diff --git a/vcpkg/reference/vcpkg-json.md b/vcpkg/reference/vcpkg-json.md index 922facc5..10371487 100644 --- a/vcpkg/reference/vcpkg-json.md +++ b/vcpkg/reference/vcpkg-json.md @@ -285,9 +285,8 @@ Having a `vcpkg-configuration` defined in `vcpkg.json` while also having a `vcpk "packages": [ "beicode", "beison" ] } ], - "overlay-ports": [ "./my-ports/fmt", - "./team-ports" - ] + "overlay-port-dirs": [ "./team-ports" ], + "overlay-ports": [ "./my-ports/fmt" ] } ``` diff --git a/vcpkg/users/buildsystems/cmake-integration.md b/vcpkg/users/buildsystems/cmake-integration.md index d68eff9e..0c4335b7 100644 --- a/vcpkg/users/buildsystems/cmake-integration.md +++ b/vcpkg/users/buildsystems/cmake-integration.md @@ -188,6 +188,10 @@ In manifest mode, vcpkg will be automatically bootstrapped if the executable doe This variable can be set to a list of paths to be passed on the command line as `--overlay-triplets=...` +### `VCPKG_OVERLAY_PORT_DIRS` + +This variable can be set to a list of paths to be passed on the command line as `--overlay-port-dirs=...` + ### `VCPKG_OVERLAY_PORTS` This variable can be set to a list of paths to be passed on the command line as `--overlay-ports=...` diff --git a/vcpkg/users/config-environment.md b/vcpkg/users/config-environment.md index 8fcf907f..216456ed 100644 --- a/vcpkg/users/config-environment.md +++ b/vcpkg/users/config-environment.md @@ -43,10 +43,15 @@ This environment variable can be set to a triplet name which will be used for un This environment variable can be set to a triplet name which will be used for unqualified host port references in command lines and all host port references in dependency lists. See [the host-dependencies documentation](host-dependencies.md) for more information. +## VCPKG_OVERLAY_PORT_DIRS + +This environment variable adds additional [overlay port directories](registries.md#overlays) considered after those listed on the command line. Multiple directories are separated with the platform dependent PATH separator (Windows `;` | others `:`) + +Example (Windows): `C:\custom-ports;C:\other-ports` + ## VCPKG_OVERLAY_PORTS -This environment variable adds additional [overlay ports](registries.md#overlays) paths considered after those listed on the command line. List paths to overlays using -the platform dependent PATH separator (Windows `;` | others `:`) +This environment variable adds additional [overlay ports or overlay port directories](registries.md#overlays) considered after those listed on the command line. Multiple values are separated with the platform dependent PATH separator (Windows `;` | others `:`) Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3` From 10f7f6dfae750737a6bbba4cbab03b06d2e6557c Mon Sep 17 00:00:00 2001 From: Billy Robert O'Neal III Date: Fri, 1 Nov 2024 20:22:48 -0700 Subject: [PATCH 2/6] Fix link target. --- vcpkg/commands/common-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vcpkg/commands/common-options.md b/vcpkg/commands/common-options.md index 861da871..6ab1aab5 100644 --- a/vcpkg/commands/common-options.md +++ b/vcpkg/commands/common-options.md @@ -111,7 +111,7 @@ Specifies a directory either an [overlay port](../concepts/package-name-resoluti This option can be specified multiple times; ports will resolve to the first match. `--overlay-port-dirs` will be considered first. -### `--overlay-port-dirs=` +### `--overlay-port-dirs=` Specifies a directory to be subdirectories that are [overlay port](../concepts/package-name-resolution.md#overlays). From cf13ae2a4b7becd2fc3ddb3dcc9612dd694e8f35 Mon Sep 17 00:00:00 2001 From: Billy Robert O'Neal III Date: Tue, 12 Nov 2024 17:37:53 -0800 Subject: [PATCH 3/6] Delete overlay-port-dirs, but keep the other clarifications. --- vcpkg/commands/common-options.md | 8 +----- vcpkg/commands/help.md | 3 --- vcpkg/concepts/manifest-mode.md | 3 --- vcpkg/concepts/overlay-ports.md | 26 ++++++------------- vcpkg/concepts/package-name-resolution.md | 13 +++------- vcpkg/get_started/get-started-packaging.md | 4 +-- vcpkg/produce/test-registry-ports-ado.md | 2 +- vcpkg/produce/test-registry-ports-gha.md | 2 +- vcpkg/reference/vcpkg-configuration-json.md | 15 ++--------- vcpkg/reference/vcpkg-json.md | 5 ++-- vcpkg/users/buildsystems/cmake-integration.md | 4 --- vcpkg/users/config-environment.md | 9 ++----- 12 files changed, 23 insertions(+), 71 deletions(-) diff --git a/vcpkg/commands/common-options.md b/vcpkg/commands/common-options.md index a5aa73b0..eb33eae1 100644 --- a/vcpkg/commands/common-options.md +++ b/vcpkg/commands/common-options.md @@ -111,16 +111,10 @@ Defaults to searching upwards from the current working directory for the nearest ### `--overlay-ports=` -Specifies a directory either an [overlay port](../concepts/package-name-resolution.md#overlays), or subdirectories that are themselves overlay-ports. If `` does not contain a `CONTROL` or `vcpkg.json`, `--overlay-ports` is equivalent to `--overlay-port-dirs`. +Specifies a directory either an [overlay port](../concepts/package-name-resolution.md#overlays), or subdirectories that are themselves overlay-ports. If `` contains a `CONTROL` or `vcpkg.json`, subdirectories are not considered. This option can be specified multiple times; ports will resolve to the first match. `--overlay-port-dirs` will be considered first. -### `--overlay-port-dirs=` - -Specifies a directory to be subdirectories that are [overlay port](../concepts/package-name-resolution.md#overlays). - -This option can be specified multiple times; ports will resolve to the first match. `--overlay-port-dirs` will be considered before `--overlay-ports`. - ### `--overlay-triplets=` Specifies a directory containing [overlay triplets](../concepts/triplets.md#custom-triplets). diff --git a/vcpkg/commands/help.md b/vcpkg/commands/help.md index 3d5f0131..a910f021 100644 --- a/vcpkg/commands/help.md +++ b/vcpkg/commands/help.md @@ -95,9 +95,6 @@ Options: --host-triplet=... Host triplet. See 'vcpkg help triplet' (default: %VCPKG_DEFAULT_HOST_TRIPLET%) --x-install-root=... Installed directory (experimental) - --overlay-port-dirs=... - Directories containing overlay-port directories (also: - %VCPKG_OVERLAY_PORT_DIRS%) --overlay-ports=... Overlay-port directories, or directories containing overlay-port directories (also: %VCPKG_OVERLAY_PORTS%) --overlay-triplets=... Directories of overlay triplets (also: %VCPKG_OVERLAY_TRIPLETS%) diff --git a/vcpkg/concepts/manifest-mode.md b/vcpkg/concepts/manifest-mode.md index 5fe36a35..23a35a00 100644 --- a/vcpkg/concepts/manifest-mode.md +++ b/vcpkg/concepts/manifest-mode.md @@ -100,9 +100,6 @@ vcpkg can be configured through a `vcpkg-configuration.json` file to add more "packages": [ "beicode", "beison" ] } ], - "overlay-port-dirs": [ - "C:\\dev\\my_vcpkg_port\\directories" - ], "overlay-ports": [ "C:\\dev\\my_vcpkg_ports" ] diff --git a/vcpkg/concepts/overlay-ports.md b/vcpkg/concepts/overlay-ports.md index 2823db3e..cec399d8 100644 --- a/vcpkg/concepts/overlay-ports.md +++ b/vcpkg/concepts/overlay-ports.md @@ -15,9 +15,6 @@ An overlay port can act as a drop-in replacement for an existing port or as a ne Overlay ports are evaluated in the following order: -* Named subdirectories of directories specified in the command-line via [`--overlay-port-dirs`](../commands/common-options.md#overlay-port-dirs). -* Named subdirectories of directories specified in a `vcpkg-configuration.json` file via [`overlay-port-dirs`](../reference/vcpkg-configuration-json.md). -* Named subdirectories of directories specified by the [`VCPKG_OVERLAY_PORT_DIRS`](../users/config-environment.md#vcpkg_overlay_port_dirs) environment variable. * The directory specified in the command-line via [`--overlay-ports`](../commands/common-options.md#overlay-ports), or named subdirectories if that directory has no `CONTROL` or `vcpkg.json` file. * The directory specified in a `vcpkg-configuration.json` file via [`overlay-ports`](../reference/vcpkg-configuration-json.md), or named subdirectories if that directory has no `CONTROL` or `vcpkg.json` file. * The directory specified by [`VCPKG_OVERLAY_PORTS`](../users/config-environment.md#vcpkg_overlay_ports) environment variable entries, or named subdirectories if that directory has no `CONTROL` or `vcpkg.json` file. @@ -28,8 +25,6 @@ When resolving port names, the first location that contains a matching overlay p If an overlay port is specified, first, vcpkg attempts to load that directory as a port. If that succeeds, the directory itself is itself treated as a port, and the name of the overlay is derived from the `CONTROL` or `vcpkg.json` file. Otherwise, subdirectories with the overlay port name are considered. -If an overlay port dir is specified, never attempts to load that as a port, and proceeds to the subdirectories with overlay port names. - Valid ports contain `portfile.cmake`, and either `vcpkg.json` or `CONTROL`. For example, consider the following directory structure: @@ -38,27 +33,22 @@ For example, consider the following directory structure: * `x/portfile.cmake`, the associated build instructions for `a`. * `x/b/vcpkg.json`, the `"name"` field is set to `"b"`. * `x/b/portfile.cmake`, the associated build instructions for `b`. -* `x/c/vcpkg.json`, the `"name"` field is set to `"c"`. -* `x/c/portfile.cmake`, the associated build instructions for `c`. +* `y/c/vcpkg.json`, the `"name"` field is set to `"c"`. +* `y/c/portfile.cmake`, the associated build instructions for `c`. * `y/d/vcpkg.json`, the `"name"` field is set to `"d"`. * `y/d/portfile.cmake`, the associated build instructions for `d`. -* `y/e/vcpkg.json`, the `"name"` field is set to `"e"`. -* `y/e/portfile.cmake`, the associated build instructions for `e`. vcpkg will consider the following ports given the following settings: -* `--overlay-ports=x`: There is one port in this overlay, `a`. The name is derived from `vcpkg.json`. +* `--overlay-ports=x`: There is one port in this overlay, `a`. The name is derived from `vcpkg.json`. The subdirectory `b` is not considered. * `--overlay-ports=x/b`: There is one port in this overlay, `b`. The name is derived from `vcpkg.json`. -* `--overlay-ports=y`: There are two ports in this overlay, `d` and `e`. Their names are derived from the subdirectories of `y`, and the names declared in their `vcpkg.json` must match, or an error will be generated if vcpkg is asked to install `d` or `e`. -* `--overlay-port-dirs=x`: There are two ports from this overlay, `b` and `c`. Their names are derived from the subdirectories of `x`, and the names declared in their `vcpkg.json` must match, or an error will be generated if vcpkg is asked to install `b` or `c`. -* `--overlay-port-dirs=x/b`: There are no ports from this overlay as there are no subdirectories. -* `--overlay-port-dirs=y`: This is the same case as `--overlay-ports=y`, because there is no `y/CONTROL` or `y/vcpkg.json`. There are two ports in this overlay, `d` and `e`. Their names are derived from the subdirectories of `y`, and the names declared in their `vcpkg.json` must match, or an error will be generated if vcpkg is asked to install `d` or `e`. +* `--overlay-ports=y`: There are two ports in this overlay, `c` and `d`. Their names are derived from the subdirectories of `y`, and the names declared in their `vcpkg.json` must match, or an error will be generated if vcpkg is asked to consider `c` or `d`. -You can add to overlay port configuration in several ways: +You can add to the overlay port configuration in several ways: -* Command-line: Add one or more `--overlay-port-dirs=` or `--overlay-ports=` options to the command-line. -* [Manifest](../reference/vcpkg-configuration-json.md#overlay-ports): Populate the `"overlay-port-dirs"` or `"overlay-ports"` arrays in `vcpkg-configuration.json`. -* [Environmental variable](../users/config-environment.md#vcpkg_overlay_ports): Set `VCPKG_OVERLAY_PORT_DIRS` or `VCPKG_OVERLAY_PORTS` to a path character delimited list. +* Command-line: Add one or more `--overlay-ports=` options to the command-line. +* [Manifest](../reference/vcpkg-configuration-json.md#overlay-ports): Populate the `"overlay-ports"` array in `vcpkg-configuration.json`. +* [Environmental variable](../users/config-environment.md#vcpkg_overlay_ports): Set `VCPKG_OVERLAY_PORTS` to a path character delimited list. ### Example: Overlay Ports Example diff --git a/vcpkg/concepts/package-name-resolution.md b/vcpkg/concepts/package-name-resolution.md index 995041c7..8ffcdfda 100644 --- a/vcpkg/concepts/package-name-resolution.md +++ b/vcpkg/concepts/package-name-resolution.md @@ -198,21 +198,14 @@ registry. Overlay ports are a way to extend vcpkg with additional ports without creating a full registry. Overlays are considered before any registry lookups, or versioning considerations. Overlays replace any builtin triplets or ports. See [overlay ports](../concepts/overlay-ports.md) to learn more. -Overlay triplets are evaluated in this order: +Overlay ports are evaluated in this order: -1. Overlays from the [command line](../commands/common-options.md#overlay-port-dirs) `--overlay-port-dirs` +1. Overlays from the [command line](../commands/common-options.md#overlay-ports) `--overlay-ports` in the order passed; then 2. Overlays from - [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md#overlay-port-dirs) `"overlay-port-dirs"` - in order; then -3. Overlays from the `VCPKG_OVERLAY_PORT-DIRS` [environment - variable](../users/config-environment.md#vcpkg_overlay_port_dirs) in order. -4. Overlays from the [command line](../commands/common-options.md#overlay-ports) `--overlay-ports` - in the order passed; then -5. Overlays from [`vcpkg-configuration.json`](../reference/vcpkg-configuration-json.md#overlay-ports) `"overlay-ports"` in order; then -6. Overlays from the `VCPKG_OVERLAY_PORTS` [environment +3. Overlays from the `VCPKG_OVERLAY_PORTS` [environment variable](../users/config-environment.md#vcpkg_overlay_ports) in order. ## Overlay triplets diff --git a/vcpkg/get_started/get-started-packaging.md b/vcpkg/get_started/get-started-packaging.md index 43c8e535..0b8c1ea6 100644 --- a/vcpkg/get_started/get-started-packaging.md +++ b/vcpkg/get_started/get-started-packaging.md @@ -212,7 +212,7 @@ For more information, refer to the [maintainer guide](../contributing/maintainer Run: ```console -vcpkg install vcpkg-sample-library --overlay-port-dirs=C:\path\to\custom-overlay +vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay ``` You will get a long error message. Scan the output until you find: @@ -229,7 +229,7 @@ and replace the `SHA512` value in the `portfile.cmake` with its value. Re-run the install command: ```console -vcpkg install vcpkg-sample-library --overlay-port-dirs=C:\path\to\custom-overlay +vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay ``` ```console diff --git a/vcpkg/produce/test-registry-ports-ado.md b/vcpkg/produce/test-registry-ports-ado.md index 7a4d713c..aa79d38d 100644 --- a/vcpkg/produce/test-registry-ports-ado.md +++ b/vcpkg/produce/test-registry-ports-ado.md @@ -228,7 +228,7 @@ ports currently in the working directory as opposed to the versions published in your repository. To that goal, you need to add your registry's ports as [overlay -ports](../concepts/overlay-ports.md) by setting the `VCPKG_OVERLAY_PORT_DIRS` +ports](../concepts/overlay-ports.md) by setting the `VCPKG_OVERLAY_PORTS` environment variable to your registry's `ports` directory. The snippet below shows how to set up your registry's ports as overlay ports and diff --git a/vcpkg/produce/test-registry-ports-gha.md b/vcpkg/produce/test-registry-ports-gha.md index 2043afa3..6ade76bb 100644 --- a/vcpkg/produce/test-registry-ports-gha.md +++ b/vcpkg/produce/test-registry-ports-gha.md @@ -207,7 +207,7 @@ ports currently in the working directory as opposed to the versions published in your repository. To that goal, you need to add your registry's ports as [overlay -ports](../concepts/overlay-ports.md) by setting the `VCPKG_OVERLAY_PORT_DIRS` +ports](../concepts/overlay-ports.md) by setting the `VCPKG_OVERLAY_PORTS` environment variable to your registry's `ports` directory. The snippet below shows how to set up your registry's ports as overlay ports and diff --git a/vcpkg/reference/vcpkg-configuration-json.md b/vcpkg/reference/vcpkg-configuration-json.md index b5929677..4b9ea3c9 100644 --- a/vcpkg/reference/vcpkg-configuration-json.md +++ b/vcpkg/reference/vcpkg-configuration-json.md @@ -43,11 +43,9 @@ The latest JSON Schema is available at [https://raw.githubusercontent.com/micros "packages": [ "beicode", "beison" ] } ], - "overlay-ports-dirs": [ - "./team-ports" - ], "overlay-ports": [ - "./custom-ports/zlib" + "./team-ports", + "./custom-ports" ], "overlay-triplets": [ "./my-triplets" ] } @@ -62,7 +60,6 @@ The example also configures custom overlays for ports and triplets that are pres | Name | Type | Description | |------|--------|-------------| | [default-registry](#default-registry) | [Registry][] or null | Registry used for all ports without a specific registry | -| [overlay-port-dirs](#overlay-port-dirs) | string[] | List of paths to use as overlay port directories | | [overlay-ports](#overlay-ports) | string[] | List of paths to use as overlay port locations | | [overlay-triplets](#overlay-triplets) | string[] | List of paths to use as overlay triplets | | [registries](#registries) | [Registry][][] | Additional registries to use for subsets of ports | @@ -77,14 +74,6 @@ Ports that do not match any [`"packages"`](#registry-packages) pattern are resol Additional registries to use for specific ports. An array of [Registries](#registry). Optional. -### `"overlay-port-dirs"` - -A list of port overlay directories. An array of strings. Optional. - -Each path in the array must name a directory containing port directories named after the ports (`zlib`'s `vcpkg.json` must be at `zlib/vcpkg.json`). - -Relative paths are resolved relative to the `vcpkg-configuration.json` file. Absolute paths can be used but are discouraged. - ### `"overlay-ports"` A list of port overlay paths. An array of strings. Optional. diff --git a/vcpkg/reference/vcpkg-json.md b/vcpkg/reference/vcpkg-json.md index 10371487..922facc5 100644 --- a/vcpkg/reference/vcpkg-json.md +++ b/vcpkg/reference/vcpkg-json.md @@ -285,8 +285,9 @@ Having a `vcpkg-configuration` defined in `vcpkg.json` while also having a `vcpk "packages": [ "beicode", "beison" ] } ], - "overlay-port-dirs": [ "./team-ports" ], - "overlay-ports": [ "./my-ports/fmt" ] + "overlay-ports": [ "./my-ports/fmt", + "./team-ports" + ] } ``` diff --git a/vcpkg/users/buildsystems/cmake-integration.md b/vcpkg/users/buildsystems/cmake-integration.md index 0c4335b7..d68eff9e 100644 --- a/vcpkg/users/buildsystems/cmake-integration.md +++ b/vcpkg/users/buildsystems/cmake-integration.md @@ -188,10 +188,6 @@ In manifest mode, vcpkg will be automatically bootstrapped if the executable doe This variable can be set to a list of paths to be passed on the command line as `--overlay-triplets=...` -### `VCPKG_OVERLAY_PORT_DIRS` - -This variable can be set to a list of paths to be passed on the command line as `--overlay-port-dirs=...` - ### `VCPKG_OVERLAY_PORTS` This variable can be set to a list of paths to be passed on the command line as `--overlay-ports=...` diff --git a/vcpkg/users/config-environment.md b/vcpkg/users/config-environment.md index 216456ed..46e1a936 100644 --- a/vcpkg/users/config-environment.md +++ b/vcpkg/users/config-environment.md @@ -43,17 +43,12 @@ This environment variable can be set to a triplet name which will be used for un This environment variable can be set to a triplet name which will be used for unqualified host port references in command lines and all host port references in dependency lists. See [the host-dependencies documentation](host-dependencies.md) for more information. -## VCPKG_OVERLAY_PORT_DIRS - -This environment variable adds additional [overlay port directories](registries.md#overlays) considered after those listed on the command line. Multiple directories are separated with the platform dependent PATH separator (Windows `;` | others `:`) - -Example (Windows): `C:\custom-ports;C:\other-ports` - ## VCPKG_OVERLAY_PORTS This environment variable adds additional [overlay ports or overlay port directories](registries.md#overlays) considered after those listed on the command line. Multiple values are separated with the platform dependent PATH separator (Windows `;` | others `:`) -Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3` + +Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3;C:\other-ports` ## VCPKG_OVERLAY_TRIPLETS From 73caad9ce75285d0e5eb549de38b163ede7aeb6c Mon Sep 17 00:00:00 2001 From: Billy Robert O'Neal III Date: Tue, 12 Nov 2024 17:39:16 -0800 Subject: [PATCH 4/6] Missed one --- vcpkg/commands/common-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vcpkg/commands/common-options.md b/vcpkg/commands/common-options.md index eb33eae1..e7a71c18 100644 --- a/vcpkg/commands/common-options.md +++ b/vcpkg/commands/common-options.md @@ -113,7 +113,7 @@ Defaults to searching upwards from the current working directory for the nearest Specifies a directory either an [overlay port](../concepts/package-name-resolution.md#overlays), or subdirectories that are themselves overlay-ports. If `` contains a `CONTROL` or `vcpkg.json`, subdirectories are not considered. -This option can be specified multiple times; ports will resolve to the first match. `--overlay-port-dirs` will be considered first. +This option can be specified multiple times; ports will resolve to the first match. ### `--overlay-triplets=` From 696292217ac2c3d82436674d9a3f5725426f0c20 Mon Sep 17 00:00:00 2001 From: Billy Robert O'Neal III Date: Wed, 13 Nov 2024 13:55:37 -0800 Subject: [PATCH 5/6] Partially apply suggestion from @Neumann-A --- vcpkg/commands/common-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vcpkg/commands/common-options.md b/vcpkg/commands/common-options.md index e7a71c18..c401a857 100644 --- a/vcpkg/commands/common-options.md +++ b/vcpkg/commands/common-options.md @@ -111,7 +111,7 @@ Defaults to searching upwards from the current working directory for the nearest ### `--overlay-ports=` -Specifies a directory either an [overlay port](../concepts/package-name-resolution.md#overlays), or subdirectories that are themselves overlay-ports. If `` contains a `CONTROL` or `vcpkg.json`, subdirectories are not considered. +Specifies a directory either an [overlay port](../concepts/package-name-resolution.md#overlays), or subdirectories that are themselves overlay-ports. If `` is a directory containing a `CONTROL` or `vcpkg.json`, it is treated as a overlay port directory, and subdirectories will **not** be considered as additional overlay ports. This option can be specified multiple times; ports will resolve to the first match. From 6b6e78b33b996ab614073cb898ffc0e229482510 Mon Sep 17 00:00:00 2001 From: Victor Romero Date: Fri, 15 Nov 2024 01:18:26 -0800 Subject: [PATCH 6/6] Update vcpkg/commands/common-options.md --- vcpkg/commands/common-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vcpkg/commands/common-options.md b/vcpkg/commands/common-options.md index c401a857..ed752e1e 100644 --- a/vcpkg/commands/common-options.md +++ b/vcpkg/commands/common-options.md @@ -111,7 +111,7 @@ Defaults to searching upwards from the current working directory for the nearest ### `--overlay-ports=` -Specifies a directory either an [overlay port](../concepts/package-name-resolution.md#overlays), or subdirectories that are themselves overlay-ports. If `` is a directory containing a `CONTROL` or `vcpkg.json`, it is treated as a overlay port directory, and subdirectories will **not** be considered as additional overlay ports. +Specifies a directory either an [overlay port](../concepts/package-name-resolution.md#overlays), or subdirectories that are themselves overlay-ports. If `` is a directory containing a `CONTROL` or `vcpkg.json`, it is treated as an overlay port directory, and subdirectories will **not** be considered as additional overlay ports. This option can be specified multiple times; ports will resolve to the first match.