[vcpkg-download-distfile] Regenerate docs and enable SKIP_SHA512 only in unstable (head) mode

docs/maintainers/vcpkg_download_distfile.md

@@ -2,6 +2,8 @@
 
 Download and cache a file needed for this port.
 
+This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
+
 ## Usage
 ```cmake
 vcpkg_download_distfile(
@@ -26,12 +28,17 @@ The expected hash for the file.
 
 If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
 
+### SKIP_SHA512
+Skip SHA512 hash check for file.
+
+This switch is only valid when building with the `--head` command line flag.
+
 ## Notes
-The command [`vcpkg_from_github`](vcpkg_from_github.md) should be used instead of this for downloading the main archive for GitHub projects.
+The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
 
 ## Examples
 
-* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)
 * [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
 * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
 

scripts/cmake/vcpkg_download_distfile.cmake

@@ -2,6 +2,8 @@
 ##
 ## Download and cache a file needed for this port.
 ##
+## This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
+##
 ## ## Usage
 ## ```cmake
 ## vcpkg_download_distfile(
@@ -29,12 +31,14 @@
 ## ### SKIP_SHA512
 ## Skip SHA512 hash check for file.
 ##
+## This switch is only valid when building with the `--head` command line flag.
+##
 ## ## Notes
-## The command [`vcpkg_from_github`](vcpkg_from_github.md) should be used instead of this for downloading the main archive for GitHub projects.
+## The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects.
 ##
 ## ## Examples
 ##
-## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+## * [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake)
 ## * [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
 ## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
 function(vcpkg_download_distfile VAR)
@@ -49,8 +53,14 @@ function(vcpkg_download_distfile VAR)
     if(NOT DEFINED vcpkg_download_distfile_FILENAME)
         message(FATAL_ERROR "vcpkg_download_distfile requires a FILENAME argument.")
     endif()
-    if(NOT DEFINED vcpkg_download_distfile_SKIP_SHA512 AND NOT _VCPKG_INTERNAL_NO_HASH_CHECK AND NOT DEFINED vcpkg_download_distfile_SHA512)
+    if(vcpkg_download_distfile_SKIP_SHA512 AND NOT VCPKG_USE_HEAD_VERSION)
-        message(FATAL_ERROR "vcpkg_download_distfile requires a SHA512 argument.")
+        message(FATAL_ERROR "vcpkg_download_distfile only allows SKIP_SHA512 when building with --head")
+    endif()
+    if(NOT vcpkg_download_distfile_SKIP_SHA512 AND NOT DEFINED vcpkg_download_distfile_SHA512)
+        message(FATAL_ERROR "vcpkg_download_distfile requires a SHA512 argument. If you do not know the SHA512, add it as 'SHA512 0' and re-run this command.")
+    endif()
+    if(vcpkg_download_distfile_SKIP_SHA512 AND DEFINED vcpkg_download_distfile_SHA512)
+        message(FATAL_ERROR "vcpkg_download_distfile must not be passed both SHA512 and SKIP_SHA512.")
     endif()
 
     set(downloaded_file_path ${DOWNLOADS}/${vcpkg_download_distfile_FILENAME})
@@ -60,7 +70,12 @@ function(vcpkg_download_distfile VAR)
     file(MAKE_DIRECTORY "${DOWNLOADS}/temp")
 
     function(test_hash FILE_KIND CUSTOM_ERROR_ADVICE)
-        if (_VCPKG_INTERNAL_NO_HASH_CHECK)
+        if(_VCPKG_INTERNAL_NO_HASH_CHECK)
+            # When using the internal hash skip, do not output an explicit message.
+            return()
+        endif()
+        if(vcpkg_download_distfile_SKIP_SHA512)
+            message(STATUS "Skipping hash check for ${downloaded_file_path}.")
             return()
         endif()
 
@@ -79,9 +94,7 @@ function(vcpkg_download_distfile VAR)
 
     if(EXISTS ${downloaded_file_path})
         message(STATUS "Using cached ${downloaded_file_path}")
-        if(NOT DEFINED vcpkg_download_distfile_SKIP_SHA512)
         test_hash("cached file" "Please delete the file and retry if this file should be downloaded again.")
-        endif()
     else()
         if(_VCPKG_NO_DOWNLOADS)
             message(FATAL_ERROR "Downloads are disabled, but '${downloaded_file_path}' does not exist.")
@@ -109,9 +122,7 @@ function(vcpkg_download_distfile VAR)
             "    Failed to download file.\n"
             "    Add mirrors or submit an issue at https://github.com/Microsoft/vcpkg/issues\n")
         else()
-            if(NOT DEFINED vcpkg_download_distfile_SKIP_SHA512)
+            test_hash("downloaded file" "The file may have been corrupted in transit.")
-                test_hash("downloaded file" "The file may be corrupted.")
-            endif()
         endif()
     endif()
     set(${VAR} ${downloaded_file_path} PARENT_SCOPE)

scripts/cmake/vcpkg_from_github.cmake

@@ -137,7 +137,6 @@ function(vcpkg_from_github)
         endif()
 
         # Try to download the file and version information from github.
-        set(_VCPKG_INTERNAL_NO_HASH_CHECK "TRUE")
         vcpkg_download_distfile(ARCHIVE_VERSION
             URLS "https://api.github.com/repos/${ORG_NAME}/${REPO_NAME}/git/refs/heads/${_vdud_HEAD_REF}"
             FILENAME ${downloaded_file_name}.version
@@ -149,7 +148,6 @@ function(vcpkg_from_github)
             FILENAME ${downloaded_file_name}
             SKIP_SHA512
         )
-        set(_VCPKG_INTERNAL_NO_HASH_CHECK "FALSE")
     endif()
 
     vcpkg_extract_source_archive_ex(
@@ -164,7 +162,10 @@ function(vcpkg_from_github)
     string(REGEX REPLACE "\"sha\": \"([a-f0-9]+)\"" "\\1" _version ${x})
 
     # exports VCPKG_HEAD_VERSION to the caller. This will get picked up by ports.cmake after the build.
+    # When multiple vcpkg_from_github's are used after each other, only use the version from the first (hopefully the primary one).
+    if(NOT DEFINED VCPKG_HEAD_VERSION)
         set(VCPKG_HEAD_VERSION ${_version} PARENT_SCOPE)
+    endif()
 
     set_SOURCE_PATH(${CURRENT_BUILDTREES_DIR}/src/head ${SANITIZED_HEAD_REF})
 endfunction()