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

6 files changed, 205 insertions, 0 deletions

diff --git a/docs/maintainers/ports/vcpkg-cmake-config.md b/docs/maintainers/ports/vcpkg-cmake-config.md
new file mode 100644
index 000000000..18e7bb9ac
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake-config.md
@@ -0,0 +1,10 @@
+# vcpkg-cmake-config
+
+`vcpkg-cmake-config` provides `vcpkg_cmake_config_fixup()`,
+a function which both:
+
+- Fixes common mistakes in port build systems, like using absolute paths
+- Merges the debug and release config files.
+
+This function should almost always be used when a port has `*config.cmake` files,
+even when the buildsystem of the project is not CMake.
diff --git a/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md b/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md
new file mode 100644
index 000000000..43d5c56cf
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md
@@ -0,0 +1,51 @@
+# vcpkg_cmake_config_fixup
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md).
+
+Merge release and debug CMake targets and configs to support multiconfig generators.
+
+Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
+
+```cmake
+vcpkg_cmake_config_fixup(
+    [PACKAGE_NAME <name>]
+    [CONFIG_PATH <config-directory>]
+    [DO_NOT_DELETE_CONFIG_PATH_PARENT]
+    [NO_PREFIX_CORRECTION]
+)
+```
+
+For many ports, `vcpkg_cmake_config_fixup()` on its own should work,
+as `PACKAGE_NAME` defaults to `${PORT}` and `CONFIG_PATH` defaults to `share/${PACKAGE_NAME}`.
+For ports where the package name passed to `find_package` is distinct from the port name,
+`PACKAGE_NAME` should be changed to be that name instead.
+For ports where the directory of the `*config.cmake` files cannot be set,
+use the `CONFIG_PATH` to change the directory where the files come from.
+
+By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
+Passing the `DO_NOT_DELETE_PARENT_CONFIG_PATH` option disable such behavior,
+as it is convenient for ports that install
+more than one CMake package configuration file.
+
+The `NO_PREFIX_CORRECTION` option disables the correction of `_IMPORT_PREFIX`
+done by vcpkg due to moving the config files.
+Currently the correction does not take into account how the files are moved,
+and applies a rather simply correction which in some cases will yield the wrong results.
+
+## How it Works
+
+1. Moves `/debug/<CONFIG_PATH>/*targets-debug.cmake` to `/share/${PACKAGE_NAME}`.
+2. Removes `/debug/<CONFIG_PATH>/*config.cmake`.
+3. Transform all references matching `/bin/*.exe` to `/tools/<port>/*.exe` on Windows.
+4. Transform all references matching `/bin/*` to `/tools/<port>/*` on other platforms.
+5. Fixes `${_IMPORT_PREFIX}` in auto generated targets.
+6. Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets.
+
+## Examples
+
+* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
+* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake)
+* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
+
+## Source
+[ports/vcpkg-cmake-config/vcpkg\_cmake\_config\_fixup.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake.md b/docs/maintainers/ports/vcpkg-cmake.md
new file mode 100644
index 000000000..b84c58869
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake.md
@@ -0,0 +1,7 @@
+# vcpkg-cmake
+
+This port contains cmake functions for dealing with a CMake buildsystem.
+
+In the common case, `vcpkg_cmake_configure()` (with appropriate arguments)
+followed by `vcpkg_cmake_install()` will be enough to build and install a port.
+`vcpkg_cmake_build()` is provided for more complex cases.
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md
new file mode 100644
index 000000000..be64ca1a6
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md
@@ -0,0 +1,36 @@
+# vcpkg_cmake_build
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md).
+
+Build a cmake project.
+
+```cmake
+vcpkg_cmake_build(
+    [TARGET <target>]
+    [LOGFILE_BASE <base>]
+    [DISABLE_PARALLEL]
+    [ADD_BIN_TO_PATH]
+)
+```
+
+`vcpkg_cmake_build` builds an already-configured cmake project.
+You can use the alias [`vcpkg_cmake_install()`] function
+if your CMake build system supports the `install` TARGET,
+and this is something we recommend doing whenever possible.
+Otherwise, you can use `TARGET` to set the target to build.
+This function defaults to not passing a target to cmake.
+
+`LOGFILE_BASE` is used to set the base of the logfile names;
+by default, this is `build`, and thus the logfiles end up being something like
+`build-x86-windows-dbg.log`; if you use `vcpkg_cmake_install`,
+this is set to `install`, so you'll get log names like `install-x86-windows-dbg.log`.
+
+For build systems that are buggy when run in parallel,
+using `DISABLE_PARALLEL` will run the build with only one job.
+
+Finally, `ADD_BIN_TO_PATH` adds the appropriate (either release or debug)
+`bin/` directories to the path during the build,
+such that executables run during the build will be able to access those DLLs.
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md
new file mode 100644
index 000000000..23e8c5cf9
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md
@@ -0,0 +1,76 @@
+# vcpkg_cmake_configure
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md).
+
+Configure a CMake buildsystem.
+
+```cmake
+vcpkg_cmake_configure(
+    SOURCE_PATH <source-path>
+    [LOGFILE_BASE <logname-base>]
+    [DISABLE_PARALLEL_CONFIGURE]
+    [NO_CHARSET_FLAG]
+    [WINDOWS_USE_MSBUILD]
+    [GENERATOR <generator>]
+    [OPTIONS
+        <configure-setting>...]
+    [OPTIONS_RELEASE
+        <configure-setting>...]
+    [OPTIONS_DEBUG
+        <configure-setting>...]
+)
+```
+
+`vcpkg_cmake_configure` configures a CMake build system for use with
+`vcpkg_cmake_buildsystem_build` and `vcpkg_cmake_buildsystem_install`.
+`source-path` is where the source is located; by convention,
+this is usually `${SOURCE_PATH}`, which is set by one of the `vcpkg_from_*` functions.
+This function configures the build system for both Debug and Release builds by default,
+assuming that `VCPKG_BUILD_TYPE` is not set; if it is, then it will only configure for
+that build type.
+
+Use the `OPTIONS` argument to set the configure settings for both release and debug,
+and use `OPTIONS_RELEASE` and `OPTIONS_DEBUG` to set the configure settings for
+release only and debug only repsectively.
+
+By default, when possible, `vcpkg_cmake_configure` uses [ninja-build]
+as its build system. If the `WINDOWS_USE_MSBUILD` argument is passed, then
+`vcpkg_cmake_configure` will use a Visual Studio generator on Windows;
+on every other platform, `vcpkg_cmake_configure` just uses Ninja.
+
+[ninja-build]: https://ninja-build.org/
+
+Additionally, one may pass the specific generator a port should use with `GENERATOR`.
+This is useful if some project-specific buildsystem
+has been wrapped in a CMake build system that doesn't perform an actual build.
+If used for this purpose, it should be set to `"NMake Makefiles"`.
+`vcpkg_cmake_buildsystem_build` and `install` do not support this being set to anything
+except for NMake.
+
+For libraries which cannot be configured in parallel,
+pass the `DISABLE_PARALLEL_CONFIGURE` flag. This is needed, for example,
+if the library's build system writes back into the source directory during configure.
+This also disables the `CMAKE_DISABLE_SOURCE_CHANGES` option.
+
+By default, this function adds flags to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`
+which set the default character set to utf-8 for MSVC.
+If the library sets its own code page, pass the `NO_CHARSET_FLAG` option.
+
+`LOGFILE_BASE` is used to set the base of the logfile names;
+by default, this is `config`, and thus the logfiles end up being something like
+`config-x86-windows-dbg.log`. You can set it to anything you like;
+if you set it to `config-the-first`,
+you'll get something like `config-the-first-x86-windows.dbg.log`.
+
+## Notes
+This command supplies many common arguments to CMake. To see the full list, examine the source.
+
+## Examples
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md
new file mode 100644
index 000000000..d328825bd
--- /dev/null
+++ b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md
@@ -0,0 +1,25 @@
+# vcpkg_cmake_install
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md).
+
+Build and install a cmake project.
+
+```cmake
+vcpkg_cmake_install(
+    [DISABLE_PARALLEL]
+    [ADD_BIN_TO_PATH]
+)
+```
+
+`vcpkg_cmake_install` transparently forwards to [`vcpkg_cmake_build()`],
+with additional parameters to set the `TARGET` to `install`,
+and to set the `LOGFILE_ROOT` to `install` as well.
+
+[`vcpkg_cmake_build()`]: vcpkg_cmake_build.cmake
+
+## Examples:
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_install.cmake)