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

docs/maintainers/vcpkg_add_to_path.md

@@ -21,5 +21,6 @@ The default is to append.
 * [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)
 
+
 ## Source
-[scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)
+[scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)

docs/maintainers/vcpkg_download_distfile.md

@@ -33,6 +33,11 @@ Skip SHA512 hash check for file.
 
 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.
 

docs/maintainers/vcpkg_from_gitlab.md

@@ -57,8 +57,10 @@ At least one of `REF` and `HEAD_REF` must be specified, however it is preferable
 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)
 
-* [tiny-process-library](https://github.com/Microsoft/vcpkg/blob/master/ports/tiny-process-library/portfile.cmake#L3)
 
 ## Source
-[scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)
+[scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)

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.")

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

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}")

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)

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