[scripts-audit] Rollup PR 2021-02-26 (#16440)

* [scripts-audit rollup] PR #16419

* pull the cmake doc comment parsing out into its own function
* support cmake helper ports
* add real support for deprecation, as opposed to ad-hoc

* [scripts-audit rollup] PR #16192

* add a z_ in front of internal functions
* move internal functions out

set feature_vars again in parent scope

* [scripts-audit rollup] PR #16309

Audit vcpkg_copy_pdbs

* [scripts-audit rollup] PR #16304

* Fix usage, documentation

* [scripts-audit rollup] PR #16393

* [scripts-audit rollup] PR #16377

Deprecate `vcpkg_*_cmake` in favor of `vcpkg_cmake_*` from the
`vcpkg-cmake` port, as well as `vcpkg_fixup_cmake_targets`
in favor of `vcpkg_cmake_config_fixup` from the
`vcpkg-cmake-config` port.

4 files changed, 41 insertions, 3 deletions

diff --git a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md b/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
index dbac84587..62ac8080c 100644
--- a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
+++ b/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
@@ -1,5 +1,7 @@
 # vcpkg_internal_get_cmake_vars
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
 **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
 
@@ -26,4 +28,4 @@ If possible avoid usage in portfiles.
 * [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)
+[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_apply_patches.md b/docs/maintainers/internal/z_vcpkg_apply_patches.md
new file mode 100644
index 000000000..e4d54caf4
--- /dev/null
+++ b/docs/maintainers/internal/z_vcpkg_apply_patches.md
@@ -0,0 +1,32 @@
+# z_vcpkg_apply_patches
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
+**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
+
+Apply a set of patches to a source tree.
+
+```cmake
+z_vcpkg_apply_patches(
+    SOURCE_PATH <path-to-source>
+    [QUIET]
+    PATCHES <patch>...
+)
+```
+
+The `<path-to-source>` should be set to `${SOURCE_PATH}` by convention,
+and is the path to apply the patches in.
+
+`z_vcpkg_apply_patches` will take the list of `<patch>`es,
+which are by default relative to the port directory,
+and apply them in order using `git apply`.
+Generally, these `<patch>`es take the form of `some.patch`
+to select patches in the port directory.
+One may also download patches and use `${VCPKG_DOWNLOADS}/path/to/some.patch`.
+
+If `QUIET` is not passed, it is a fatal error for a patch to fail to apply;
+otherwise, if `QUIET` is passed, no message is printed.
+This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
+
+## Source
+[scripts/cmake/z\_vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_apply_patches.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_function_arguments.md b/docs/maintainers/internal/z_vcpkg_function_arguments.md
index e60407f20..a31d8b33c 100644
--- a/docs/maintainers/internal/z_vcpkg_function_arguments.md
+++ b/docs/maintainers/internal/z_vcpkg_function_arguments.md
@@ -1,5 +1,7 @@
 # z_vcpkg_function_arguments
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
 **Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
 Get a list of the arguments which were passed in.
 Unlike `ARGV`, which is simply the arguments joined with `;`,
@@ -24,4 +26,4 @@ endfunction()
 ```
 
 ## Source
-[scripts/cmake/z_vcpkg_function_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)
+[scripts/cmake/z\_vcpkg\_function\_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_prettify_command_line.md b/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
index 1b7636630..9bbb1c457 100644
--- a/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
+++ b/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
@@ -1,5 +1,7 @@
 # z_vcpkg_prettify_command_line
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
 **Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
 Turn a command line into a formatted string.
 
@@ -16,4 +18,4 @@ This command is for internal use, when printing out to a message.
 * `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
 
 ## Source
-[scripts/cmake/z_vcpkg_prettify_command_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake)
+[scripts/cmake/z\_vcpkg\_prettify\_command\_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake)