Download Mode (#7950)

* [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 * Fix calls to _execute_process() when not in Download Mode
2024-11-24 10:39:08 +08:00 · 2019-08-28 13:49:29 -07:00 · 2019-08-28 13:49:29 -07:00 · f5c732b40d
commit f5c732b40d
parent 2d60eea045
23 changed files with 182 additions and 78 deletions
--- a/docs/maintainers/execute_process.md
+++ 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)
--- 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)
--- a/docs/maintainers/vcpkg_common_definitions.md
+++ 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)
--- 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.

--- a/docs/maintainers/vcpkg_fail_port_install.md
+++ 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)
--- a/scripts/cmake/execute_process.cmake
+++ b/scripts/cmake/execute_process.cmake
@ -0,0 +1,20 @@
+## # 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)
+
+  if (DEFINED VCPKG_DOWNLOAD_MODE)
+    function(execute_process)
+      message(FATAL_ERROR "This command cannot be executed in Download Mode.\nHalting portfile execution.\n")
+    endfunction()
+  else()
+    function(execute_process)
+      _execute_process(${ARGV})
+    endfunction()
+  endif()
+endif()
--- 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}
      )
--- 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
--- 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)
--- 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
--- 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}
--- 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
--- 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
--- 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
--- 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
--- 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()
--- a/toolsrc/VERSION.txt
+++ b/toolsrc/VERSION.txt
@ -1 +1 @@
-"2019.08.23"
+"2019.08.27"
--- 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 = {
--- 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,13 +808,15 @@ 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.
+        // Skip this validation when running in Download Mode.
+        if (config.build_package_options.only_downloads != Build::OnlyDownloads::YES)
+        {
            Util::erase_remove_if(required_fspecs, [&](FeatureSpec const& fspec) {
                return status_db.is_installed(fspec) || fspec.name() == name;
            });
@ -808,6 +825,7 @@ namespace vcpkg::Build
            {
                return {BuildResult::CASCADED_DUE_TO_MISSING_DEPENDENCIES, std::move(required_fspecs)};
            }
+        }

        const PackageSpec spec =
            PackageSpec::from_name_and_triplet(config.scf.core_paragraph->name, triplet).value_or_exit(VCPKG_LINE_INFO);
@ -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);
        }
    }
--- 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,
--- 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,
--- 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,
--- 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,
        };