[vcpkg install] Enable Download Mode (#7797)

* [portfile functions] Override execute_process() to accept ALLOW_IN_DOWNLOAD_MODE option

* [vcpkg install] Set VCPKG_DOWNLOAD_MODE when using --only-downloads option

* [vcpkg_find_acquire_program] Allow in Download Mode

* Don't stop when build fails for a package

* Download sources for all packages in dependency graph

* Improve output messages

* Enable acquiring MSYS packages in download mode

* Documentation

* Update documentation

* execute_process() always fails on Download Mode

* Regenerate docs and fix formatting

* Run clang-format

* Use _execute_process on vcpkg_from_<source> helpers

23 files changed, 181 insertions, 78 deletions

diff --git a/docs/maintainers/execute_process.md b/docs/maintainers/execute_process.md
new file mode 100644
index 000000000..cbb339509
--- /dev/null
+++ b/docs/maintainers/execute_process.md
@@ -0,0 +1,10 @@
+# execute_process
+
+Intercepts all calls to execute_process() inside portfiles and fails when Download Mode
+is enabled.
+
+In order to execute a process in Download Mode call `_execute_process()` instead.
+
+
+## Source
+[scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index eadebf49a..bbd5d23ab 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -1,6 +1,7 @@
 <!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
 
 # Portfile helper functions

+- [execute\_process](execute_process.md)

 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)

 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)

 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md)

@@ -9,6 +10,7 @@
 - [vcpkg\_check\_features](vcpkg_check_features.md)

 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)

 - [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)

+- [vcpkg\_common\_definitions](vcpkg_common_definitions.md)

 - [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)

 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)

 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)

@@ -17,6 +19,7 @@
 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)

 - [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)

 - [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)

+- [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md)

 - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)

 - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)

 - [vcpkg\_from\_git](vcpkg_from_git.md)

diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md
new file mode 100644
index 000000000..3bb922b17
--- /dev/null
+++ b/docs/maintainers/vcpkg_common_definitions.md
@@ -0,0 +1,19 @@
+# vcpkg_common_definitions
+
+File contains helpful variabls for portfiles which are commonly needed or used.
+
+## The following variables are available:
+```cmake
+VCPKG_TARGET_IS_<target>                 with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD. only defined if <target>
+VCPKG_TARGET_STATIC_LIBRARY_PREFIX       static library prefix for target (same as CMAKE_STATIC_LIBRARY_PREFIX)
+VCPKG_TARGET_STATIC_LIBRARY_SUFFIX       static library suffix for target (same as CMAKE_STATIC_LIBRARY_SUFFIX)
+VCPKG_TARGET_SHARED_LIBRARY_PREFIX       shared library prefix for target (same as CMAKE_SHARED_LIBRARY_PREFIX)
+VCPKG_TARGET_SHARED_LIBRARY_SUFFIX       shared library suffix for target (same as CMAKE_SHARED_LIBRARY_SUFFIX)
+```
+
+CMAKE_STATIC_LIBRARY_PREFIX, CMAKE_STATIC_LIBRARY_SUFFIX, CMAKE_SHARED_LIBRARY_PREFIX, CMAKE_SHARED_LIBRARY_SUFFIX are defined for the target so that 
+portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports. 
+
+
+## Source
+[scripts/cmake/vcpkg_common_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)

diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md
index 4b1a7e081..26a116782 100644
--- a/docs/maintainers/vcpkg_execute_required_process.md
+++ b/docs/maintainers/vcpkg_execute_required_process.md
@@ -11,6 +11,10 @@ vcpkg_execute_required_process(
 )
 ```
 ## Parameters
+### ALLOW_IN_DOWNLOAD_MODE
+Allows the command to execute in Download Mode.  
+[See execute_process() override](../../scripts/cmake/execute_process.cmake).
+
 ### COMMAND
 The command to be executed, along with its arguments.
 
diff --git a/docs/maintainers/vcpkg_fail_port_install.md b/docs/maintainers/vcpkg_fail_port_install.md
new file mode 100644
index 000000000..b3b48ad5e
--- /dev/null
+++ b/docs/maintainers/vcpkg_fail_port_install.md
@@ -0,0 +1,34 @@
+# vcpkg_fail_port_install
+
+Fails the current portfile with a (default) error message
+
+## Usage
+```cmake
+vcpkg_fail_port_install([MESSAGE <message>] 	[ON_TARGET <target1> [<target2> ...]]
+```
+
+## Parameters
+### MESSAGE
+Additional failure message. If non is given a default message will be displayed depending on the failure condition
+
+### ALWAYS
+will always fail early
+
+### ON_TARGET
+targets for which the build should fail early. Valid targets are <target> from VCPKG_IS_TARGET_<target> (see vcpkg_common_definitions.cmake)
+
+### ON_ARCH
+architecture for which the build should fail early. 
+
+### ON_CRT_LINKAGE
+CRT linkage for which the build should fail early.
+
+### ON_LIBRARY_LINKAGE
+library linkage for which the build should fail early.
+
+## Examples
+
+* [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
+
+## Source
+[scripts/cmake/vcpkg_fail_port_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)

diff --git a/scripts/cmake/execute_process.cmake b/scripts/cmake/execute_process.cmake
new file mode 100644
index 000000000..90198e337
--- /dev/null
+++ b/scripts/cmake/execute_process.cmake
@@ -0,0 +1,19 @@
+## # execute_process

+##

+## Intercepts all calls to execute_process() inside portfiles and fails when Download Mode

+## is enabled.

+##

+## In order to execute a process in Download Mode call `_execute_process()` instead.

+##

+if (NOT DEFINED OVERRIDEN_EXECUTE_PROCESS)

+set(OVERRIDEN_EXECUTE_PROCESS ON)

+

+function(execute_process)

+        message(FATAL_ERROR 

+[[

+  This command cannot be executed in Download Mode.

+  Halting portfile execution.

+]])

+endfunction()

+

+endif()
\ No newline at end of file
diff --git a/scripts/cmake/vcpkg_acquire_msys.cmake b/scripts/cmake/vcpkg_acquire_msys.cmake
index 09090db68..f1f09dc7e 100644
--- a/scripts/cmake/vcpkg_acquire_msys.cmake
+++ b/scripts/cmake/vcpkg_acquire_msys.cmake
@@ -81,15 +81,15 @@ function(vcpkg_acquire_msys PATH_TO_ROOT_OUT)
 
     file(REMOVE_RECURSE ${TOOLPATH}/${TOOLSUBPATH})
     file(MAKE_DIRECTORY ${TOOLPATH})
-    execute_process(
+    _execute_process(
       COMMAND ${CMAKE_COMMAND} -E tar xzf ${ARCHIVE_PATH}
       WORKING_DIRECTORY ${TOOLPATH}
     )
-    execute_process(
+    _execute_process(
       COMMAND ${PATH_TO_ROOT}/usr/bin/bash.exe --noprofile --norc -c "PATH=/usr/bin;pacman-key --init;pacman-key --populate"
       WORKING_DIRECTORY ${TOOLPATH}
     )
-    execute_process(
+    _execute_process(
       COMMAND ${PATH_TO_ROOT}/usr/bin/bash.exe --noprofile --norc -c "PATH=/usr/bin;pacman -Syu --noconfirm"
       WORKING_DIRECTORY ${TOOLPATH}
     )
@@ -104,6 +104,7 @@ function(vcpkg_acquire_msys PATH_TO_ROOT_OUT)
     set(_ENV_ORIGINAL $ENV{PATH})
     set(ENV{PATH} ${PATH_TO_ROOT}/usr/bin)
     vcpkg_execute_required_process(
+      ALLOW_IN_DOWNLOAD_MODE
       COMMAND ${PATH_TO_ROOT}/usr/bin/bash.exe --noprofile --norc -c "pacman -Sy --noconfirm --needed ${_am_PACKAGES}"
       WORKING_DIRECTORY ${TOOLPATH}
       LOGNAME msys-pacman-${TARGET_TRIPLET}
@@ -116,6 +117,7 @@ function(vcpkg_acquire_msys PATH_TO_ROOT_OUT)
   # Deal with a stale process created by MSYS
   if (NOT VCPKG_CMAKE_SYSTEM_NAME OR VCPKG_CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
       vcpkg_execute_required_process(
+          ALLOW_IN_DOWNLOAD_MODE
           COMMAND TASKKILL /F /IM gpg-agent.exe /fi "memusage gt 2"
           WORKING_DIRECTORY ${SOURCE_PATH}
       )
diff --git a/scripts/cmake/vcpkg_apply_patches.cmake b/scripts/cmake/vcpkg_apply_patches.cmake
index ac0b78e20..9698917de 100644
--- a/scripts/cmake/vcpkg_apply_patches.cmake
+++ b/scripts/cmake/vcpkg_apply_patches.cmake
@@ -40,7 +40,7 @@ function(vcpkg_apply_patches)
         get_filename_component(ABSOLUTE_PATCH "${PATCH}" ABSOLUTE BASE_DIR "${CURRENT_PORT_DIR}")
         message(STATUS "Applying patch ${PATCH}")
         set(LOGNAME patch-${TARGET_TRIPLET}-${PATCHNUM})
-        execute_process(
+        _execute_process(
             COMMAND ${GIT} --work-tree=. --git-dir=.git apply "${ABSOLUTE_PATCH}" --ignore-whitespace --whitespace=nowarn --verbose
             OUTPUT_FILE ${CURRENT_BUILDTREES_DIR}/${LOGNAME}-out.log
             ERROR_FILE ${CURRENT_BUILDTREES_DIR}/${LOGNAME}-err.log
diff --git a/scripts/cmake/vcpkg_common_functions.cmake b/scripts/cmake/vcpkg_common_functions.cmake
index e9e52bad8..5f4155e9d 100644
--- a/scripts/cmake/vcpkg_common_functions.cmake
+++ b/scripts/cmake/vcpkg_common_functions.cmake
@@ -1,3 +1,4 @@
+include(execute_process)
 include(vcpkg_acquire_msys)
 include(vcpkg_add_to_path)
 include(vcpkg_check_features)
diff --git a/scripts/cmake/vcpkg_download_distfile.cmake b/scripts/cmake/vcpkg_download_distfile.cmake
index 72016b8c9..1fbff40e5 100644
--- a/scripts/cmake/vcpkg_download_distfile.cmake
+++ b/scripts/cmake/vcpkg_download_distfile.cmake
@@ -120,7 +120,7 @@ function(vcpkg_download_distfile VAR)
                     list(APPEND request_headers "--header=${header}")
                 endforeach()
             endif()
-            execute_process(
+            _execute_process(
                 COMMAND ${ARIA2} ${vcpkg_download_distfile_URLS}
                 -o temp/${vcpkg_download_distfile_FILENAME}
                 -l download-${vcpkg_download_distfile_FILENAME}-detailed.log
diff --git a/scripts/cmake/vcpkg_execute_required_process.cmake b/scripts/cmake/vcpkg_execute_required_process.cmake
index e65d1970a..f25a5b55e 100644
--- a/scripts/cmake/vcpkg_execute_required_process.cmake
+++ b/scripts/cmake/vcpkg_execute_required_process.cmake
@@ -11,6 +11,10 @@
 ## )
 ## ```
 ## ## Parameters
+## ### ALLOW_IN_DOWNLOAD_MODE
+## Allows the command to execute in Download Mode.  
+## [See execute_process() override](../../scripts/cmake/execute_process.cmake).
+##
 ## ### COMMAND
 ## The command to be executed, along with its arguments.
 ##
@@ -30,10 +34,20 @@
 ## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
 include(vcpkg_prettify_command)
 function(vcpkg_execute_required_process)
-    cmake_parse_arguments(vcpkg_execute_required_process "" "WORKING_DIRECTORY;LOGNAME" "COMMAND" ${ARGN})
+    cmake_parse_arguments(vcpkg_execute_required_process "ALLOW_IN_DOWNLOAD_MODE" "WORKING_DIRECTORY;LOGNAME" "COMMAND" ${ARGN})
     set(LOG_OUT "${CURRENT_BUILDTREES_DIR}/${vcpkg_execute_required_process_LOGNAME}-out.log")
     set(LOG_ERR "${CURRENT_BUILDTREES_DIR}/${vcpkg_execute_required_process_LOGNAME}-err.log")
-    execute_process(
+
+    set(execute_process_function execute_process)
+    if (DEFINED VCPKG_DOWNLOAD_MODE AND NOT vcpkg_execute_required_process_ALLOW_IN_DOWNLOAD_MODE)
+        message(FATAL_ERROR 
+[[
+This command cannot be executed in Download Mode.
+Halting portfile execution.
+]])
+    endif()
+
+    _execute_process(
         COMMAND ${vcpkg_execute_required_process_COMMAND}
         OUTPUT_FILE ${LOG_OUT}
         ERROR_FILE ${LOG_ERR}
diff --git a/scripts/cmake/vcpkg_extract_source_archive.cmake b/scripts/cmake/vcpkg_extract_source_archive.cmake
index a55419b19..fbae94b55 100644
--- a/scripts/cmake/vcpkg_extract_source_archive.cmake
+++ b/scripts/cmake/vcpkg_extract_source_archive.cmake
@@ -41,6 +41,7 @@ function(vcpkg_extract_source_archive ARCHIVE)
         message(STATUS "Extracting source ${ARCHIVE}")
         file(MAKE_DIRECTORY ${WORKING_DIRECTORY})
         vcpkg_execute_required_process(
+            ALLOW_IN_DOWNLOAD_MODE
             COMMAND ${CMAKE_COMMAND} -E tar xjf ${ARCHIVE}
             WORKING_DIRECTORY ${WORKING_DIRECTORY}
             LOGNAME extract
diff --git a/scripts/cmake/vcpkg_find_acquire_program.cmake b/scripts/cmake/vcpkg_find_acquire_program.cmake
index fed016c7b..aa8a70026 100644
--- a/scripts/cmake/vcpkg_find_acquire_program.cmake
+++ b/scripts/cmake/vcpkg_find_acquire_program.cmake
@@ -302,12 +302,12 @@ function(vcpkg_find_acquire_program VAR)
       if(ARCHIVE_EXTENSION STREQUAL ".msi")
         file(TO_NATIVE_PATH "${ARCHIVE_PATH}" ARCHIVE_NATIVE_PATH)
         file(TO_NATIVE_PATH "${PROG_PATH_SUBDIR}" DESTINATION_NATIVE_PATH)
-        execute_process(
+        _execute_process(
           COMMAND msiexec /a ${ARCHIVE_NATIVE_PATH} /qn TARGETDIR=${DESTINATION_NATIVE_PATH}
           WORKING_DIRECTORY ${DOWNLOADS}
         )
       else()
-        execute_process(
+        _execute_process(
           COMMAND ${CMAKE_COMMAND} -E tar xzf ${ARCHIVE_PATH}
           WORKING_DIRECTORY ${PROG_PATH_SUBDIR}
         )
@@ -316,6 +316,7 @@ function(vcpkg_find_acquire_program VAR)
 
     if(DEFINED POST_INSTALL_COMMAND)
       vcpkg_execute_required_process(
+        ALLOW_IN_DOWNLOAD_MODE
         COMMAND ${POST_INSTALL_COMMAND}
         WORKING_DIRECTORY ${PROG_PATH_SUBDIR}
         LOGNAME ${VAR}-tool-post-install
diff --git a/scripts/cmake/vcpkg_from_git.cmake b/scripts/cmake/vcpkg_from_git.cmake
index 0db818f80..bad5384ca 100644
--- a/scripts/cmake/vcpkg_from_git.cmake
+++ b/scripts/cmake/vcpkg_from_git.cmake
@@ -74,16 +74,18 @@ function(vcpkg_from_git)
     find_program(GIT NAMES git git.cmd)
     # Note: git init is safe to run multiple times
     vcpkg_execute_required_process(
+      ALLOW_IN_DOWNLOAD_MODE
       COMMAND ${GIT} init git-tmp
       WORKING_DIRECTORY ${DOWNLOADS}
       LOGNAME git-init-${TARGET_TRIPLET}
     )
     vcpkg_execute_required_process(
+      ALLOW_IN_DOWNLOAD_MODE
       COMMAND ${GIT} fetch ${_vdud_URL} ${_vdud_REF} --depth 1 -n
       WORKING_DIRECTORY ${DOWNLOADS}/git-tmp
       LOGNAME git-fetch-${TARGET_TRIPLET}
     )
-    execute_process(
+    _execute_process(
       COMMAND ${GIT} rev-parse FETCH_HEAD
       OUTPUT_VARIABLE REV_PARSE_HEAD
       ERROR_VARIABLE REV_PARSE_HEAD
@@ -100,6 +102,7 @@ function(vcpkg_from_git)
 
     file(MAKE_DIRECTORY "${DOWNLOADS}/temp")
     vcpkg_execute_required_process(
+      ALLOW_IN_DOWNLOAD_MODE
       COMMAND ${GIT} archive FETCH_HEAD -o "${TEMP_ARCHIVE}"
       WORKING_DIRECTORY ${DOWNLOADS}/git-tmp
       LOGNAME git-archive
diff --git a/scripts/cmake/vcpkg_from_gitlab.cmake b/scripts/cmake/vcpkg_from_gitlab.cmake
index 6bbe81ed6..05253289e 100644
--- a/scripts/cmake/vcpkg_from_gitlab.cmake
+++ b/scripts/cmake/vcpkg_from_gitlab.cmake
@@ -150,7 +150,7 @@ function(vcpkg_from_gitlab)
     endif()
 
     # There are issues with the Gitlab API project paths being URL-escaped, so we use git here to get the head revision
-    execute_process(COMMAND ${GIT} ls-remote
+    _execute_process(COMMAND ${GIT} ls-remote
         "${_vdud_GITLAB_URL}/${ORG_NAME}/${REPO_NAME}.git" "${_vdud_HEAD_REF}"
         RESULT_VARIABLE _git_result
         OUTPUT_VARIABLE _git_output
diff --git a/scripts/cmake/vcpkg_test_cmake.cmake b/scripts/cmake/vcpkg_test_cmake.cmake
index 20343bf64..eeb27867c 100644
--- a/scripts/cmake/vcpkg_test_cmake.cmake
+++ b/scripts/cmake/vcpkg_test_cmake.cmake
@@ -21,59 +21,4 @@ function(vcpkg_test_cmake)
   #   2. Select a generator in the same method as vcpkg_configure_cmake() as though the PREFER_NINJA flag was always passed.
   #   3. Fully emulate the toolchain file for the just-built package (just adding it to CMAKE_PREFIX_PATH is not enough).
   return()
-
-  cmake_parse_arguments(_tc "MODULE" "PACKAGE_NAME" "" ${ARGN})
-
-  if(NOT DEFINED _tc_PACKAGE_NAME)
-    message(FATAL_ERROR "PACKAGE_NAME must be specified")
-  endif()
-  if(_tc_MODULE)
-    set(PACKAGE_TYPE MODULE)
-  else()
-    set(PACKAGE_TYPE CONFIG)
-  endif()
-
-  if(VCPKG_PLATFORM_TOOLSET STREQUAL "v142")
-    message(STATUS "Skipping CMake integration test due to v142 / CMake interaction issues")
-    return()
-  endif()
-
-  message(STATUS "Performing CMake integration test")
-  file(REMOVE_RECURSE ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-test)
-  file(MAKE_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-test)
-
-  #Generate Dummy source
-#    set(VCPKG_TEST_SOURCE ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-test/CMakeIntegration.cpp)
-#    file(WRITE  ${VCPKG_TEST_SOURCE} "int main() \{\n")
-#    file(APPEND ${VCPKG_TEST_SOURCE} "return 0;}")
-  # Generate test source CMakeLists.txt
-  set(VCPKG_TEST_CMAKELIST ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-test/CMakeLists.txt)
-  file(WRITE  ${VCPKG_TEST_CMAKELIST} "cmake_minimum_required(VERSION 3.10)\n")
-  file(APPEND ${VCPKG_TEST_CMAKELIST} "set(CMAKE_PREFIX_PATH \"${CURRENT_PACKAGES_DIR};${CURRENT_INSTALLED_DIR}\")\n")
-  file(APPEND ${VCPKG_TEST_CMAKELIST} "\n")
-  file(APPEND ${VCPKG_TEST_CMAKELIST} "find_package(${_tc_PACKAGE_NAME} ${PACKAGE_TYPE} REQUIRED)\n")
-  #To properly test if the package is actually working haveway correctly we have to link all targets of a package to 
-  #a test executable and than actually build it. This will not discover if every symbol exported by the library is available/linked
-  #but it will doscover if all files which are linked by a target actual exist. Problem is: How to discover all targets?
-#    file(APPEND ${VCPKG_TEST_CMAKELIST} "add_executable(${_tc_PACKAGE_NAME}_exe ${VCPKG_TEST_SOURCE})\n")
-#    file(APPEND ${VCPKG_TEST_CMAKELIST} "target_link_libraries(${_tc_PACKAGE_NAME}_exe PRIVATE ${_tc_PACKAGE_NAME})\n")
-
-  if(DEFINED _VCPKG_CMAKE_GENERATOR)
-      set(VCPKG_CMAKE_TEST_GENERATOR "${_VCPKG_CMAKE_GENERATOR}")
-  else()
-      set(VCPKG_CMAKE_TEST_GENERATOR Ninja)
-  endif()
-
-  # Run cmake config with a generated CMakeLists.txt
-  set(LOGPREFIX "${CURRENT_BUILDTREES_DIR}/test-cmake-${TARGET_TRIPLET}")
-  execute_process(
-    COMMAND ${CMAKE_COMMAND} -G ${VCPKG_CMAKE_TEST_GENERATOR} .
-    OUTPUT_FILE "${LOGPREFIX}-out.log"
-    ERROR_FILE "${LOGPREFIX}-err.log"
-    RESULT_VARIABLE error_code
-    WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-test
-  )
-  if(error_code)
-    message(FATAL_ERROR "CMake integration test failed; unable to find_package(${_tc_PACKAGE_NAME} ${PACKAGE_TYPE} REQUIRED)")
-  endif()
 endfunction()
diff --git a/toolsrc/VERSION.txt b/toolsrc/VERSION.txt
index 66247baf7..2dc424b6c 100644
--- a/toolsrc/VERSION.txt
+++ b/toolsrc/VERSION.txt
@@ -1 +1 @@
-"2019.08.23"
+"2019.08.27"
diff --git a/toolsrc/include/vcpkg/build.h b/toolsrc/include/vcpkg/build.h
index 4f6397662..b535698dc 100644
--- a/toolsrc/include/vcpkg/build.h
+++ b/toolsrc/include/vcpkg/build.h
@@ -39,6 +39,12 @@ namespace vcpkg::Build
         YES
     };
 
+    enum class OnlyDownloads
+    {
+        NO = 0,
+        YES
+    };
+
     enum class CleanBuildtrees
     {
         NO = 0,
@@ -86,6 +92,7 @@ namespace vcpkg::Build
     {
         UseHeadVersion use_head_version;
         AllowDownloads allow_downloads;
+        OnlyDownloads only_downloads;
         CleanBuildtrees clean_buildtrees;
         CleanPackages clean_packages;
         CleanDownloads clean_downloads;
@@ -103,6 +110,7 @@ namespace vcpkg::Build
         FILE_CONFLICTS,
         CASCADED_DUE_TO_MISSING_DEPENDENCIES,
         EXCLUDED,
+        DOWNLOADED
     };
 
     static constexpr std::array<BuildResult, 6> BUILD_RESULT_VALUES = {
diff --git a/toolsrc/src/vcpkg/build.cpp b/toolsrc/src/vcpkg/build.cpp
index 9245ddfbc..e5c00b929 100644
--- a/toolsrc/src/vcpkg/build.cpp
+++ b/toolsrc/src/vcpkg/build.cpp
@@ -53,6 +53,7 @@ namespace vcpkg::Build::Command
         const Build::BuildPackageOptions build_package_options{

             Build::UseHeadVersion::NO,

             Build::AllowDownloads::YES,

+            Build::OnlyDownloads::NO,

             Build::CleanBuildtrees::NO,

             Build::CleanPackages::NO,

             Build::CleanDownloads::NO,

@@ -407,6 +408,11 @@ namespace vcpkg::Build
             {"VCPKG_CONCURRENCY", std::to_string(get_concurrency())},

         };

 

+        if (Util::Enum::to_bool(config.build_package_options.only_downloads))

+        {

+            variables.push_back({"VCPKG_DOWNLOAD_MODE", "true"});

+        }

+

         if (!System::get_environment_variable("VCPKG_FORCE_SYSTEM_BINARIES").has_value())

         {

             variables.push_back({"GIT", git_exe_path});

@@ -528,6 +534,7 @@ namespace vcpkg::Build
                                                 const BuildPackageConfig& config)

     {

         auto& fs = paths.get_filesystem();

+

 #if defined(_WIN32)

         const fs::path& powershell_exe_path = paths.get_tool_exe("powershell-core");

         if (!fs.exists(powershell_exe_path.parent_path() / "powershell.exe"))

@@ -559,6 +566,14 @@ namespace vcpkg::Build
 #else

         const int return_code = System::cmd_execute_clean(command, env);

 #endif

+        // With the exception of empty packages, builds in "Download Mode" always result in failure.

+        if (config.build_package_options.only_downloads == Build::OnlyDownloads::YES)

+        {

+            // TODO: Capture executed command output and evaluate whether the failure was intended.

+            // If an unintended error occurs then return a BuildResult::DOWNLOAD_FAILURE status.

+            return BuildResult::DOWNLOADED;

+        }

+

         const auto buildtimeus = timer.microseconds();

         const auto spec_string = spec.to_string();

 

@@ -793,20 +808,23 @@ namespace vcpkg::Build
         const std::string& name = config.scf.core_paragraph->name;

 

         std::vector<FeatureSpec> required_fspecs = compute_required_feature_specs(config, status_db);

-        std::vector<FeatureSpec> required_fspecs_copy = required_fspecs;

 

         // extract out the actual package ids

         auto dep_pspecs = Util::fmap(required_fspecs, [](FeatureSpec const& fspec) { return fspec.spec(); });

         Util::sort_unique_erase(dep_pspecs);

 

         // Find all features that aren't installed. This mutates required_fspecs.

-        Util::erase_remove_if(required_fspecs, [&](FeatureSpec const& fspec) {

-            return status_db.is_installed(fspec) || fspec.name() == name;

-        });

-

-        if (!required_fspecs.empty())

+        // Skip this validation when running in Download Mode.

+        if (config.build_package_options.only_downloads != Build::OnlyDownloads::YES)

         {

-            return {BuildResult::CASCADED_DUE_TO_MISSING_DEPENDENCIES, std::move(required_fspecs)};

+            Util::erase_remove_if(required_fspecs, [&](FeatureSpec const& fspec) {

+                return status_db.is_installed(fspec) || fspec.name() == name;

+            });

+

+            if (!required_fspecs.empty())

+            {

+                return {BuildResult::CASCADED_DUE_TO_MISSING_DEPENDENCIES, std::move(required_fspecs)};

+            }

         }

 

         const PackageSpec spec =

@@ -817,7 +835,10 @@ namespace vcpkg::Build
         // dep_pspecs was not destroyed

         for (auto&& pspec : dep_pspecs)

         {

-            if (pspec == spec) continue;

+            if (pspec == spec || Util::Enum::to_bool(config.build_package_options.only_downloads))

+            {

+                continue;

+            }

             const auto status_it = status_db.find_installed(pspec);

             Checks::check_exit(VCPKG_LINE_INFO, status_it != status_db.end());

             dependency_abis.emplace_back(

@@ -949,6 +970,7 @@ namespace vcpkg::Build
         static const std::string POST_BUILD_CHECKS_FAILED_STRING = "POST_BUILD_CHECKS_FAILED";

         static const std::string CASCADED_DUE_TO_MISSING_DEPENDENCIES_STRING = "CASCADED_DUE_TO_MISSING_DEPENDENCIES";

         static const std::string EXCLUDED_STRING = "EXCLUDED";

+        static const std::string DOWNLOADED_STRING = "DOWNLOADED";

 

         switch (build_result)

         {

@@ -959,6 +981,7 @@ namespace vcpkg::Build
             case BuildResult::FILE_CONFLICTS: return FILE_CONFLICTS_STRING;

             case BuildResult::CASCADED_DUE_TO_MISSING_DEPENDENCIES: return CASCADED_DUE_TO_MISSING_DEPENDENCIES_STRING;

             case BuildResult::EXCLUDED: return EXCLUDED_STRING;

+            case BuildResult::DOWNLOADED: return DOWNLOADED_STRING;

             default: Checks::unreachable(VCPKG_LINE_INFO);

         }

     }

diff --git a/toolsrc/src/vcpkg/commands.ci.cpp b/toolsrc/src/vcpkg/commands.ci.cpp
index f0f162f5c..6e0a71adf 100644
--- a/toolsrc/src/vcpkg/commands.ci.cpp
+++ b/toolsrc/src/vcpkg/commands.ci.cpp
@@ -212,6 +212,7 @@ namespace vcpkg::Commands::CI
         const Build::BuildPackageOptions build_options = {
             Build::UseHeadVersion::NO,
             Build::AllowDownloads::YES,
+            Build::OnlyDownloads::NO,
             Build::CleanBuildtrees::YES,
             Build::CleanPackages::YES,
             Build::CleanDownloads::NO,
@@ -356,6 +357,7 @@ namespace vcpkg::Commands::CI
         const Build::BuildPackageOptions install_plan_options = {
             Build::UseHeadVersion::NO,
             Build::AllowDownloads::YES,
+            Build::OnlyDownloads::NO,
             Build::CleanBuildtrees::YES,
             Build::CleanPackages::YES,
             Build::CleanDownloads::NO,
diff --git a/toolsrc/src/vcpkg/commands.upgrade.cpp b/toolsrc/src/vcpkg/commands.upgrade.cpp
index 1e64b2eb6..b1dbf6194 100644
--- a/toolsrc/src/vcpkg/commands.upgrade.cpp
+++ b/toolsrc/src/vcpkg/commands.upgrade.cpp
@@ -154,6 +154,7 @@ namespace vcpkg::Commands::Upgrade
         const Build::BuildPackageOptions install_plan_options = {
             Build::UseHeadVersion::NO,
             Build::AllowDownloads::YES,
+            Build::OnlyDownloads::NO,
             Build::CleanBuildtrees::NO,
             Build::CleanPackages::NO,
             Build::CleanDownloads::NO,
diff --git a/toolsrc/src/vcpkg/export.cpp b/toolsrc/src/vcpkg/export.cpp
index 5ceb47adf..349d9aefd 100644
--- a/toolsrc/src/vcpkg/export.cpp
+++ b/toolsrc/src/vcpkg/export.cpp
@@ -73,6 +73,7 @@ namespace vcpkg::Export
         static constexpr Build::BuildPackageOptions BUILD_OPTIONS = {
             Build::UseHeadVersion::NO,
             Build::AllowDownloads::YES,
+            Build::OnlyDownloads::NO,
             Build::CleanBuildtrees::NO,
             Build::CleanPackages::NO,
             Build::CleanDownloads::NO,
diff --git a/toolsrc/src/vcpkg/install.cpp b/toolsrc/src/vcpkg/install.cpp
index 1812f1624..009965887 100644
--- a/toolsrc/src/vcpkg/install.cpp
+++ b/toolsrc/src/vcpkg/install.cpp
@@ -342,6 +342,13 @@ namespace vcpkg::Install
                 return Build::build_package(paths, build_config, status_db);
             }();
 
+            if (BuildResult::DOWNLOADED == result.code)
+            {
+                System::print2(
+                    System::Color::success, "Downloaded sources for package ", display_name_with_features, "\n");
+                return result;
+            }
+
             if (result.code != Build::BuildResult::SUCCEEDED)
             {
                 System::print2(System::Color::error, Build::create_error_message(result.code, action.spec), "\n");
@@ -467,16 +474,18 @@ namespace vcpkg::Install
     static constexpr StringLiteral OPTION_DRY_RUN = "--dry-run";
     static constexpr StringLiteral OPTION_USE_HEAD_VERSION = "--head";
     static constexpr StringLiteral OPTION_NO_DOWNLOADS = "--no-downloads";
+    static constexpr StringLiteral OPTION_ONLY_DOWNLOADS = "--only-downloads";
     static constexpr StringLiteral OPTION_RECURSE = "--recurse";
     static constexpr StringLiteral OPTION_KEEP_GOING = "--keep-going";
     static constexpr StringLiteral OPTION_XUNIT = "--x-xunit";
     static constexpr StringLiteral OPTION_USE_ARIA2 = "--x-use-aria2";
     static constexpr StringLiteral OPTION_CLEAN_AFTER_BUILD = "--clean-after-build";
 
-    static constexpr std::array<CommandSwitch, 7> INSTALL_SWITCHES = {{
+    static constexpr std::array<CommandSwitch, 8> INSTALL_SWITCHES = {{
         {OPTION_DRY_RUN, "Do not actually build or install"},
         {OPTION_USE_HEAD_VERSION, "Install the libraries on the command line using the latest upstream sources"},
         {OPTION_NO_DOWNLOADS, "Do not download new sources"},
+        {OPTION_ONLY_DOWNLOADS, "Download sources but don't build packages"},
         {OPTION_RECURSE, "Allow removal of packages as part of installation"},
         {OPTION_KEEP_GOING, "Continue installing packages on failure"},
         {OPTION_USE_ARIA2, "Use aria2 to perform download tasks"},
@@ -631,10 +640,12 @@ namespace vcpkg::Install
         const bool dry_run = Util::Sets::contains(options.switches, OPTION_DRY_RUN);
         const bool use_head_version = Util::Sets::contains(options.switches, (OPTION_USE_HEAD_VERSION));
         const bool no_downloads = Util::Sets::contains(options.switches, (OPTION_NO_DOWNLOADS));
+        const bool only_downloads = Util::Sets::contains(options.switches, (OPTION_ONLY_DOWNLOADS));
         const bool is_recursive = Util::Sets::contains(options.switches, (OPTION_RECURSE));
         const bool use_aria2 = Util::Sets::contains(options.switches, (OPTION_USE_ARIA2));
         const bool clean_after_build = Util::Sets::contains(options.switches, (OPTION_CLEAN_AFTER_BUILD));
-        const KeepGoing keep_going = to_keep_going(Util::Sets::contains(options.switches, OPTION_KEEP_GOING));
+        const KeepGoing keep_going =
+            to_keep_going(Util::Sets::contains(options.switches, OPTION_KEEP_GOING) || only_downloads);
 
         auto& fs = paths.get_filesystem();
 
@@ -647,11 +658,12 @@ namespace vcpkg::Install
         const Build::BuildPackageOptions install_plan_options = {
             Util::Enum::to_enum<Build::UseHeadVersion>(use_head_version),
             Util::Enum::to_enum<Build::AllowDownloads>(!no_downloads),
+            Util::Enum::to_enum<Build::OnlyDownloads>(only_downloads),
             clean_after_build ? Build::CleanBuildtrees::YES : Build::CleanBuildtrees::NO,
             clean_after_build ? Build::CleanPackages::YES : Build::CleanPackages::NO,
             clean_after_build ? Build::CleanDownloads::YES : Build::CleanDownloads::NO,
             download_tool,
-            GlobalState::g_binary_caching ? Build::BinaryCaching::YES : Build::BinaryCaching::NO,
+            (GlobalState::g_binary_caching && !only_downloads) ? Build::BinaryCaching::YES : Build::BinaryCaching::NO,
             Build::FailOnTombstone::NO,
         };