[vcpkg] add environment variable VCPKG_OVERLAY_PORTS (#12640)

* [vcpkg] add environment variable VCPKG_OVERLAY_PORTS

* add documentation for VCPKG_OVERLAY_PORTS

* append env overlay instead of prepending to give explicitly listed overlays priority

* fix formating (manually)

* manually fixing formating

* improve help text

Co-authored-by: ras0219 <533828+ras0219@users.noreply.github.com>

Co-authored-by: ras0219 <533828+ras0219@users.noreply.github.com>

3 files changed, 24 insertions, 1 deletions

diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md
index ffa988cbc..22f7ff84a 100644
--- a/docs/users/config-environment.md
+++ b/docs/users/config-environment.md
@@ -38,11 +38,19 @@ Example: `D:\2017`
 

 This environment variable can be set to a triplet name which will be used for unqualified triplet references in command lines.

 

+#### VCPKG_OVERLAY_PORTS

+

+This environment variable allows users to override ports with alternate versions according to the

+[ports overlay](../specifications/ports-overlay.md) specification. List paths to overlays using 

+the platform dependent PATH seperator (Windows `;` | others `:`) 

+

+Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3`

+

 #### VCPKG_FORCE_SYSTEM_BINARIES

 

 This environment variable, if set, suppresses the downloading of CMake and Ninja and forces the use of the system binaries.

 

-### VCPKG_KEEP_ENV_VARS

+#### VCPKG_KEEP_ENV_VARS

 

 This environment variable can be set to a list of environment variables, separated by `;`, which will be propagated to

 the build environment.

diff --git a/toolsrc/include/vcpkg/vcpkgcmdarguments.h b/toolsrc/include/vcpkg/vcpkgcmdarguments.h
index ddc407a35..82c4f6dc2 100644
--- a/toolsrc/include/vcpkg/vcpkgcmdarguments.h
+++ b/toolsrc/include/vcpkg/vcpkgcmdarguments.h
@@ -130,6 +130,7 @@ namespace vcpkg
         constexpr static StringLiteral TRIPLET_ENV = "VCPKG_DEFAULT_TRIPLET";
         constexpr static StringLiteral TRIPLET_ARG = "triplet";
         std::unique_ptr<std::string> triplet;
+        constexpr static StringLiteral OVERLAY_PORTS_ENV = "VCPKG_OVERLAY_PORTS";
         constexpr static StringLiteral OVERLAY_PORTS_ARG = "overlay-ports";
         std::vector<std::string> overlay_ports;
         constexpr static StringLiteral OVERLAY_TRIPLETS_ARG = "overlay-triplets";
diff --git a/toolsrc/src/vcpkg/vcpkgcmdarguments.cpp b/toolsrc/src/vcpkg/vcpkgcmdarguments.cpp
index 40782cc61..e1cc3e741 100644
--- a/toolsrc/src/vcpkg/vcpkgcmdarguments.cpp
+++ b/toolsrc/src/vcpkg/vcpkgcmdarguments.cpp
@@ -612,6 +612,7 @@ namespace vcpkg
         table.format(opt(TRIPLET_ARG, " ", "<t>"), "Specify the target architecture triplet. See 'vcpkg help triplet'");
         table.format("", "(default: " + format_environment_variable("VCPKG_DEFAULT_TRIPLET") + ')');
         table.format(opt(OVERLAY_PORTS_ARG, "=", "<path>"), "Specify directories to be used when searching for ports");
+        table.format("", "(also: " + format_environment_variable("VCPKG_OVERLAY_PORTS") + ')');
         table.format(opt(OVERLAY_TRIPLETS_ARG, "=", "<path>"), "Specify directories containing triplets files");
         table.format(opt(BINARY_SOURCES_ARG, "=", "<path>"),
                      "Add sources for binary caching. See 'vcpkg help binarycaching'");
@@ -646,6 +647,19 @@ namespace vcpkg
             }
         }
 
+        {
+            const auto vcpkg_overlay_ports_env = System::get_environment_variable(OVERLAY_PORTS_ENV);
+            if (const auto unpacked = vcpkg_overlay_ports_env.get())
+            {
+#ifdef WIN32
+                auto overlays = Strings::split(*unpacked, ';');
+#else
+                auto overlays = Strings::split(*unpacked, ':');
+#endif
+                overlay_ports.insert(std::end(overlay_ports), std::begin(overlays), std::end(overlays));
+            }
+        }
+
         if (!vcpkg_root_dir)
         {
             const auto vcpkg_root_env = System::get_environment_variable(VCPKG_ROOT_DIR_ENV);