[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

5 files changed, 70 insertions, 0 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)