[vcpkg] add environment variable VCPKG_OVERLAY_PORTS

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.

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";

toolsrc/src/vcpkg/vcpkgcmdarguments.cpp

@@ -611,6 +611,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'");
@@ -645,6 +646,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);