[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>

2 files changed, 36 insertions, 31 deletions

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)