Allow redirection of the downloads folder with an environment variable. (#4883)

* Add detection for VCPKG_DOWNLOADS environment variable in vcpkgpaths.cpp.

* Pass the downloads directory from VcpkgPaths to cmake.

* Also fixup bootstrap on *nix.

* Make error message a little prettier.

* Make that bash script actually work :)

* [vcpkg] Alter Optional<> usage style

* [vcpkg-docs] Add section on Environment Variables to the docs

5 files changed, 62 insertions, 24 deletions

diff --git a/docs/index.md b/docs/index.md
index 69dbdcd1e..cde241e92 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,8 +2,6 @@
 
 Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement are vital to its success!
 
-- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md)
-
 ### Examples
 
 - [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md)
@@ -15,6 +13,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 
 - [Integration with build systems](users/integration.md)
 - [Triplet files](users/triplets.md)
+- [Configuration and Environment](users/config-environment.md)
 
 ### Maintainer help
 
@@ -24,6 +23,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 ### Specifications
 
 - [Export](specifications/export-command.md)
+- [Feature Packages](specifications/feature-packages.md)
 
 ### Blog posts
 - [Announcing a single C++ library manager for Linux, macOS and Windows: Vcpkg](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/)
diff --git a/docs/users/triplets.md b/docs/users/triplets.md
index 9ff372aed..4f23c8e27 100644
--- a/docs/users/triplets.md
+++ b/docs/users/triplets.md
@@ -33,24 +33,6 @@ Valid options include any CMake system name, such as:
 - `Darwin` (Mac OSX)
 - `Linux` (Linux)
 
-### VCPKG_PLATFORM_TOOLSET
-Specifies the VS-based C/C++ compiler toolchain to use.
-
-This can be set to `v141`, `v140`, or left blank. If left blank, we select the latest compiler toolset available on your machine.
-
-Visual Studio 2015 platform toolset is `v140`  
-Visual Studio 2017 platform toolset is `v141`
-
-### VCPKG_VISUAL_STUDIO_PATH
-Specifies the Visual Studio installation to use.
-
-When unspecified, a Visual Studio instance is selected automatically, preferring Stable 2017, then Preview 2017, then 2015.
-
-The path should be absolute, formatted with backslashes, and have no trailing slash:
-```cmake
-set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Community")
-```
-
 ### VCPKG_CHAINLOAD_TOOLCHAIN_FILE
 Specifies an alternate CMake Toolchain file to use.
 
@@ -69,7 +51,28 @@ This option also has forms for configuration-specific and C flags:
 - `VCPKG_C_FLAGS_DEBUG`
 - `VCPKG_C_FLAGS_RELEASE`
 
-## macOS Variables
+## Windows Variables
+
+### VCPKG_PLATFORM_TOOLSET
+Specifies the VS-based C/C++ compiler toolchain to use.
+
+This can be set to `v141`, `v140`, or left blank. If left blank, we select the latest compiler toolset available on your machine.
+
+Visual Studio 2015 platform toolset is `v140`
+Visual Studio 2017 platform toolset is `v141`
+
+<a name="VCPKG_VISUAL_STUDIO_PATH"></a>
+### VCPKG_VISUAL_STUDIO_PATH
+Specifies the Visual Studio installation to use.
+
+When unspecified, a Visual Studio instance is selected automatically, preferring Stable 2017, then Preview 2017, then 2015.
+
+The path should be absolute, formatted with backslashes, and have no trailing slash:
+```cmake
+set(VCPKG_VISUAL_STUDIO_PATH "C:\\Program Files (x86)\\Microsoft Visual Studio\\Preview\\Community")
+```
+
+## MacOS Variables
 
 ### VCPKG_INSTALL_NAME_DIR
 Sets the install name used when building macOS dynamic libraries. Default value is `@rpath`. See the CMake documentation for [CMAKE_INSTALL_NAME_DIR](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_NAME_DIR.html) for more information.
diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
index a8b3d102b..5de0998c1 100644
--- a/scripts/bootstrap.sh
+++ b/scripts/bootstrap.sh
@@ -17,7 +17,16 @@ while [ "$vcpkgRootDir" != "/" ] && ! [ -e "$vcpkgRootDir/.vcpkg-root" ]; do
     vcpkgRootDir="$(dirname "$vcpkgRootDir")"
 done
 
-downloadsDir="$vcpkgRootDir/downloads"
+if [ -z ${VCPKG_DOWNLOADS+x} ]; then
+    downloadsDir="$vcpkgRootDir/downloads"
+else
+    downloadsDir="$VCPKG_DOWNLOADS"
+    if [ ! -d "$VCPKG_DOWNLOADS" ]; then
+        echo "VCPKG_DOWNLOADS was set to '$VCPKG_DOWNLOADS', but that was not a directory."
+        exit 1
+    fi
+
+fi
 
 extractStringBetweenDelimiters()
 {
diff --git a/toolsrc/src/vcpkg/build.cpp b/toolsrc/src/vcpkg/build.cpp
index 0e60fd50e..67d9b63ed 100644
--- a/toolsrc/src/vcpkg/build.cpp
+++ b/toolsrc/src/vcpkg/build.cpp
@@ -372,7 +372,8 @@ namespace vcpkg::Build
                 {"TARGET_TRIPLET", spec.triplet().canonical_name()},
                 {"VCPKG_PLATFORM_TOOLSET", toolset.version.c_str()},
                 {"VCPKG_USE_HEAD_VERSION",
-                 Util::Enum::to_bool(config.build_package_options.use_head_version) ? "1" : "0"},
+                Util::Enum::to_bool(config.build_package_options.use_head_version) ? "1" : "0"},
+                {"DOWNLOADS", paths.downloads},
                 {"_VCPKG_NO_DOWNLOADS", !Util::Enum::to_bool(config.build_package_options.allow_downloads) ? "1" : "0"},
                 {"_VCPKG_DOWNLOAD_TOOL", to_string(config.build_package_options.download_tool)},
                 {"GIT", git_exe_path},
diff --git a/toolsrc/src/vcpkg/vcpkgpaths.cpp b/toolsrc/src/vcpkg/vcpkgpaths.cpp
index 9a51818e8..a92a5673e 100644
--- a/toolsrc/src/vcpkg/vcpkgpaths.cpp
+++ b/toolsrc/src/vcpkg/vcpkgpaths.cpp
@@ -34,7 +34,32 @@ namespace vcpkg
 
         paths.packages = paths.root / "packages";
         paths.buildtrees = paths.root / "buildtrees";
-        paths.downloads = paths.root / "downloads";
+
+        const auto overriddenDownloadsPath = System::get_environment_variable("VCPKG_DOWNLOADS");
+        if (auto odp = overriddenDownloadsPath.get())
+        {
+            auto asPath = fs::u8path(*odp);
+            if (!fs::stdfs::is_directory(asPath))
+            {
+                Metrics::g_metrics.lock()->track_property("error", "Invalid VCPKG_DOWNLOADS override directory.");
+                Checks::exit_with_message(
+                    VCPKG_LINE_INFO,
+                    "Invalid downloads override directory: %s; "
+                    "create that directory or unset VCPKG_DOWNLOADS to use the default downloads location.",
+                    asPath.u8string());
+            }
+
+            paths.downloads = fs::stdfs::canonical(std::move(asPath), ec);
+            if (ec)
+            {
+                return ec;
+            }
+        }
+        else
+        {
+            paths.downloads = paths.root / "downloads";
+        }
+
         paths.ports = paths.root / "ports";
         paths.installed = paths.root / "installed";
         paths.triplets = paths.root / "triplets";