Add headers to vcpkg_download_distfile (#5640)

* Add headers to vcpkg_download_distfile

Allows headers to be appended when downloading a distribution. This allows for setting
authentication headers to download from a private repository.

* [scripts,docs] Regenerate docs for portfile functions

* [docs,scripts] Fix typo regressions

* [docs,scripts] Fix broken link

5 files changed, 31 insertions, 5 deletions

diff --git a/scripts/cmake/vcpkg_add_to_path.cmake b/scripts/cmake/vcpkg_add_to_path.cmake
index 6890dfe31..7ab08c88e 100644
--- a/scripts/cmake/vcpkg_add_to_path.cmake
+++ b/scripts/cmake/vcpkg_add_to_path.cmake
@@ -15,6 +15,12 @@
 ## Prepends the directory.

 ##

 ## The default is to append.

+##

+## ## Examples:

+## * [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75)

+## * [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)

+## * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)

+##

 function(vcpkg_add_to_path)

     if(NOT "${ARGC}" STREQUAL "1" AND NOT "${ARGC}" STREQUAL "2")

         message(FATAL_ERROR "vcpkg_add_to_path() only accepts 1 or 2 arguments.")

diff --git a/scripts/cmake/vcpkg_build_msbuild.cmake b/scripts/cmake/vcpkg_build_msbuild.cmake
index 7a65127f0..50432f8fa 100644
--- a/scripts/cmake/vcpkg_build_msbuild.cmake
+++ b/scripts/cmake/vcpkg_build_msbuild.cmake
@@ -1,6 +1,6 @@
 ## # vcpkg_build_msbuild
 ##
-## Build an msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
+## Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
 ##
 ## ## Usage
 ## ```cmake
diff --git a/scripts/cmake/vcpkg_download_distfile.cmake b/scripts/cmake/vcpkg_download_distfile.cmake
index 949036c88..72016b8c9 100644
--- a/scripts/cmake/vcpkg_download_distfile.cmake
+++ b/scripts/cmake/vcpkg_download_distfile.cmake
@@ -33,6 +33,11 @@
 ##
 ## This switch is only valid when building with the `--head` command line flag.
 ##
+## ### HEADERS
+## A list of headers to append to the download request. This can be used for authentication during a download.
+##
+## Headers should be specified as "<header-name>: <header-value>".
+##
 ## ## Notes
 ## The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
 ##
@@ -44,7 +49,7 @@
 function(vcpkg_download_distfile VAR)
     set(options SKIP_SHA512)
     set(oneValueArgs FILENAME SHA512)
-    set(multipleValuesArgs URLS)
+    set(multipleValuesArgs URLS HEADERS)
     cmake_parse_arguments(vcpkg_download_distfile "${options}" "${oneValueArgs}" "${multipleValuesArgs}" ${ARGN})
 
     if(NOT DEFINED vcpkg_download_distfile_URLS)
@@ -110,10 +115,16 @@ function(vcpkg_download_distfile VAR)
         if(_VCPKG_DOWNLOAD_TOOL STREQUAL "ARIA2" AND NOT SAMPLE_URL MATCHES "aria2")
             vcpkg_find_acquire_program("ARIA2")
             message(STATUS "Downloading ${vcpkg_download_distfile_FILENAME}...")
+            if(vcpkg_download_distfile_HEADERS)
+                foreach(header ${vcpkg_download_distfile_HEADERS})
+                    list(APPEND request_headers "--header=${header}")
+                endforeach()
+            endif()
             execute_process(
                 COMMAND ${ARIA2} ${vcpkg_download_distfile_URLS}
                 -o temp/${vcpkg_download_distfile_FILENAME}
                 -l download-${vcpkg_download_distfile_FILENAME}-detailed.log
+                ${request_headers}
                 OUTPUT_FILE download-${vcpkg_download_distfile_FILENAME}-out.log
                 ERROR_FILE download-${vcpkg_download_distfile_FILENAME}-err.log
                 RESULT_VARIABLE error_code
@@ -140,7 +151,12 @@ function(vcpkg_download_distfile VAR)
         else()
             foreach(url IN LISTS vcpkg_download_distfile_URLS)
                 message(STATUS "Downloading ${url}...")
-                file(DOWNLOAD ${url} "${download_file_path_part}" STATUS download_status)
+                if(vcpkg_download_distfile_HEADERS)
+                    foreach(header ${vcpkg_download_distfile_HEADERS})
+                        list(APPEND request_headers HTTPHEADER ${header})
+                    endforeach()
+                endif()
+                file(DOWNLOAD ${url} "${download_file_path_part}" STATUS download_status ${request_headers})
                 list(GET download_status 0 status_code)
                 if (NOT "${status_code}" STREQUAL "0")
                     message(STATUS "Downloading ${url}... Failed. Status: ${download_status}")
diff --git a/scripts/cmake/vcpkg_from_gitlab.cmake b/scripts/cmake/vcpkg_from_gitlab.cmake
index f13bc054c..6bbe81ed6 100644
--- a/scripts/cmake/vcpkg_from_gitlab.cmake
+++ b/scripts/cmake/vcpkg_from_gitlab.cmake
@@ -56,7 +56,11 @@
 ##
 ## This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 ##
-
+## ## Examples:
+## * [curl][https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake#L75]
+## * [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
+## * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
+##
 function(vcpkg_from_gitlab)
     set(oneValueArgs OUT_SOURCE_PATH GITLAB_URL USER REPO REF SHA512 HEAD_REF)
     set(multipleValuesArgs PATCHES)
diff --git a/scripts/cmake/vcpkg_install_msbuild.cmake b/scripts/cmake/vcpkg_install_msbuild.cmake
index 11bcdf189..92c84bf0b 100644
--- a/scripts/cmake/vcpkg_install_msbuild.cmake
+++ b/scripts/cmake/vcpkg_install_msbuild.cmake
@@ -1,6 +1,6 @@
 ## # vcpkg_install_msbuild
 ##
-## Build and install an msbuild-based project. This replaces `vcpkg_build_msbuild()`.
+## Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
 ##
 ## ## Usage
 ## ```cmake