[rollup] 2021-07-26 (#19157)

* [rollup:2021-07-26 1/6] PR #18783 (@strega-nil)

[scripts-audit] vcpkg_copy_tools and friends

* [rollup:2021-07-26 2/6] PR #18898 (@dg0yt)

[vcpkg] Fix toolchain compatibility with cmake < 3.15

* [rollup:2021-07-26 3/6] PR #18980 (@strega-nil)

[cmake-guidelines] Minor update, for `if()`

* [rollup:2021-07-26 4/6] PR #18981 (@strega-nil)

[scripts-audit] vcpkg_check_linkage

* [rollup:2021-07-26 5/6] PR #19158 (@Hoikas)

[vcpkg.cmake] Fix variable case.

* [rollup:2021-07-26 6/6] PR #18839

[scripts-audit] z_vcpkg_get_cmake_vars

Co-authored-by: nicole mazzuca <mazzucan@outlook.com>

6 files changed, 130 insertions, 54 deletions

diff --git a/docs/maintainers/cmake-guidelines.md b/docs/maintainers/cmake-guidelines.md
index 77cdf7372..c0bd5b6a0 100644
--- a/docs/maintainers/cmake-guidelines.md
+++ b/docs/maintainers/cmake-guidelines.md
@@ -35,7 +35,7 @@ We hope that they will make both forwards and backwards compatibility easier.
   Always check for `ARGN` or `arg_UNPARSED_ARGUMENTS`.

   `FATAL_ERROR` when possible, `WARNING` if necessary for backwards compatibility.

 - All `cmake_parse_arguments` must use `PARSE_ARGV`.

-- All `foreach` loops must use `IN LISTS` and `IN ITEMS`.

+- All `foreach` loops must use `IN LISTS`, `IN ITEMS`, or `RANGE`.

 - The variables `${ARGV}` and `${ARGN}` are unreferenced,

   except in helpful messages to the user.

   - (i.e., `message(FATAL_ERROR "blah was passed extra arguments: ${ARGN}")`)

@@ -45,27 +45,68 @@ We hope that they will make both forwards and backwards compatibility easier.
   - Exception: `vcpkg.cmake`'s `find_package`.

 - Scripts in the scripts tree should not be expected to need observable changes

   as part of normal operation.

-  - Example violation: `vcpkg_acquire_msys()` has hard-coded packages and versions that need updating over time due to the MSYS project dropping old packages.

-  - Example exception: `vcpkg_from_sourceforge()` has a list of mirrors which needs maintenance but does not have an observable behavior impact on the callers.

-- All variable expansions are in quotes `""`,

-  except those which are intended to be passed as multiple arguments.

-  - Example:

-  ```cmake

-  set(working_directory "")

-  if(DEFINED arg_WORKING_DIRECTORY)

-    set(working_directory "WORKING_DIRECTORY" "${arg_WORKING_DIRECTORY}")

-  endif()

-  # calls do_the_thing() if NOT DEFINED arg_WORKING_DIRECTORY,

-  # else calls do_the_thing(WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")

-  do_the_thing(${working_directory})

-  ```

+  - Example violation: `vcpkg_acquire_msys()` has hard-coded packages and versions

+    that need updating over time due to the MSYS project dropping old packages.

+  - Example exception: `vcpkg_from_sourceforge()` has a list of mirrors which

+    needs maintenance, but does not have an observable behavior impact on the callers.

+- Rules for quoting: there are three kinds of arguments in CMake -

+  unquoted (`foo(BAR)`), quoted (`foo("BAR")`), and bracketed (`foo([[BAR]])`).

+  Follow these rules to quote correctly:

+  - If an argument contains a variable expansion `${...}`,

+    it must be quoted.

+    - Exception: a "splat" variable expansion, when one variable will be

+      passed to a function as multiple arguments. In this case, the argument

+      should simply be `${foo}`:

+      ```cmake

+      vcpkg_list(SET working_directory)

+      if(DEFINED "arg_WORKING_DIRECTORY")

+        vcpkg_list(SET working_directory WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")

+      endif()

+      # calls do_the_thing() if NOT DEFINED arg_WORKING_DIRECTORY,

+      # else calls do_the_thing(WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")

+      do_the_thing(${working_directory})

+      ```

+  - Otherwise, if the argument contains any escape sequences that are not

+    `\\`, `\"`, or `\$`, that argument must be a quoted argument.

+    - For example: `"foo\nbar"` must be quoted.

+  - Otherwise, if the argument contains a `\`, a `"`, or a `$`,

+    that argument should be bracketed.

+    - Example:

+      ```cmake

+      set(x [[foo\bar]])

+      set(y [=[foo([[bar\baz]])]=])

+      ```

+  - Otherwise, if the argument contains characters that are

+    not alphanumeric or `_`, that argument should be quoted.

+  - Otherwise, the argument should be unquoted.

+  - Exception: arguments to `if()` of type `<variable|string>` should always be quoted:

+    - Both arguments to the comparison operators -

+      `EQUAL`, `STREQUAL`, `VERSION_LESS`, etc.

+    - The first argument to `MATCHES` and `IN_LIST`

+    - Example:

+      ```cmake

+      if("${FOO}" STREQUAL "BAR") # ...

+      if("${BAZ}" EQUAL "0") # ...

+      if("FOO" IN_LIST list_variable) # ...

+      if("${bar}" MATCHES [[a[bcd]+\.[bcd]+]]) # ...

+      ```

+    - For single expressions and for other types of predicates that do not

+    take `<variable|string>`, use the normal rules.

 - There are no "pointer" or "in-out" parameters

   (where a user passes a variable name rather than the contents),

   except for simple out-parameters.

 - Variables are not assumed to be empty.

   If the variable is intended to be used locally,

-  it must be explicitly initialized to empty with `set(foo "")`.

-- All variables expected to be inherited from the parent scope across an API boundary (i.e. not a file-local function) should be documented. Note that all variables mentioned in triplets.md are considered documented.

+  it must be explicitly initialized to empty with `set(foo "")` if it is a string variable,

+  and `vcpkg_list(SET foo)` if it is a list variable.

+- `set(var)` should not be used. Use `unset(var)` to unset a variable,

+  `set(var "")` to set it to the empty string,

+  and `vcpkg_list(SET var)` to set it to the empty list.

+  _Note: the empty string and the empty list are the same value;_

+  _this is a notational difference rather than a difference in result_

+- All variables expected to be inherited from the parent scope across an API boundary

+  (i.e. not a file-local function) should be documented.

+  Note that all variables mentioned in triplets.md are considered documented.

 - Out parameters are only set in `PARENT_SCOPE` and are never read.

   See also the helper `z_vcpkg_forward_output_variable()` to forward out parameters through a function scope.

 - `CACHE` variables are used only for global variables which are shared internally among strongly coupled

@@ -80,16 +121,14 @@ We hope that they will make both forwards and backwards compatibility easier.
   and `<start>` _must always be_ less than or equal to `<stop>`.

   - This must be checked by something like:

   ```cmake

-  if(start LESS_EQUAL end)

-    foreach(RANGE start end)

+  if("${start}" LESS_EQUAL "${end}")

+    foreach(RANGE "${start}" "${end}")

       ...

     endforeach()

   endif()

   ```

 - All port-based scripts must use `include_guard(GLOBAL)`

   to avoid being included multiple times.

-- `set(var)` should not be used. Use `unset(var)` to unset a variable,

-  and `set(var "")` to set it to the empty value. _Note: this works for use as a list and as a string_

 

 ### CMake Versions to Require

 

diff --git a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md b/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
deleted file mode 100644
index 63218102f..000000000
--- a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# vcpkg_internal_get_cmake_vars
-
-The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
-
-**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
-Runs a cmake configure with a dummy project to extract certain cmake variables
-
-## Usage
-```cmake
-vcpkg_internal_get_cmake_vars(
-    [OUTPUT_FILE <output_file_with_vars>]
-    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-)
-```
-
-## Parameters
-### OPTIONS
-Additional options to pass to the test configure call 
-
-### OUTPUT_FILE
-Variable to return the path to the generated cmake file with the detected `CMAKE_` variables set as `VCKPG_DETECTED_`
-
-## Notes
-If possible avoid usage in portfiles. 
-
-## Examples
-
-* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
-
-## Source
-[scripts/cmake/vcpkg\_internal\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_internal_get_cmake_vars.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md b/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md
new file mode 100644
index 000000000..2dcf2a8e7
--- /dev/null
+++ b/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md
@@ -0,0 +1,36 @@
+# z_vcpkg_get_cmake_vars
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
+
+**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
+Runs a cmake configure with a dummy project to extract certain cmake variables
+
+## Usage
+```cmake
+z_vcpkg_get_cmake_vars(<out-var>)
+```
+
+`z_vcpkg_get_cmake_vars(cmake_vars_file)` sets `<out-var>` to
+a path to a generated CMake file, with the detected `CMAKE_*` variables
+re-exported as `VCPKG_DETECTED_*`.
+
+## Notes
+Avoid usage in portfiles. 
+
+All calls to `z_vcpkg_get_cmake_vars` will result in the same output file;
+the output file is not generated multiple times.
+
+## Examples
+
+* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
+
+### Basic Usage
+
+```cmake
+z_vcpkg_get_cmake_vars(cmake_vars_file)
+include("${cmake_vars_file}")
+message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CXX_FLAGS}")
+```
+
+## Source
+[scripts/cmake/z\_vcpkg\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_get_cmake_vars.cmake)
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index 0ba3533e2..45aa4589b 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -57,10 +57,10 @@
 
 ## Internal Functions
 
-- [vcpkg\_internal\_get\_cmake\_vars](internal/vcpkg_internal_get_cmake_vars.md)
 - [z\_vcpkg\_apply\_patches](internal/z_vcpkg_apply_patches.md)
 - [z\_vcpkg\_forward\_output\_variable](internal/z_vcpkg_forward_output_variable.md)
 - [z\_vcpkg\_function\_arguments](internal/z_vcpkg_function_arguments.md)
+- [z\_vcpkg\_get\_cmake\_vars](internal/z_vcpkg_get_cmake_vars.md)
 - [z\_vcpkg\_prettify\_command\_line](internal/z_vcpkg_prettify_command_line.md)
 
 ## Scripts from Ports
@@ -69,6 +69,7 @@
 
 - [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md)
 - [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md)
+- [vcpkg\_cmake\_get\_vars](ports/vcpkg-cmake/vcpkg_cmake_get_vars.md)
 - [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md)
 
 ### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md)
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_get_vars.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_get_vars.md
new file mode 100644
index 000000000..68e51333c
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_get_vars.md
@@ -0,0 +1,31 @@
+# vcpkg_cmake_get_vars
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_get_vars.md).
+
+Runs a cmake configure with a dummy project to extract certain cmake variables
+
+## Usage
+```cmake
+vcpkg_cmake_get_vars(<out-var>)
+```
+
+`vcpkg_cmake_get_vars(<out-var>)` sets `<out-var>` to
+a path to a generated CMake file, with the detected `CMAKE_*` variables
+re-exported as `VCPKG_DETECTED_CMAKE_*`.
+
+## Notes
+Avoid usage in portfiles.
+
+All calls to `vcpkg_cmake_get_vars` will result in the same output file;
+the output file is not generated multiple times.
+
+### Basic Usage
+
+```cmake
+vcpkg_cmake_get_vars(cmake_vars_file)
+include("${cmake_vars_file}")
+message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CMAKE_CXX_FLAGS}")
+```
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_get\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_get_vars.cmake)
diff --git a/docs/regenerate.ps1 b/docs/regenerate.ps1
index 7844055ef..f2f888a77 100755
--- a/docs/regenerate.ps1
+++ b/docs/regenerate.ps1
@@ -222,7 +222,7 @@ function ParseCmakeDocComment
 
 Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
     $docs = ParseCmakeDocComment $_
-    [Bool]$isInternalFunction = $_.Name.StartsWith("vcpkg_internal") -or $_.Name.StartsWith("z_vcpkg")
+    [Bool]$isInternalFunction = $_.Name.StartsWith("z_vcpkg")
 
     if ($docs.IsDeprecated -and $null -eq $docs.ActualDocumentation)
     {