Clarify the behavior of overlay-ports. (#422)

Co-authored-by: Victor Romero <[email protected]>

vcpkg/commands/common-options.md

@@ -111,7 +111,7 @@ Defaults to searching upwards from the current working directory for the nearest
 
 ### <a name="overlay-ports"></a> `--overlay-ports=<path>`
 
-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 `<path>` 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.
 

vcpkg/commands/help.md

@@ -95,7 +95,8 @@ 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-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%)

vcpkg/concepts/overlay-ports.md

@@ -15,25 +15,40 @@ 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.
+* 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: `<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`.
+Valid ports contain `portfile.cmake`, and either `vcpkg.json` or `CONTROL`.
 
-You can add an overlay port in several ways:
+For example, consider the following directory structure:
 
-* Command-line: Add one or multiple `--overlay-ports=<directory>` 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
+* `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`.
+* `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`.
+
+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`. 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, `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 the overlay port configuration in several ways:
+
+* Command-line: Add one or more `--overlay-ports=<directory>` 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
 

vcpkg/concepts/package-name-resolution.md

@@ -194,19 +194,31 @@ Because exact matches are preferred over pattern matches,
 `qt-advanced-docking-system` and `qtkeychain` will resolve to the default
 registry.
 
-## <a name="overlays"></a> Overlays
+## <a name="overlays"></a><a name="overlay-ports"></a> 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 ports 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-ports) `--overlay-ports`
    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-ports) `"overlay-ports"`
    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_PORTS` [environment
+   variable](../users/config-environment.md#vcpkg_overlay_ports) in order.
+
+## <a name="overlay-triplets"></a> 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.
+

vcpkg/reference/vcpkg-configuration-json.md

@@ -60,7 +60,7 @@ 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-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 |
 
@@ -78,10 +78,10 @@ Additional registries to use for specific ports. An array of [Registries](#regis
 
 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.
 

vcpkg/users/config-environment.md

@@ -45,10 +45,10 @@ This environment variable can be set to a triplet name which will be used for un
 
 ## 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`
+
+Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3;C:\other-ports`
 
 ## VCPKG_OVERLAY_TRIPLETS