[rollup:2021-07-06] Rollup PR (#18838)

* [rollup:2021-07-06 1/8] PR #18272 (@strega-nil)

[scripts-audit] vcpkg_from_*

* [rollup:2021-07-06 2/8] PR #18319 (@strega-nil)

[scripts-audit] add guidelines for cmake

* [rollup 2021-07-06 3/8] PR #18410 (@mheyman)

[vcpkg-cmake-config] documentation fix

* [rollup:2021-07-06 4/8] PR #18488 (@strega-nil)

[scripts-audit] vcpkg_execute_*

* [rollup:2021-07-06 5/8] PR #18517 (@strega-nil)

[scripts-audit] vcpkg_extract_source_archive

* [rollup:2021-07-06 6/8] PR #18674 (@NancyLi1013)

[vcpkg doc] Update examples

* [rollup:2021-07-06 7/8] PR #18695 (@JackBoosY)

[vcpkg] Update the minimum version of vcpkg

* [rollup:2021-07-06 8/8] PR #18758 (@ras0219-msft)

[vcpkg_from_git] Fix error if downloads folder does not exist

* build docs!

* fix bond:*-windows

* fix nmap

Co-authored-by: nicole mazzuca <mazzucan@outlook.com>
Co-authored-by: Michael Heyman <Michael.Heyman@jhuapl.edu>
Co-authored-by: NancyLi1013 <lirui09@beyondsoft.com>
Co-authored-by: JackBoosY <yuzaiyang@beyondsoft.com>
Co-authored-by: Robert Schumacher <ras0219@outlook.com>

1 files changed, 102 insertions, 90 deletions

diff --git a/scripts/cmake/vcpkg_from_git.cmake b/scripts/cmake/vcpkg_from_git.cmake
index d2055f82e..ac46e32cc 100644
--- a/scripts/cmake/vcpkg_from_git.cmake
+++ b/scripts/cmake/vcpkg_from_git.cmake
@@ -9,7 +9,7 @@ vcpkg_from_git(
     OUT_SOURCE_PATH <SOURCE_PATH>
     URL <https://android.googlesource.com/platform/external/fdlibm>
     REF <59f7335e4d...>
-    [TAG <v1.0.2>]
+    [HEAD_REF <ref>]
     [PATCHES <patch1.patch> <patch2.patch>...]
 )
 ```
@@ -26,17 +26,16 @@ The url of the git repository.
 ### REF
 The git sha of the commit to download.
 
-### TAG
-An optional git tag to be verified against the `REF`. If the remote repository's tag does not match the specified `REF`, the build will fail.
+### HEAD_REF
+The git branch to use when the package is requested to be built from the latest sources.
+
+Example: `main`, `develop`, `HEAD`
 
 ### PATCHES
 A list of patches to be applied to the extracted sources.
 
 Relative paths are based on the port directory.
 
-### X_OUT_REF (internal only)
-This parameter is used for automatic REF updates for certain ports in the central vcpkg catalog. It should not be used by any ports outside the central catalog and within the central catalog it should not be used on any user path. This parameter may change behavior incompatibly or be removed at any time.
-
 ## Notes:
 `OUT_SOURCE_PATH`, `REF`, and `URL` must be specified.
 
@@ -48,94 +47,107 @@ This parameter is used for automatic REF updates for certain ports in the centra
 include(vcpkg_execute_in_download_mode)
 
 function(vcpkg_from_git)
-  set(oneValueArgs OUT_SOURCE_PATH URL REF TAG X_OUT_REF)
-  set(multipleValuesArgs PATCHES)
-  # parse parameters such that semicolons in options arguments to COMMAND don't get erased
-  cmake_parse_arguments(PARSE_ARGV 0 _vdud "" "${oneValueArgs}" "${multipleValuesArgs}")
-
-  if(NOT DEFINED _vdud_OUT_SOURCE_PATH)
-    message(FATAL_ERROR "OUT_SOURCE_PATH must be specified.")
-  endif()
-
-  if(NOT DEFINED _vdud_URL)
-    message(FATAL_ERROR "The git url must be specified")
-  endif()
-
-  if(NOT DEFINED _vdud_REF)
-    message(FATAL_ERROR "The git ref must be specified.")
-  endif()
-
-  if(NOT DEFINED _vdud_TAG)
-    set(_vdud_TAG ${_vdud_REF})
-  endif()
-  
-  # using .tar.gz instead of .zip because the hash of the latter is affected by timezone.
-  string(REPLACE "/" "-" SANITIZED_REF "${_vdud_TAG}")
-  set(TEMP_ARCHIVE "${DOWNLOADS}/temp/${PORT}-${SANITIZED_REF}.tar.gz")
-  set(ARCHIVE "${DOWNLOADS}/${PORT}-${SANITIZED_REF}.tar.gz")
-  set(TEMP_SOURCE_PATH "${CURRENT_BUILDTREES_DIR}/src/${SANITIZED_REF}")
-
-  if(NOT EXISTS "${ARCHIVE}")
-    if(_VCPKG_NO_DOWNLOADS)
-        message(FATAL_ERROR "Downloads are disabled, but '${ARCHIVE}' does not exist.")
-    endif()
-    message(STATUS "Fetching ${_vdud_URL}...")
-    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_TAG} --depth 1 -n
-      WORKING_DIRECTORY ${DOWNLOADS}/git-tmp
-      LOGNAME git-fetch-${TARGET_TRIPLET}
+    cmake_parse_arguments(PARSE_ARGV 0 "arg"
+        ""
+        "OUT_SOURCE_PATH;URL;REF;HEAD_REF;TAG"
+        "PATCHES"
     )
-    vcpkg_execute_in_download_mode(
-      COMMAND ${GIT} rev-parse FETCH_HEAD
-      OUTPUT_VARIABLE REV_PARSE_HEAD
-      ERROR_VARIABLE REV_PARSE_HEAD
-      RESULT_VARIABLE error_code
-      WORKING_DIRECTORY ${DOWNLOADS}/git-tmp
-    )
-    if(error_code)
-        message(FATAL_ERROR "unable to determine FETCH_HEAD after fetching git repository")
+
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(WARNING "vcpkg_from_git was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+    if(DEFINED arg_TAG)
+        message(WARNING "The TAG argument to vcpkg_from_git has been deprecated and has no effect.")
     endif()
-    string(REGEX REPLACE "\n$" "" REV_PARSE_HEAD "${REV_PARSE_HEAD}")
-    if(NOT REV_PARSE_HEAD STREQUAL _vdud_REF AND NOT DEFINED _vdud_X_OUT_REF)
-        message(STATUS "[Expected : ( ${_vdud_REF} )]")
-        message(STATUS "[  Actual : ( ${REV_PARSE_HEAD} )]")
-        message(FATAL_ERROR "REF (${_vdud_REF}) does not match FETCH_HEAD (${REV_PARSE_HEAD})")
-    elseif(DEFINED _vdud_X_OUT_REF)
-        set(${_vdud_X_OUT_REF} ${REV_PARSE_HEAD} PARENT_SCOPE)
-        return()
+    
+
+    if(NOT DEFINED arg_OUT_SOURCE_PATH)
+        message(FATAL_ERROR "OUT_SOURCE_PATH must be specified.")
+    endif()
+    if(NOT DEFINED arg_URL)
+        message(FATAL_ERROR "The git url must be specified")
+    endif()
+    if(NOT DEFINED arg_REF AND NOT DEFINED arg_HEAD_REF)
+        message(FATAL_ERROR "At least one of REF or HEAD_REF must be specified.")
+    endif()
+
+    set(working_directory_param "")
+    set(ref_to_use "${arg_REF}")
+    if(VCPKG_USE_HEAD_VERSION)
+        if(DEFINED arg_HEAD_REF)
+            set(working_directory_param "WORKING_DIRECTORY" "${CURRENT_BUILDTREES_DIR}/src/head")
+            set(ref_to_use "${arg_HEAD_REF}")
+        else()
+            message(STATUS "Package does not specify HEAD_REF. Falling back to non-HEAD version.")
+        endif()
+    elseif(NOT DEFINED arg_REF)
+        message(FATAL_ERROR "Package does not specify REF. It must be built using --head.")
+    endif()
+
+    string(REPLACE "/" "_-" sanitized_ref "${ref_to_use}")
+    set(temp_archive "${DOWNLOADS}/temp/${PORT}-${sanitized_ref}.tar.gz")
+    set(archive "${DOWNLOADS}/${PORT}-${sanitized_ref}.tar.gz")
+
+    if(NOT EXISTS "${archive}")
+        if(_VCPKG_NO_DOWNLOADS)
+            message(FATAL_ERROR "Downloads are disabled, but '${archive}' does not exist.")
+        endif()
+        message(STATUS "Fetching ${arg_URL} ${ref_to_use}...")
+        find_program(GIT NAMES git git.cmd)
+        file(MAKE_DIRECTORY "${DOWNLOADS}")
+        # 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 "${arg_URL}" "${ref_to_use}" --depth 1 -n
+            WORKING_DIRECTORY "${DOWNLOADS}/git-tmp"
+            LOGNAME "git-fetch-${TARGET_TRIPLET}"
+        )
+        vcpkg_execute_in_download_mode(
+            COMMAND "${GIT}" rev-parse FETCH_HEAD
+            OUTPUT_VARIABLE rev_parse_head
+            ERROR_VARIABLE rev_parse_head
+            RESULT_VARIABLE error_code
+            WORKING_DIRECTORY "${DOWNLOADS}/git-tmp"
+        )
+        if(error_code)
+            message(FATAL_ERROR "unable to determine FETCH_HEAD after fetching git repository")
+        endif()
+        string(STRIP "${rev_parse_head}" rev_parse_head)
+        if(VCPKG_USE_HEAD_VERSION)
+            set(VCPKG_HEAD_VERSION "${rev_parse_head}" PARENT_SCOPE)
+        elseif(NOT rev_parse_head STREQUAL arg_REF)
+            message(FATAL_ERROR "REF (${arg_REF}) does not match FETCH_HEAD (${rev_parse_head})
+    [Expected : ( ${arg_REF} )])
+    [  Actual : ( ${rev_parse_head} )]"
+            )
+        endif()
+
+        file(MAKE_DIRECTORY "${DOWNLOADS}/temp")
+        vcpkg_execute_required_process(
+            ALLOW_IN_DOWNLOAD_MODE
+            COMMAND "${GIT}" archive "${rev_parse_head}" -o "${temp_archive}"
+            WORKING_DIRECTORY "${DOWNLOADS}/git-tmp"
+            LOGNAME git-archive
+        )
+        file(RENAME "${temp_archive}" "${archive}")
+    else()
+        message(STATUS "Using cached ${archive}")
     endif()
 
-    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
+    vcpkg_extract_source_archive_ex(
+        OUT_SOURCE_PATH SOURCE_PATH
+        ARCHIVE "${archive}"
+        REF "${sanitized_ref}"
+        PATCHES ${arg_PATCHES}
+        NO_REMOVE_ONE_LEVEL
+        ${working_directory_param}
     )
 
-    get_filename_component(downloaded_file_dir "${ARCHIVE}" DIRECTORY)
-    file(MAKE_DIRECTORY "${downloaded_file_dir}")
-    file(RENAME "${TEMP_ARCHIVE}" "${ARCHIVE}")
-  else()
-    message(STATUS "Using cached ${ARCHIVE}")
-  endif()
-
-  vcpkg_extract_source_archive_ex(
-    OUT_SOURCE_PATH SOURCE_PATH
-    ARCHIVE "${ARCHIVE}"
-    REF "${SANITIZED_REF}"
-    PATCHES ${_vdud_PATCHES}
-    NO_REMOVE_ONE_LEVEL
-  )
-
-  set(${_vdud_OUT_SOURCE_PATH} "${SOURCE_PATH}" PARENT_SCOPE)
+    set("${arg_OUT_SOURCE_PATH}" "${SOURCE_PATH}" PARENT_SCOPE)
 endfunction()