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

docs/maintainers/execute_process.md

@@ -1,9 +1,11 @@
 # execute_process
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/execute_process.md).
+
 Intercepts all calls to execute_process() inside portfiles and fails when Download Mode
 is enabled.
 
 In order to execute a process in Download Mode call `vcpkg_execute_in_download_mode()` instead.
 
 ## Source
-[scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)
+[scripts/cmake/execute\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)

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)

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)

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)

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)

docs/maintainers/portfile-functions.md

@@ -1,10 +1,10 @@
-<!-- Run regenerate.ps1 to extract documentation from scripts/cmake/*.cmake -->
+<!-- Run regenerate.ps1 to extract scripts documentation -->
 
 # Portfile helper functions
 - [execute\_process](execute_process.md)
 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
-- [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
+- [vcpkg\_apply\_patches](vcpkg_apply_patches.md) (deprecated)
 - [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
 - [vcpkg\_build\_gn](vcpkg_build_gn.md)
 - [vcpkg\_build\_make](vcpkg_build_make.md)
@@ -58,5 +58,18 @@
 ## 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\_function\_arguments](internal/z_vcpkg_function_arguments.md)
 - [z\_vcpkg\_prettify\_command\_line](internal/z_vcpkg_prettify_command_line.md)
+
+## Scripts from Ports
+
+### [vcpkg-cmake](ports/vcpkg-cmake.md)
+
+- [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md)
+- [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md)
+- [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md)
+
+### [vcpkg-cmake-config](ports/vcpkg-cmake-config.md)
+
+- [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md)

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.

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)

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.

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)

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)

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)

docs/maintainers/vcpkg_acquire_msys.md

@@ -1,5 +1,7 @@
 # vcpkg_acquire_msys
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_acquire_msys.md).
+
 Download and prepare an MSYS2 instance.
 
 ## Usage
@@ -55,4 +57,4 @@ vcpkg_execute_required_process(
 * [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_acquire_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)
+[scripts/cmake/vcpkg\_acquire\_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)

docs/maintainers/vcpkg_add_to_path.md

@@ -1,5 +1,7 @@
 # vcpkg_add_to_path
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_add_to_path.md).
+
 Add a directory or directories to the PATH environment variable
 
 ```cmake
@@ -22,4 +24,4 @@ If no paths are passed, then nothing will be done.
 * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
 
 ## Source
-[scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)
+[scripts/cmake/vcpkg\_add\_to\_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)

docs/maintainers/vcpkg_apply_patches.md

@@ -1,8 +1,11 @@
 # vcpkg_apply_patches
 
-Apply a set of patches to a source tree. This function is deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
+**This function has been deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.**
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_apply_patches.md).
+
+Apply a set of patches to a source tree.
 
-## Usage
 ```cmake
 vcpkg_apply_patches(
     SOURCE_PATH <${SOURCE_PATH}>
@@ -11,24 +14,5 @@ vcpkg_apply_patches(
 )
 ```
 
-## Parameters
-### SOURCE_PATH
-The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-
-### PATCHES
-A list of patches that are applied to the source tree.
-
-Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
-
-### QUIET
-Disables the warning message upon failure.
-
-This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
-
-## Examples
-
-* [libbson](https://github.com/Microsoft/vcpkg/blob/master/ports/libbson/portfile.cmake)
-* [gdal](https://github.com/Microsoft/vcpkg/blob/master/ports/gdal/portfile.cmake)
-
 ## Source
-[scripts/cmake/vcpkg_apply_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)
+[scripts/cmake/vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)

docs/maintainers/vcpkg_build_cmake.md

@@ -1,5 +1,9 @@
 # vcpkg_build_cmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_cmake.md).
+
+**This function has been deprecated in favor of `vcpkg_cmake_build` from the vcpkg-cmake port.**
+
 Build a cmake project.
 
 ## Usage:
@@ -31,4 +35,4 @@ You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) functi
 * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_build_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)
+[scripts/cmake/vcpkg\_build\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)

docs/maintainers/vcpkg_build_gn.md

@@ -1,5 +1,7 @@
 # vcpkg_build_gn
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_gn.md).
+
 Build a GN project
 
 ## Usage:
@@ -14,4 +16,4 @@ vcpkg_build_gn(
 Only build the specified targets.
 
 ## Source
-[scripts/cmake/vcpkg_build_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_gn.cmake)
+[scripts/cmake/vcpkg\_build\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_gn.cmake)

docs/maintainers/vcpkg_build_make.md

@@ -1,5 +1,7 @@
 # vcpkg_build_make
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_make.md).
+
 Build a linux makefile project.
 
 ## Usage:
@@ -49,4 +51,4 @@ You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function i
 * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_build_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)
+[scripts/cmake/vcpkg\_build\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_make.cmake)

docs/maintainers/vcpkg_build_msbuild.md

@@ -1,5 +1,7 @@
 # vcpkg_build_msbuild
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_msbuild.md).
+
 Build a msbuild-based project. Deprecated in favor of `vcpkg_install_msbuild()`.
 
 ## Usage
@@ -61,4 +63,4 @@ Additional options passed to msbuild for Debug builds. These are in addition to
 * [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_build_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)
+[scripts/cmake/vcpkg\_build\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)

docs/maintainers/vcpkg_build_ninja.md

@@ -1,5 +1,7 @@
 # vcpkg_build_ninja
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_ninja.md).
+
 Build a ninja project
 
 ## Usage:
@@ -14,4 +16,4 @@ vcpkg_build_ninja(
 Only build the specified targets.
 
 ## Source
-[scripts/cmake/vcpkg_build_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake)
+[scripts/cmake/vcpkg\_build\_ninja.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_ninja.cmake)

docs/maintainers/vcpkg_build_nmake.md

@@ -1,5 +1,7 @@
 # vcpkg_build_nmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_nmake.md).
+
 Build a msvc makefile project.
 
 ## Usage:
@@ -73,4 +75,4 @@ You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function
 * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_build_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)
+[scripts/cmake/vcpkg\_build\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_nmake.cmake)

docs/maintainers/vcpkg_build_qmake.md

@@ -1,5 +1,7 @@
 # vcpkg_build_qmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_build_qmake.md).
+
 Build a qmake-based project, previously configured using vcpkg_configure_qmake.
 
 ```cmake
@@ -7,4 +9,4 @@ vcpkg_build_qmake()
 ```
 
 ## Source
-[scripts/cmake/vcpkg_build_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake)
+[scripts/cmake/vcpkg\_build\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake)

docs/maintainers/vcpkg_buildpath_length_warning.md

@@ -1,5 +1,7 @@
 # vcpkg_buildpath_length_warning
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_buildpath_length_warning.md).
+
 Warns the user if their vcpkg installation path might be too long for the package they're installing.
 
 ```cmake
@@ -11,4 +13,4 @@ path to `buildtrees` is bigger than `N`. Note that this is simply a warning,
 and isn't relied on for correctness.
 
 ## Source
-[scripts/cmake/vcpkg_buildpath_length_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake)
+[scripts/cmake/vcpkg\_buildpath\_length\_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake)

docs/maintainers/vcpkg_check_features.md

@@ -1,53 +1,45 @@
 # vcpkg_check_features
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_check_features.md).
 Check if one or more features are a part of a package installation.
 
-## Usage
 ```cmake
 vcpkg_check_features(
-  OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>
+    OUT_FEATURE_OPTIONS <out-var>
-  [FEATURES
+    [PREFIX <prefix>]
-    <cuda> <WITH_CUDA>
+    [FEATURES
-    [<opencv> <WITH_OPENCV>]
+        [<feature-name> <feature-var>]...
-    ...]
+        ]
-  [INVERTED_FEATURES
+    [INVERTED_FEATURES
-    <cuda> <IGNORE_PACKAGE_CUDA>
+        [<feature-name> <feature-var>]...
-    [<opencv> <IGNORE_PACKAGE_OPENCV>]
+        ]
-    ...]
 )
 ```
-`vcpkg_check_features()` accepts these parameters:
 
-* `OUT_FEATURE_OPTIONS`:
+The `<out-var>` should be set to `FEATURE_OPTIONS` by convention.
-  An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS`
-  and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`).
 
-  This should be set to `FEATURE_OPTIONS` by convention.
+`vcpkg_check_features()` will:
 
-* `FEATURES`:
+- for each `<feature-name>` passed in `FEATURES`:
-  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.
+    - if the feature is set, add `-D<feature-var>=ON` to `<out-var>`,
-  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
+      and set `<prefix>_<feature-var>` to ON.
+    - if the feature is not set, add `-D<feature-var>=OFF` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to OFF.
+- for each `<feature-name>` passed in `INVERTED_FEATURES`:
+    - if the feature is set, add `-D<feature-var>=OFF` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to OFF.
+    - if the feature is not set, add `-D<feature-var>=ON` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to ON.
 
-    * `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
+If `<prefix>` is not passed, then the feature vars set are simply `<feature-var>`,
-    * `-D<OPTION_NAME>=OFF`, otherwise.
+not `_<feature-var>`.
 
-* `INVERTED_FEATURES`:
+If `INVERTED_FEATURES` is not passed, then the `FEATURES` keyword is optional.
-  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.
+This behavior is deprecated.
-  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
-
-    * `-D<OPTION_NAME>=OFF`, if a feature is specified for installation,
-    * `-D<OPTION_NAME>=ON`, otherwise.
-
-
-## Notes
-
-The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used.
-
-At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call.
-
-Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication.
-If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists,
-two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
 
+If the same `<feature-var>` is passed multiple times,
+then `vcpkg_check_features` will cause a fatal error,
+since that is a bug.
 
 ## Examples
 
@@ -58,18 +50,18 @@ $ ./vcpkg install mimalloc[asm,secure]
 
 # ports/mimalloc/portfile.cmake
 vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-  # Keyword FEATURES is optional if INVERTED_FEATURES are not used
+    FEATURES
-    asm       MI_SEE_ASM
+        asm       MI_SEE_ASM
-    override  MI_OVERRIDE
+        override  MI_OVERRIDE
-    secure    MI_SECURE
+        secure    MI_SECURE
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
+    SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
+    PREFER_NINJA
-  OPTIONS
+    OPTIONS
-    # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
+        # Expands to "-DMI_SEE_ASM=ON;-DMI_OVERRIDE=OFF;-DMI_SECURE=ON"
-    ${FEATURE_OPTIONS}
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -79,18 +71,18 @@ vcpkg_configure_cmake(
 $ ./vcpkg install cpprestsdk[websockets]
 
 # ports/cpprestsdk/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+vcpkg_check_features(
-  INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
+    INVERTED_FEATURES
-    brotli      CPPREST_EXCLUDE_BROTLI
+        brotli      CPPREST_EXCLUDE_BROTLI
-    websockets  CPPREST_EXCLUDE_WEBSOCKETS
+        websockets  CPPREST_EXCLUDE_WEBSOCKETS
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
+    SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
+    PREFER_NINJA
-  OPTIONS
+    OPTIONS
-    # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
+        # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON;-DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
-    ${FEATURE_OPTIONS}
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -100,18 +92,19 @@ vcpkg_configure_cmake(
 $ ./vcpkg install pcl[cuda]
 
 # ports/pcl/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+vcpkg_check_features(
-    cuda  WITH_CUDA
+    FEATURES
-    cuda  BUILD_CUDA
+        cuda  WITH_CUDA
-    cuda  BUILD_GPU
+        cuda  BUILD_CUDA
+        cuda  BUILD_GPU
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
+    SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
+    PREFER_NINJA
-  OPTIONS
+    OPTIONS
-    # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
+        # Expands to "-DWITH_CUDA=ON;-DBUILD_CUDA=ON;-DBUILD_GPU=ON"
-    ${FEATURE_OPTIONS}
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -121,19 +114,19 @@ vcpkg_configure_cmake(
 $ ./vcpkg install rocksdb[tbb]
 
 # ports/rocksdb/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+vcpkg_check_features(
-  FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
+    FEATURES
-    tbb   WITH_TBB
+        tbb   WITH_TBB
-  INVERTED_FEATURES
+    INVERTED_FEATURES
-    tbb   ROCKSDB_IGNORE_PACKAGE_TBB
+        tbb   ROCKSDB_IGNORE_PACKAGE_TBB
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
+    SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
+    PREFER_NINJA
-  OPTIONS
+    OPTIONS
-    # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
+        # Expands to "-DWITH_TBB=ON;-DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
-    ${FEATURE_OPTIONS}
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -144,4 +137,4 @@ vcpkg_configure_cmake(
 * [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)
+[scripts/cmake/vcpkg\_check\_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)

docs/maintainers/vcpkg_check_linkage.md

@@ -1,5 +1,7 @@
 # vcpkg_check_linkage
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_check_linkage.md).
+
 Asserts the available library and CRT linkage options for the port.
 
 ## Usage
@@ -33,4 +35,4 @@ This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail,
 * [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_check_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake)
+[scripts/cmake/vcpkg\_check\_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake)

docs/maintainers/vcpkg_clean_executables_in_bin.md

@@ -1,5 +1,7 @@
 # vcpkg_clean_executables_in_bin
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_clean_executables_in_bin.md).
+
 Remove specified executables found in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_DIR}/debug/bin`. If, after all specified executables have been removed, and the `bin` and `debug/bin` directories are empty, then also delete `bin` and `debug/bin` directories.
 
 ## Usage
@@ -20,4 +22,4 @@ Generally, there is no need to call this function manually. Instead, pass an ext
 * [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_clean_executables_in_bin.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_executables_in_bin.cmake)
+[scripts/cmake/vcpkg\_clean\_executables\_in\_bin.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_executables_in_bin.cmake)

docs/maintainers/vcpkg_clean_msbuild.md

@@ -1,5 +1,7 @@
 # vcpkg_clean_msbuild
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_clean_msbuild.md).
+
 Clean intermediate files generated by `vcpkg_install_msbuild()`.
 
 ## Usage
@@ -12,4 +14,4 @@ vcpkg_clean_msbuild()
 * [xalan-c](https://github.com/Microsoft/vcpkg/blob/master/ports/xalan-c/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_clean_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)
+[scripts/cmake/vcpkg\_clean\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_clean_msbuild.cmake)

docs/maintainers/vcpkg_common_definitions.md

@@ -1,8 +1,9 @@
 # vcpkg_common_definitions
 
-File contains helpful variabls for portfiles which are commonly needed or used.
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_common_definitions.md).
+
+This file defines the following variabls which are commonly needed or used in portfiles:
 
-## The following variables are available:
 ```cmake
 VCPKG_TARGET_IS_<target>                 with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD, OPENBSD. only defined if <target>
 VCPKG_HOST_IS_<target>                   with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <host>
@@ -25,4 +26,4 @@ Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also define
 portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
 
 ## Source
-[scripts/cmake/vcpkg_common_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)
+[scripts/cmake/vcpkg\_common\_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)

docs/maintainers/vcpkg_configure_cmake.md

@@ -1,5 +1,9 @@
 # vcpkg_configure_cmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_cmake.md).
+
+**This function has been deprecated in favor of `vcpkg_cmake_configure` from the vcpkg-cmake port.**
+
 Configure CMake for Debug and Release builds of a project.
 
 ## Usage
@@ -65,4 +69,4 @@ This command supplies many common arguments to CMake. To see the full list, exam
 * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_configure_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake)
+[scripts/cmake/vcpkg\_configure\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake)

docs/maintainers/vcpkg_configure_gn.md

@@ -1,5 +1,7 @@
 # vcpkg_configure_gn
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_gn.md).
+
 Generate Ninja (GN) targets
 
 ## Usage:
@@ -27,4 +29,4 @@ Options to be passed to the debug target.
 Options to be passed to the release target.
 
 ## Source
-[scripts/cmake/vcpkg_configure_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_gn.cmake)
+[scripts/cmake/vcpkg\_configure\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_gn.cmake)

docs/maintainers/vcpkg_configure_make.md

@@ -1,5 +1,7 @@
 # vcpkg_configure_make
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_make.md).
+
 Configure configure for Debug and Release builds of a project.
 
 ## Usage
@@ -88,4 +90,4 @@ This command supplies many common arguments to configure. To see the full list,
 * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_configure_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
+[scripts/cmake/vcpkg\_configure\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)

docs/maintainers/vcpkg_configure_meson.md

@@ -1,5 +1,7 @@
 # vcpkg_configure_meson
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_meson.md).
+
 Configure Meson for Debug and Release builds of a project.
 
 ## Usage
@@ -35,4 +37,4 @@ This command supplies many common arguments to Meson. To see the full list, exam
 * [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_configure_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake)
+[scripts/cmake/vcpkg\_configure\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_meson.cmake)

docs/maintainers/vcpkg_configure_qmake.md

@@ -1,5 +1,7 @@
 # vcpkg_configure_qmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_configure_qmake.md).
+
 Configure a qmake-based project.
 
 ```cmake
@@ -18,4 +20,4 @@ The path to the *.pro qmake project file.
 The options passed to qmake.
 
 ## Source
-[scripts/cmake/vcpkg_configure_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)
+[scripts/cmake/vcpkg\_configure\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)

docs/maintainers/vcpkg_copy_pdbs.md

@@ -1,25 +1,29 @@
 # vcpkg_copy_pdbs
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_copy_pdbs.md).
+
 Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
 
-## Usage
 ```cmake
-vcpkg_copy_pdbs([BUILD_PATHS <${CURRENT_PACKAGES_DIR}/bin/*.dll> ...])
+vcpkg_copy_pdbs(
+    [BUILD_PATHS <glob>...])
 ```
 
+The `<glob>`s are patterns which will be passed to `file(GLOB_RECURSE)`,
+for locating DLLs. It defaults to using:
+
+- `${CURRENT_PACKAGES_DIR}/bin/*.dll`
+- `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`
+
+since that is generally where DLLs are located.
+
 ## Notes
 This command should always be called by portfiles after they have finished rearranging the binary output.
 
-## Parameters
-### BUILD_PATHS
-Path patterns passed to `file(GLOB_RECURSE)` for locating dlls.
-
-Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`.
-
 ## 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)
 
 ## Source
-[scripts/cmake/vcpkg_copy_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)
+[scripts/cmake/vcpkg\_copy\_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)

docs/maintainers/vcpkg_copy_tool_dependencies.md

@@ -1,5 +1,7 @@
 # vcpkg_copy_tool_dependencies
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_copy_tool_dependencies.md).
+
 Copy all DLL dependencies of built tools into the tool folder.
 
 ## Usage
@@ -18,4 +20,4 @@ This command should always be called by portfiles after they have finished rearr
 * [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_copy_tool_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)
+[scripts/cmake/vcpkg\_copy\_tool\_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)

docs/maintainers/vcpkg_copy_tools.md

@@ -1,5 +1,7 @@
 # vcpkg_copy_tools
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_copy_tools.md).
+
 Copy tools and all their DLL dependencies into the `tools` folder.
 
 ## Usage
@@ -27,4 +29,4 @@ Auto clean executables in `${CURRENT_PACKAGES_DIR}/bin` and `${CURRENT_PACKAGES_
 * [uriparser](https://github.com/microsoft/vcpkg/blob/master/ports/uriparser/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_copy_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake)
+[scripts/cmake/vcpkg\_copy\_tools.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tools.cmake)

docs/maintainers/vcpkg_download_distfile.md

@@ -1,5 +1,7 @@
 # vcpkg_download_distfile
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_download_distfile.md).
+
 Download and cache a file needed for this port.
 
 This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command.
@@ -51,4 +53,4 @@ The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downlo
 * [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_download_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)
+[scripts/cmake/vcpkg\_download\_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)

docs/maintainers/vcpkg_execute_build_process.md

@@ -1,5 +1,7 @@
 # vcpkg_execute_build_process
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_execute_build_process.md).
+
 Execute a required build process
 
 ## Usage
@@ -33,4 +35,4 @@ conflict when building multiple at once.
 * [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_execute_build_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)
+[scripts/cmake/vcpkg\_execute\_build\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_build_process.cmake)

docs/maintainers/vcpkg_execute_in_download_mode.md

@@ -1,5 +1,7 @@
 # vcpkg_execute_in_download_mode
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_execute_in_download_mode.md).
+
 Execute a process even in download mode.
 
 ## Usage
@@ -31,4 +33,4 @@ See [`execute_process()`] for a detailed description of the parameters.
 [`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html
 
 ## Source
-[scripts/cmake/vcpkg_execute_in_download_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)
+[scripts/cmake/vcpkg\_execute\_in\_download\_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)

docs/maintainers/vcpkg_execute_required_process.md

@@ -1,5 +1,7 @@
 # vcpkg_execute_required_process
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_execute_required_process.md).
+
 Execute a process with logging and fail the build if the command fails.
 
 ## Usage
@@ -46,4 +48,4 @@ This should be a unique name for different triplets so that the logs don't confl
 * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_execute_required_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)
+[scripts/cmake/vcpkg\_execute\_required\_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)

docs/maintainers/vcpkg_execute_required_process_repeat.md

@@ -1,5 +1,7 @@
 # vcpkg_execute_required_process_repeat
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_execute_required_process_repeat.md).
+
 Execute a process until the command succeeds, or until the COUNT is reached.
 
 ## Usage
@@ -13,4 +15,4 @@ vcpkg_execute_required_process_repeat(
 ```
 
 ## Source
-[scripts/cmake/vcpkg_execute_required_process_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)
+[scripts/cmake/vcpkg\_execute\_required\_process\_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)

docs/maintainers/vcpkg_extract_source_archive.md

@@ -1,5 +1,7 @@
 # vcpkg_extract_source_archive
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_extract_source_archive.md).
+
 Extract an archive into the source directory. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md).
 
 ## Usage
@@ -29,4 +31,4 @@ This command will also create a tracking file named <FILENAME>.extracted in the
 * [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_extract_source_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)
+[scripts/cmake/vcpkg\_extract\_source\_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)

docs/maintainers/vcpkg_extract_source_archive_ex.md

@@ -1,5 +1,7 @@
 # vcpkg_extract_source_archive_ex
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_extract_source_archive_ex.md).
+
 Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md).
 
 ## Usage
@@ -53,4 +55,4 @@ Specifies that the default removal of the top level folder should not occur.
 * [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_extract_source_archive_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)
+[scripts/cmake/vcpkg\_extract\_source\_archive\_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)

docs/maintainers/vcpkg_fail_port_install.md

@@ -1,5 +1,7 @@
 # vcpkg_fail_port_install
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_fail_port_install.md).
+
 Checks common requirements and fails the current portfile with a (default) error message
 
 ## Usage
@@ -38,4 +40,4 @@ Library linkage for which the build should fail early.
 * [aws-lambda-cpp](https://github.com/Microsoft/vcpkg/blob/master/ports/aws-lambda-cpp/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_fail_port_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)
+[scripts/cmake/vcpkg\_fail\_port\_install.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_port_install.cmake)

docs/maintainers/vcpkg_find_acquire_program.md

@@ -1,5 +1,7 @@
 # vcpkg_find_acquire_program
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_find_acquire_program.md).
+
 Download or find a well-known tool.
 
 ## Usage
@@ -46,4 +48,4 @@ Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_ac
 * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_find_acquire_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)
+[scripts/cmake/vcpkg\_find\_acquire\_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)

docs/maintainers/vcpkg_find_fortran.md

@@ -1,5 +1,7 @@
 # vcpkg_find_fortran
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_find_fortran.md).
+
 Checks if a Fortran compiler can be found.
 Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran 
                        and return required cmake args for building. 
@@ -10,4 +12,4 @@ vcpkg_find_fortran(<additional_cmake_args_out>)
 ```
 
 ## Source
-[scripts/cmake/vcpkg_find_fortran.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_fortran.cmake)
+[scripts/cmake/vcpkg\_find\_fortran.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_fortran.cmake)

docs/maintainers/vcpkg_fixup_cmake_targets.md

@@ -1,5 +1,9 @@
 # vcpkg_fixup_cmake_targets
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_fixup_cmake_targets.md).
+
+**This function has been deprecated in favor of `vcpkg_cmake_config_fixup` from the vcpkg-cmake-config port.**
+
 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.
@@ -22,7 +26,7 @@ This needs to be specified if the port name differs from the `find_package()` na
 
 Defaults to `share/${PORT}`.
 
-### DO_NOT_DELETE_PARENT_CONFIG_PATH 
+### DO_NOT_DELETE_PARENT_CONFIG_PATH
 By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
 Passing this option disable such behavior, as it is convenient for ports that install
 more than one CMake package configuration file.
@@ -49,4 +53,4 @@ Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targe
 * [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_fixup_cmake_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)
+[scripts/cmake/vcpkg\_fixup\_cmake\_targets.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_cmake_targets.cmake)

docs/maintainers/vcpkg_fixup_pkgconfig.md

@@ -1,5 +1,7 @@
 # vcpkg_fixup_pkgconfig
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_fixup_pkgconfig.md).
+
 Fix common paths in *.pc files and make everything relativ to $(prefix)
 
 ## Usage
@@ -40,4 +42,4 @@ Still work in progress. If there are more cases which can be handled here feel f
 * [brotli](https://github.com/Microsoft/vcpkg/blob/master/ports/brotli/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_fixup_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)
+[scripts/cmake/vcpkg\_fixup\_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)

docs/maintainers/vcpkg_from_bitbucket.md

@@ -1,5 +1,7 @@
 # vcpkg_from_bitbucket
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_bitbucket.md).
+
 Download and extract a project from Bitbucket.
 Enables support for installing HEAD `vcpkg.exe install --head <port>`.
 
@@ -56,4 +58,4 @@ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 * [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_from_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)
+[scripts/cmake/vcpkg\_from\_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)

docs/maintainers/vcpkg_from_git.md

@@ -1,5 +1,7 @@
 # vcpkg_from_git
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_git.md).
+
 Download and extract a project from git
 
 ## Usage:
@@ -44,4 +46,4 @@ This parameter is used for automatic REF updates for certain ports in the centra
 * [fdlibm](https://github.com/Microsoft/vcpkg/blob/master/ports/fdlibm/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_from_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake)
+[scripts/cmake/vcpkg\_from\_git.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_git.cmake)

docs/maintainers/vcpkg_from_github.md

@@ -1,5 +1,7 @@
 # vcpkg_from_github
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_github.md).
+
 Download and extract a project from GitHub. Enables support for `install --head`.
 
 ## Usage:
@@ -71,4 +73,4 @@ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 * [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_from_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)
+[scripts/cmake/vcpkg\_from\_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)

docs/maintainers/vcpkg_from_gitlab.md

@@ -1,5 +1,7 @@
 # vcpkg_from_gitlab
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_gitlab.md).
+
 Download and extract a project from Gitlab instances. Enables support for `install --head`.
 
 ## Usage:
@@ -66,4 +68,4 @@ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
 
 ## Source
-[scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)
+[scripts/cmake/vcpkg\_from\_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)

docs/maintainers/vcpkg_from_sourceforge.md

@@ -1,5 +1,7 @@
 # vcpkg_from_sourceforge
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_from_sourceforge.md).
+
 Download and extract a project from sourceforge.
 
 ## Usage:
@@ -65,4 +67,4 @@ Specifies that the default removal of the top level folder should not occur.
 * [tinyfiledialogs](https://github.com/Microsoft/vcpkg/blob/master/ports/tinyfiledialogs/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_from_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake)
+[scripts/cmake/vcpkg\_from\_sourceforge.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_sourceforge.cmake)

docs/maintainers/vcpkg_get_program_files_platform_bitness.md

@@ -1,5 +1,7 @@
 # vcpkg_get_program_files_platform_bitness
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_get_program_files_platform_bitness.md).
+
 Get the Program Files directory of the current platform's bitness:
 either `$ENV{ProgramW6432}` on 64-bit windows,
 or `$ENV{PROGRAMFILES}` on 32-bit windows.
@@ -10,4 +12,4 @@ vcpkg_get_program_files_platform_bitness(<variable>)
 ```
 
 ## Source
-[scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake)
+[scripts/cmake/vcpkg\_get\_program\_files\_platform\_bitness.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake)

docs/maintainers/vcpkg_get_windows_sdk.md

@@ -1,5 +1,7 @@
 # vcpkg_get_windows_sdk
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_get_windows_sdk.md).
+
 Get the Windows SDK number.
 
 ## Usage:
@@ -8,4 +10,4 @@ vcpkg_get_windows_sdk(<variable>)
 ```
 
 ## Source
-[scripts/cmake/vcpkg_get_windows_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake)
+[scripts/cmake/vcpkg\_get\_windows\_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake)

docs/maintainers/vcpkg_install_cmake.md

@@ -1,5 +1,9 @@
 # vcpkg_install_cmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_cmake.md).
+
+**This function has been deprecated in favor of `vcpkg_cmake_install` from the vcpkg-cmake port.**
+
 Build and install a cmake project.
 
 ## Usage:
@@ -22,4 +26,4 @@ parameter.
 * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)
+[scripts/cmake/vcpkg\_install\_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)

docs/maintainers/vcpkg_install_gn.md

@@ -1,5 +1,7 @@
 # vcpkg_install_gn
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_gn.md).
+
 Installs a GN project
 
 ## Usage:
@@ -20,4 +22,4 @@ Only install the specified targets.
 Note: includes must be handled separately
 
 ## Source
-[scripts/cmake/vcpkg_install_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake)
+[scripts/cmake/vcpkg\_install\_gn.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_gn.cmake)

docs/maintainers/vcpkg_install_make.md

@@ -1,5 +1,7 @@
 # vcpkg_install_make
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_make.md).
+
 Build and install a make project.
 
 ## Usage:
@@ -21,4 +23,4 @@ This command transparently forwards to [`vcpkg_build_make()`](vcpkg_build_make.m
 * [libosip2](https://github.com/Microsoft/vcpkg/blob/master/ports/libosip2/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)
+[scripts/cmake/vcpkg\_install\_make.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_make.cmake)

docs/maintainers/vcpkg_install_meson.md

@@ -1,5 +1,7 @@
 # vcpkg_install_meson
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_meson.md).
+
 Builds a meson project previously configured with `vcpkg_configure_meson()`.
 
 ## Usage
@@ -13,4 +15,4 @@ vcpkg_install_meson()
 * [libepoxy](https://github.com/Microsoft/vcpkg/blob/master/ports/libepoxy/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake)
+[scripts/cmake/vcpkg\_install\_meson.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_meson.cmake)

docs/maintainers/vcpkg_install_msbuild.md

@@ -1,5 +1,7 @@
 # vcpkg_install_msbuild
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_msbuild.md).
+
 Build and install a msbuild-based project. This replaces `vcpkg_build_msbuild()`.
 
 ## Usage
@@ -90,4 +92,4 @@ Additional options passed to msbuild for Debug builds. These are in addition to
 * [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake)
+[scripts/cmake/vcpkg\_install\_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_msbuild.cmake)

docs/maintainers/vcpkg_install_nmake.md

@@ -1,5 +1,7 @@
 # vcpkg_install_nmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_nmake.md).
+
 Build and install a msvc makefile project.
 
 ## Usage:
@@ -63,4 +65,4 @@ This command transparently forwards to [`vcpkg_build_nmake()`](vcpkg_build_nmake
 * [freexl](https://github.com/Microsoft/vcpkg/blob/master/ports/freexl/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)
+[scripts/cmake/vcpkg\_install\_nmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_nmake.cmake)

docs/maintainers/vcpkg_install_qmake.md

@@ -1,5 +1,7 @@
 # vcpkg_install_qmake
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_install_qmake.md).
+
 Build and install a qmake project.
 
 ## Usage:
@@ -21,4 +23,4 @@ staging directories.
 * [libqglviewer](https://github.com/Microsoft/vcpkg/blob/master/ports/libqglviewer/portfile.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_install_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake)
+[scripts/cmake/vcpkg\_install\_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_qmake.cmake)

docs/maintainers/vcpkg_minimum_required.md

@@ -1,5 +1,7 @@
 # vcpkg_minimum_required
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_minimum_required.md).
+
 Asserts that the version of the vcpkg program being used to build a port is later than the supplied date, inclusive.
 
 ## Usage
@@ -12,4 +14,4 @@ vcpkg_minimum_required(VERSION 2021-01-13)
 The date-version to check against.
 
 ## Source
-[scripts/cmake/vcpkg_minimum_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_minimum_required.cmake)
+[scripts/cmake/vcpkg\_minimum\_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_minimum_required.cmake)

docs/maintainers/vcpkg_replace_string.md

@@ -1,5 +1,7 @@
 # vcpkg_replace_string
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/vcpkg_replace_string.md).
+
 Replace a string in a file.
 
 ```cmake
@@ -8,4 +10,4 @@ vcpkg_replace_string(filename match_string replace_string)
 
 
 ## Source
-[scripts/cmake/vcpkg_replace_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)
+[scripts/cmake/vcpkg\_replace\_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)

docs/regenerate.ps1

@@ -15,9 +15,73 @@ if (-not (Test-Path "$VcpkgRoot/.vcpkg-root")) {
     throw "Invalid vcpkg instance, did you forget -VcpkgRoot?"
 }
 
-$tableOfContents = @()
+class CMakeDocumentation {
-$internalTableOfContents = @()
+    [String]$Filename
+    [String[]]$ActualDocumentation
+    [Bool]$IsDeprecated
+    [String]$DeprecationMessage
+    [Bool]$HasError
+}
 
+[String[]]$cmakeScriptsPorts = @(
+    'vcpkg-cmake'
+    'vcpkg-cmake-config'
+)
+
+[CMakeDocumentation[]]$tableOfContents = @()
+[CMakeDocumentation[]]$internalTableOfContents = @()
+$portTableOfContents = [ordered]@{}
+
+function RelativeUnixPathTo
+{
+    Param(
+        [Parameter(Mandatory)]
+        [String]$Path,
+        [Parameter(Mandatory)]
+        [String]$Base
+    )
+
+    $Path = Resolve-Path -LiteralPath $Path
+    $Base = Resolve-Path -LiteralPath $Base
+
+    if ($IsWindows)
+    {
+        if ((Split-Path -Qualifier $Path) -ne (Split-Path -Qualifier $Base))
+        {
+            throw "It is not possible to get the relative unix path from $Base to $Path"
+        }
+    }
+
+    $Path = $Path -replace '\\','/'
+    $Base = $Base -replace '\\','/'
+
+    [String[]]$PathArray = $Path -split '/'
+    [String[]]$BaseArray = $Base -split '/'
+
+    [String[]]$Result = @()
+
+    $Idx = 0
+
+    while ($Idx -lt $PathArray.Length -and $Idx -lt $BaseArray.Length)
+    {
+        if ($PathArray[$Idx] -ne $BaseArray[$Idx])
+        {
+            break
+        }
+        ++$Idx
+    }
+
+    for ($BaseIdx = $Idx; $BaseIdx -lt $BaseArray.Length; ++$BaseIdx)
+    {
+        $Result += '..'
+    }
+    for ($PathIdx = $Idx; $PathIdx -lt $PathArray.Length; ++$PathIdx)
+    {
+        $Result += $PathArray[$PathIdx]
+    }
+
+    $Result -join '/'
+}
 function WriteFile
 {
     Param(
@@ -33,41 +97,81 @@ function WriteFile
 function FinalDocFile
 {
     Param(
-        [String[]]$Value,
+        [CMakeDocumentation]$Docs,
-        [String]$Name
+        [String]$PathToFile # something like docs/maintainers/blah.md
     )
-    $Value + @(
+    [String[]]$documentation = @()
+
+    if ($Docs.ActualDocumentation.Length -eq 0)
+    {
+        throw "Invalid documentation: empty docs"
+    }
+
+    $documentation += $Docs.ActualDocumentation[0] # name line
+    if ($Docs.IsDeprecated)
+    {
+        if ($null -eq $Docs.DeprecationMessage)
+        {
+            $documentation += @("", "**This function has been deprecated**")
+        }
+        else
+        {
+            $documentation += @("", "**This function has been deprecated $($Docs.DeprecationMessage)**")
+        }
+    }
+    $documentation += @("", "The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/$PathToFile).")
+
+    $documentation += $Docs.ActualDocumentation[1..$Docs.ActualDocumentation.Length]
+
+    $relativePath = RelativeUnixPathTo $Docs.Filename $VcpkgRoot
+    $documentation += @(
         "",
         "## Source",
-        "[scripts/cmake/$Name](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/$Name)",
+        "[$($relativePath -replace '_','\_')](https://github.com/Microsoft/vcpkg/blob/master/$relativePath)",
         ""
     )
+
+    $documentation
 }
 
-Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
+function ParseCmakeDocComment
-    $filename = $_
+{
-    [String[]]$contents = Get-Content $filename
+    Param(
+        [Parameter(Mandatory)]
+        [System.IO.FileSystemInfo]$Filename
+    )
 
-    if ($contents[0] -eq '# DEPRECATED') {
+    $Docs = New-Object 'CMakeDocumentation'
-        return
+    $Docs.HasError = $False
+    $Docs.IsDeprecated = $False
+    $Docs.Filename = $Filename.FullName
+
+    [String[]]$contents = Get-Content $Filename
+
+    if ($contents[0] -eq '# DEPRECATED')
+    {
+        $Docs.IsDeprecated = $True
+    }
+    elseif($contents[0] -match '^# DEPRECATED: (.*)$')
+    {
+        $Docs.IsDeprecated = $True
+        $Docs.DeprecationMessage = $matches[1]
     }
 
     [String]$startCommentRegex = '#\[(=*)\['
     [String]$endCommentRegex = ''
     [Bool]$inComment = $False
-    [Bool]$failThisFile = $False
-    [Bool]$isInternalFunction = $filename.Name.StartsWith("vcpkg_internal") -or $filename.Name.StartsWith("z_vcpkg")
 
     $contents = $contents | ForEach-Object {
         if (-not $inComment) {
             if ($_ -match "^\s*${startCommentRegex}(\.[a-z]*)?:?\s*$") {
                 if (-not [String]::IsNullOrEmpty($matches[2]) -and $matches[2] -ne '.md') {
-                    Write-Warning "The documentation in ${filename} doesn't seem to be markdown (extension: $($matches[2])). Only markdown is supported; please rewrite the documentation in markdown."
+                    Write-Warning "The documentation in $($Filename.FullName) doesn't seem to be markdown (extension: $($matches[2])). Only markdown is supported; please rewrite the documentation in markdown."
                 }
                 $inComment = $True
                 $endCommentRegex = "\]$($matches[1])\]"
             } elseif ($_ -match $startCommentRegex) {
-                $failThisFile = $True
+                $Docs.HasError = $True
                 Write-Warning "Invalid start of comment -- the comment start must be at the beginning of the line.
     (on line: `"$_`")"
             } else {
@@ -78,7 +182,7 @@ Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
                 $inComment = $False
                 $endCommentRegex = ''
             } elseif ($_ -match $endCommentRegex) {
-                $failThisFile = $True
+                $Docs.HasError = $True
                 Write-Warning "Invalid end of comment -- the comment end must be on it's own on a line.
     (on line: `"$_`")"
             } else {
@@ -89,47 +193,147 @@ Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
     }
 
     if ($inComment) {
-        Write-Warning "File ${filename} has an unclosed comment."
+        Write-Warning "File $($Filename.FullName) has an unclosed comment."
+        $Docs.HasError = $True
+    }
+
+    if ($contents.Length -ne 0)
+    {
+        $Docs.ActualDocumentation = $contents
+    }
+
+    $Docs
+}
+
+Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
+    $docs = ParseCmakeDocComment $_
+    [Bool]$isInternalFunction = $_.Name.StartsWith("vcpkg_internal") -or $_.Name.StartsWith("z_vcpkg")
+
+    if ($docs.IsDeprecated -and $null -eq $docs.ActualDocumentation)
+    {
+        return
+    }
+    if ($docs.HasError)
+    {
         return
     }
 
-    if ($failThisFile) {
+    if ($null -ne $docs.ActualDocumentation)
-        return
+    {
-    }
+        if ($isInternalFunction)
-
+        {
-
+            $pathToFile = "maintainers/internal/$($_.BaseName).md"
-    if ($contents) {
-        if ($isInternalFunction) {
             WriteFile `
-                -Path "$PSScriptRoot/maintainers/internal/$($filename.BaseName).md" `
+                -Path "$PSScriptRoot/$pathToFile" `
-                -Value (FinalDocFile $contents $filename.Name)
+                -Value (FinalDocFile $docs)
 
-            $internalTableOfContents += $filename.BaseName
+            $internalTableOfContents += $docs
-        } else {
-            WriteFile `
-                -Path "$PSScriptRoot/maintainers/$($filename.BaseName).md" `
-                -Value (FinalDocFile $contents $filename.Name)
-
-            $tableOfContents += $filename.BaseName
         }
-    } elseif (-not $isInternalFunction) {
+        else
+        {
+            $pathToFile = "maintainers/$($_.BaseName).md"
+            WriteFile `
+                -Path "$PSScriptRoot/$pathToFile" `
+                -Value (FinalDocFile $docs $pathToFile)
+
+            $tableOfContents += $docs
+        }
+    }
+    elseif (-not $isInternalFunction)
+    {
         # don't worry about undocumented internal functions
-        Write-Warning "The cmake function in file $filename doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
+        Write-Warning "The cmake function in file $($_.FullName) doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
+    }
+}
+
+$cmakeScriptsPorts | ForEach-Object {
+    $portName = $_
+
+    Copy-Item "$VcpkgRoot/ports/$portName/README.md" "$PSScriptRoot/maintainers/ports/$portName.md"
+    New-Item -Path "$PSScriptRoot/maintainers/ports/$portName" -Force -ItemType 'Directory' | Out-Null
+
+    $portTableOfContents[$portName] = @()
+
+    Get-ChildItem "$VcpkgRoot/ports/$portName" -Filter '*.cmake' | ForEach-Object {
+        if ($_.Name -eq 'vcpkg-port-config.cmake' -or $_.Name -eq 'portfile.cmake')
+        {
+            return
+        }
+
+        $docs = ParseCmakeDocComment $_
+
+        if ($docs.IsDeprecated -and $null -eq $docs.ActualDocumentation)
+        {
+            return
+        }
+        if ($docs.HasError)
+        {
+            return
+        }
+
+        if ($null -ne $docs.ActualDocumentation)
+        {
+            $pathToFile = "maintainers/ports/$portName/$($_.BaseName).md"
+            WriteFile `
+                -Path "$PSScriptRoot/$pathToFile" `
+                -Value (FinalDocFile $docs $pathToFile)
+            $portTableOfContents[$portName] += $docs
+        }
+        else
+        {
+            Write-Warning "The cmake function in file $($_.FullName) doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
+        }
     }
 }
 
 $portfileFunctionsContent = @(
-    '<!-- Run regenerate.ps1 to extract documentation from scripts/cmake/*.cmake -->',
+    '<!-- Run regenerate.ps1 to extract scripts documentation -->',
     '',
     '# Portfile helper functions')
 
-$tableOfContents | Sort-Object -Culture '' | ForEach-Object {
+$DocsName = @{ expression = { Split-Path -LeafBase $_.Filename } }
-    $portfileFunctionsContent += "- [$($_ -replace '_','\_')]($_.md)"
+$tableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
+    $name = Split-Path -LeafBase $_.Filename
+    if ($_.IsDeprecated)
+    {
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md) (deprecated)"
+    }
+    else
+    {
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md)"
+    }
 }
 $portfileFunctionsContent += @("", "## Internal Functions", "")
-$internalTableOfContents | Sort-Object -Culture '' | ForEach-Object {
+$internalTableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
-    $portfileFunctionsContent += "- [$($_ -replace '_','\_')](internal/$_.md)"
+    $name = Split-Path -LeafBase $_.Filename
+    if ($_.IsDeprecated)
+    {
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md) (deprecated)"
+    }
+    else
+    {
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md)"
+    }
 }
+
+$portfileFunctionsContent += @("", "## Scripts from Ports")
+$portTableOfContents.GetEnumerator() | ForEach-Object {
+    $portName = $_.Name
+    $cmakeDocs = $_.Value
+    $portfileFunctionsContent += @("", "### [$portName](ports/$portName.md)", "")
+    $cmakeDocs | ForEach-Object {
+        $name = Split-Path -LeafBase $_.Filename
+        if ($_.IsDeprecated)
+        {
+            $portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md) (deprecated)"
+        }
+        else
+        {
+            $portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md)"
+        }
+    }
+}
+
 $portfileFunctionsContent += "" # final newline
 
 WriteFile `

ports/fmt/CONTROL

@@ -1,5 +0,0 @@
-Source: fmt
-Version: 7.1.3
-Port-Version: 0
-Homepage: https://github.com/fmtlib/fmt
-Description: Formatting library for C++. It can be used as a safe alternative to printf or as a fast alternative to IOStreams.

ports/fmt/portfile.cmake

@@ -6,16 +6,15 @@ vcpkg_from_github(
     HEAD_REF master
     PATCHES fix-warning4189.patch
 )
-vcpkg_configure_cmake(
+vcpkg_cmake_configure(
     SOURCE_PATH ${SOURCE_PATH}
-    PREFER_NINJA
     OPTIONS
         -DFMT_CMAKE_DIR=share/fmt
         -DFMT_TEST=OFF
         -DFMT_DOC=OFF
 )
 
-vcpkg_install_cmake()
+vcpkg_cmake_install()
 file(INSTALL ${SOURCE_PATH}/LICENSE.rst DESTINATION ${CURRENT_PACKAGES_DIR}/share/${PORT} RENAME copyright)
 if(VCPKG_LIBRARY_LINKAGE STREQUAL dynamic)
     if(VCPKG_TARGET_IS_WINDOWS)
@@ -40,7 +39,7 @@ if(VCPKG_LIBRARY_LINKAGE STREQUAL dynamic)
 endif()
 file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)
 
-vcpkg_fixup_cmake_targets()
+vcpkg_cmake_config_fixup()
 vcpkg_fixup_pkgconfig()
 
 if(VCPKG_TARGET_IS_WINDOWS)

ports/fmt/vcpkg.json

@@ -0,0 +1,17 @@
+{
+  "name": "fmt",
+  "version": "7.1.3",
+  "port-version": 1,
+  "description": "Formatting library for C++. It can be used as a safe alternative to printf or as a fast alternative to IOStreams.",
+  "homepage": "https://github.com/fmtlib/fmt",
+  "dependencies": [
+    {
+      "name": "vcpkg-cmake",
+      "host": true
+    },
+    {
+      "name": "vcpkg-cmake-config",
+      "host": true
+    }
+  ]
+}

ports/vcpkg-cmake-config/README.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.

ports/vcpkg-cmake-config/copyright

@@ -0,0 +1,23 @@
+Copyright (c) Microsoft Corporation
+
+All rights reserved. 
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ports/vcpkg-cmake-config/portfile.cmake

@@ -0,0 +1,11 @@
+if(NOT TARGET_TRIPLET STREQUAL _HOST_TRIPLET)
+    message(FATAL_ERROR "vcpkg-cmake-config is a host-only port; please mark it as a host port in your dependencies.")
+endif()
+
+file(INSTALL
+    "${CMAKE_CURRENT_LIST_DIR}/vcpkg_cmake_config_fixup.cmake"
+    "${CMAKE_CURRENT_LIST_DIR}/vcpkg-port-config.cmake"
+    "${CMAKE_CURRENT_LIST_DIR}/copyright"
+    DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
+
+set(VCPKG_POLICY_EMPTY_PACKAGE enabled)

ports/vcpkg-cmake-config/vcpkg-port-config.cmake

@@ -0,0 +1 @@
+include("${CMAKE_CURRENT_LIST_DIR}/vcpkg_cmake_config_fixup.cmake")

ports/vcpkg-cmake-config/vcpkg.json

@@ -0,0 +1,4 @@
+{
+  "name": "vcpkg-cmake-config",
+  "version-date": "2021-02-26"
+}

ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.cmake

@@ -0,0 +1,237 @@
+#[===[.md:
+# vcpkg_cmake_config_fixup
+
+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)
+#]===]
+if(Z_VCPKG_CMAKE_CONFIG_FIXUP_GUARD)
+    return()
+endif()
+set(Z_VCPKG_CMAKE_CONFIG_FIXUP_GUARD ON CACHE INTERNAL "guard variable")
+
+function(vcpkg_cmake_config_fixup)
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "DO_NOT_DELETE_PARENT_CONFIG_PATH" "PACKAGE_NAME;CONFIG_PATH;NO_PREFIX_CORRECTION" "")
+
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "vcpkg_cmake_config_fixup was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+    if(NOT arg_PACKAGE_NAME)
+        set(arg_PACKAGE_NAME "${PORT}")
+    endif()
+    if(NOT arg_CONFIG_PATH)
+        set(arg_CONFIG_PATH "share/${arg_PACKAGE_NAME}")
+    endif()
+    set(target_path "share/${arg_PACKAGE_NAME}")
+
+    string(REPLACE "." "\\." EXECUTABLE_SUFFIX "${VCPKG_TARGET_EXECUTABLE_SUFFIX}")
+
+    set(debug_share "${CURRENT_PACKAGES_DIR}/debug/${target_path}")
+    set(release_share "${CURRENT_PACKAGES_DIR}/${target_path}")
+
+    if(NOT arg_CONFIG_PATH STREQUAL "share/${arg_PACKAGE_NAME}")
+        if(arg_CONFIG_PATH STREQUAL "share")
+            set(arg_CONFIG_PATH z_vcpkg_share)
+            file(RENAME "${CURRENT_PACKAGES_DIR}/debug/share" "${CURRENT_PACKAGES_DIR}/debug/${arg_CONFIG_PATH}")
+            file(RENAME "${CURRENT_PACKAGES_DIR}/share" "${CURRENT_PACKAGES_DIR}/${arg_CONFIG_PATH}")
+        endif()
+
+        set(debug_config "${CURRENT_PACKAGES_DIR}/debug/${arg_CONFIG_PATH}")
+        set(release_config "${CURRENT_PACKAGES_DIR}/${arg_CONFIG_PATH}")
+        if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
+            if(NOT EXISTS "${debug_config}")
+                message(FATAL_ERROR "'${debug_config}' does not exist.")
+            endif()
+
+            # This roundabout handling enables CONFIG_PATH = share
+            file(MAKE_DIRECTORY "${debug_share}")
+            file(GLOB files "${debug_config}/*")
+            file(COPY ${files} DESTINATION "${debug_share}")
+            file(REMOVE_RECURSE "${debug_config}")
+        endif()
+
+        file(GLOB files "${release_config}/*")
+        file(COPY ${files} DESTINATION "${release_share}")
+        file(REMOVE_RECURSE "${release_config}")
+
+        if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
+            get_filename_component(debug_config_dir_name "${debug_config}" NAME)
+            string(TOLOWER "${debug_config_dir_name}" debug_config_dir_name)
+            if(debug_config_dir_name STREQUAL "cmake" AND NOT arg_DO_NOT_DELETE_PARENT_CONFIG_PATH)
+                file(REMOVE_RECURSE "${debug_config}")
+            else()
+                get_filename_component(debug_config_parent_dir "${debug_config}" DIRECTORY)
+                get_filename_component(debug_config_dir_name "${debug_config_parent_dir}" NAME)
+                string(TOLOWER "${debug_config_dir_name}" debug_config_dir_name)
+                if(debug_config_dir_name STREQUAL "cmake" AND NOT arg_DO_NOT_DELETE_PARENT_CONFIG_PATH)
+                    file(REMOVE_RECURSE "${debug_config_parent_dir}")
+                endif()
+            endif()
+        endif()
+
+        get_filename_component(release_config_dir_name "${release_config}" NAME)
+        string(TOLOWER "${release_config_dir_name}" release_config_dir_name)
+        if(release_config_dir_name STREQUAL "cmake" AND NOT arg_DO_NOT_DELETE_PARENT_CONFIG_PATH)
+            file(REMOVE_RECURSE "${release_config}")
+        else()
+            get_filename_component(release_config_parent_dir "${release_config}" DIRECTORY)
+            get_filename_component(release_config_dir_name "${release_config_parent_dir}" NAME)
+            string(TOLOWER "${release_config_dir_name}" release_config_dir_name)
+            if(release_config_dir_name STREQUAL "cmake" AND NOT arg_DO_NOT_DELETE_PARENT_CONFIG_PATH)
+                file(REMOVE_RECURSE "${release_config_parent_dir}")
+            endif()
+        endif()
+    endif()
+
+    if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
+        if(NOT EXISTS "${debug_share}")
+            message(FATAL_ERROR "'${debug_share}' does not exist.")
+        endif()
+    endif()
+
+    file(GLOB_RECURSE unused_files
+        "${debug_share}/*[Tt]argets.cmake"
+        "${debug_share}/*[Cc]onfig.cmake"
+        "${debug_share}/*[Cc]onfigVersion.cmake"
+        "${debug_share}/*[Cc]onfig-version.cmake"
+    )
+    if(NOT unused_files STREQUAL "")
+        file(REMOVE "${unused_files}")
+    endif()
+
+    file(GLOB_RECURSE release_targets
+        "${release_share}/*-release.cmake"
+    )
+    foreach(release_target IN LISTS release_targets)
+        file(READ "${release_target}" contents)
+        string(REPLACE "${CURRENT_INSTALLED_DIR}" "\${_IMPORT_PREFIX}" contents "${contents}")
+        string(REGEX REPLACE "\\\${_IMPORT_PREFIX}/bin/([^ \"]+${EXECUTABLE_SUFFIX})" "\${_IMPORT_PREFIX}/tools/${PORT}/\\1" contents "${contents}")
+        file(WRITE "${release_target}" "${contents}")
+    endforeach()
+
+    if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
+        file(GLOB_RECURSE debug_targets
+            "${debug_share}/*-debug.cmake"
+            )
+        foreach(debug_target IN LISTS debug_targets)
+            file(RELATIVE_PATH debug_target_rel "${debug_share}" "${debug_target}")
+
+            file(READ "${debug_target}" contents)
+            string(REPLACE "${CURRENT_INSTALLED_DIR}" "\${_IMPORT_PREFIX}" contents "${contents}")
+            string(REGEX REPLACE "\\\${_IMPORT_PREFIX}/bin/([^ \";]+${EXECUTABLE_SUFFIX})" "\${_IMPORT_PREFIX}/tools/${PORT}/\\1" contents "${contents}")
+            string(REPLACE "\${_IMPORT_PREFIX}/lib" "\${_IMPORT_PREFIX}/debug/lib" contents "${contents}")
+            string(REPLACE "\${_IMPORT_PREFIX}/bin" "\${_IMPORT_PREFIX}/debug/bin" contents "${contents}")
+            file(WRITE "${release_share}/${debug_target_rel}" "${contents}")
+
+            file(REMOVE "${debug_target}")
+        endforeach()
+    endif()
+
+    #Fix ${_IMPORT_PREFIX} in cmake generated targets and configs;
+    #Since those can be renamed we have to check in every *.cmake
+    file(GLOB_RECURSE main_cmakes "${release_share}/*.cmake")
+
+    foreach(main_cmake IN LISTS main_cmakes)
+        file(READ "${main_cmake}" contents)
+        # Note: I think the following comment is no longer true, since we now require the path to be `share/blah`
+        # however, I don't know it for sure.
+        # - nimazzuc
+
+        #This correction is not correct for all cases. To make it correct for all cases it needs to consider
+        #original folder deepness to CURRENT_PACKAGES_DIR in comparison to the moved to folder deepness which
+        #is always at least (>=) 2, e.g. share/${PORT}. Currently the code assumes it is always 2 although
+        #this requirement is only true for the *Config.cmake. The targets are not required to be in the same
+        #folder as the *Config.cmake!
+        if(NOT arg_NO_PREFIX_CORRECTION)
+            string(REGEX REPLACE
+[[get_filename_component\(_IMPORT_PREFIX "\${CMAKE_CURRENT_LIST_FILE}" PATH\)(
+get_filename_component\(_IMPORT_PREFIX "\${_IMPORT_PREFIX}" PATH\))*]]
+[[get_filename_component(_IMPORT_PREFIX "${CMAKE_CURRENT_LIST_FILE}" PATH)
+get_filename_component(_IMPORT_PREFIX "${_IMPORT_PREFIX}" PATH)
+get_filename_component(_IMPORT_PREFIX "${_IMPORT_PREFIX}" PATH)]]
+                contents "${contents}") # see #1044 for details why this replacement is necessary. See #4782 why it must be a regex.
+            string(REGEX REPLACE
+[[get_filename_component\(PACKAGE_PREFIX_DIR "\${CMAKE_CURRENT_LIST_DIR}/\.\./(\.\./)*" ABSOLUTE\)]]
+[[get_filename_component(PACKAGE_PREFIX_DIR "${CMAKE_CURRENT_LIST_DIR}/../../" ABSOLUTE)]]
+                contents "${contents}")
+            string(REGEX REPLACE
+[[get_filename_component\(PACKAGE_PREFIX_DIR "\${CMAKE_CURRENT_LIST_DIR}/\.\.((\\|/)\.\.)*" ABSOLUTE\)]]
+[[get_filename_component(PACKAGE_PREFIX_DIR "${CMAKE_CURRENT_LIST_DIR}/../../" ABSOLUTE)]]
+                contents "${contents}") # This is a meson-related workaround, see https://github.com/mesonbuild/meson/issues/6955
+        endif()
+
+        #Fix wrongly absolute paths to install dir with the correct dir using ${_IMPORT_PREFIX}
+        #This happens if vcpkg built libraries are directly linked to a target instead of using
+        #an imported target for it. We could add more logic here to identify defect target files.
+        #Since the replacement here in a multi config build always requires a generator expression
+        #in front of the absoulte path to ${CURRENT_INSTALLED_DIR}. So the match should always be at
+        #least >:${CURRENT_INSTALLED_DIR}.
+        #In general the following generator expressions should be there:
+        #\$<\$<CONFIG:DEBUG>:${CURRENT_INSTALLED_DIR}/debug/lib/somelib>
+        #and/or
+        #\$<\$<NOT:\$<CONFIG:DEBUG>>:${CURRENT_INSTALLED_DIR}/lib/somelib>
+        #with ${CURRENT_INSTALLED_DIR} being fully expanded
+        string(REPLACE "${CURRENT_INSTALLED_DIR}" [[${_IMPORT_PREFIX}]] contents "${contents}")
+
+        # Patch out any remaining absolute references
+        file(TO_CMAKE_PATH "${CURRENT_PACKAGES_DIR}" cmake_current_packages_dir)
+        string(REPLACE "${CMAKE_CURRENT_PACKAGES_DIR}" [[${_IMPORT_PREFIX}]] contents "${contents}")
+
+        file(WRITE "${main_cmake}" "${contents}")
+    endforeach()
+
+    # Remove /debug/<target_path>/ if it's empty.
+    file(GLOB_RECURSE remaining_files "${debug_share}/*")
+    if(NOT remaining_files STREQUAL "")
+        file(REMOVE_RECURSE "${debug_share}")
+    endif()
+
+    # Remove /debug/share/ if it's empty.
+    file(GLOB_RECURSE remaining_files "${CURRENT_PACKAGES_DIR}/debug/share/*")
+    if(NOT remaining_files STREQUAL "")
+        file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/share")
+    endif()
+endfunction()
+
+

ports/vcpkg-cmake/README.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.

ports/vcpkg-cmake/copyright

@@ -0,0 +1,23 @@
+Copyright (c) Microsoft Corporation
+
+All rights reserved. 
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ports/vcpkg-cmake/portfile.cmake

@@ -0,0 +1,13 @@
+if(NOT TARGET_TRIPLET STREQUAL _HOST_TRIPLET)
+    message(FATAL_ERROR "vcpkg-cmake is a host-only port; please mark it as a host port in your dependencies.")
+endif()
+
+file(INSTALL
+    "${CMAKE_CURRENT_LIST_DIR}/vcpkg_cmake_configure.cmake"
+    "${CMAKE_CURRENT_LIST_DIR}/vcpkg_cmake_build.cmake"
+    "${CMAKE_CURRENT_LIST_DIR}/vcpkg_cmake_install.cmake"
+    "${CMAKE_CURRENT_LIST_DIR}/vcpkg-port-config.cmake"
+    "${CMAKE_CURRENT_LIST_DIR}/copyright"
+    DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
+
+set(VCPKG_POLICY_EMPTY_PACKAGE enabled)

ports/vcpkg-cmake/vcpkg-port-config.cmake

@@ -0,0 +1,3 @@
+include("${CMAKE_CURRENT_LIST_DIR}/vcpkg_cmake_configure.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/vcpkg_cmake_build.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/vcpkg_cmake_install.cmake")

ports/vcpkg-cmake/vcpkg.json

@@ -0,0 +1,4 @@
+{
+  "name": "vcpkg-cmake",
+  "version-date": "2021-02-26"
+}

ports/vcpkg-cmake/vcpkg_cmake_build.cmake

@@ -0,0 +1,115 @@
+#[===[.md:
+# vcpkg_cmake_build
+
+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.
+#]===]
+if(Z_VCPKG_CMAKE_BUILD_GUARD)
+    return()
+endif()
+set(Z_VCPKG_CMAKE_BUILD_GUARD ON CACHE INTERNAL "guard variable")
+
+function(vcpkg_cmake_build)
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "DISABLE_PARALLEL;ADD_BIN_TO_PATH" "TARGET;LOGFILE_BASE" "")
+
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "vcpkg_cmake_build was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+    if(NOT DEFINED arg_LOGFILE_BASE)
+        set(arg_LOGFILE_BASE "build")
+    endif()
+
+    set(build_args)
+    set(target_args)
+    set(parallel_args)
+    set(no_parallel_args)
+
+    if(Z_VCPKG_CMAKE_GENERATOR STREQUAL "Ninja")
+        set(build_args "-v") # verbose output
+        set(parallel_args "-j${VCPKG_CONCURRENCY}")
+        set(no_parallel_args "-j1")
+    elseif(Z_VCPKG_CMAKE_GENERATOR MATCHES "^Visual Studio")
+        set(build_args
+            "/p:VCPkgLocalAppDataDisabled=true"
+            "/p:UseIntelMKL=No"
+        )
+        set(parallel_args "/m")
+    elseif(Z_VCPKG_CMAKE_GENERATOR STREQUAL "NMake Makefiles")
+        # No options are currently added for nmake builds
+    else()
+        message(FATAL_ERROR "Unrecognized GENERATOR setting from vcpkg_configure_cmake(). Valid generators are: Ninja, Visual Studio, and NMake Makefiles")
+    endif()
+
+    if(DEFINED arg_TARGET)
+        set(target_args "--target" "${arg_TARGET}")
+    endif()
+
+    foreach(buildtype IN ITEMS debug release)
+        if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL buildtype)
+            if(buildtype STREQUAL "debug")
+                set(short_buildtype "dbg")
+                set(cmake_config "Debug")
+            else()
+                set(short_buildtype "rel")
+                set(cmake_config "Release")
+            endif()
+
+            message(STATUS "Building ${TARGET_TRIPLET}-${short_buildtype}")
+
+            if(arg_ADD_BIN_TO_PATH)
+                set(env_path_backup "$ENV{PATH}")
+                if(buildtype STREQUAL "debug")
+                    vcpkg_add_to_path(PREPEND "${CURRENT_INSTALLED_DIR}/debug/bin")
+                else()
+                    vcpkg_add_to_path(PREPEND "${CURRENT_INSTALLED_DIR}/bin")
+                endif()
+            endif()
+
+            if (arg_DISABLE_PARALLEL)
+                vcpkg_execute_build_process(
+                    COMMAND "${CMAKE_COMMAND}" --build . --config "${cmake_config}" ${target_args} -- ${build_args} ${no_parallel_args}
+                    WORKING_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-${short_buildtype}"
+                    LOGNAME "${arg_LOGFILE_BASE}-${TARGET_TRIPLET}-${short_buildtype}"
+                )
+            else()
+                vcpkg_execute_build_process(
+                    COMMAND "${CMAKE_COMMAND}" --build . --config "${cmake_config}" ${target_args} -- ${build_args} ${parallel_args}
+                    NO_PARALLEL_COMMAND "${CMAKE_COMMAND}" --build . --config "${cmake_config}" ${target_args} -- ${build_args} ${no_parallel_args}
+                    WORKING_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-${short_buildtype}"
+                    LOGNAME "${arg_LOGFILE_BASE}-${TARGET_TRIPLET}-${short_buildtype}"
+                )
+            endif()
+
+            if(arg_ADD_BIN_TO_PATH)
+                set(ENV{PATH} "${env_path_backup}")
+            endif()
+        endif()
+    endforeach()
+endfunction()

ports/vcpkg-cmake/vcpkg_cmake_configure.cmake

@@ -0,0 +1,391 @@
+#[===[.md:
+# vcpkg_cmake_configure
+
+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)
+#]===]
+if(Z_VCPKG_CMAKE_CONFIGURE_GUARD)
+    return()
+endif()
+set(Z_VCPKG_CMAKE_CONFIGURE_GUARD ON CACHE INTERNAL "guard variable")
+
+macro(z_vcpkg_cmake_configure_both_set_or_unset var1 var2)
+    if(DEFINED ${var1} AND NOT DEFINED ${var2})
+        message(FATAL_ERROR "If ${var1} is set, then ${var2} must be set.")
+    elseif(NOT DEFINED ${var1} AND DEFINED ${var2})
+        message(FATAL_ERROR "If ${var2} is set, then ${var1} must be set.")
+    endif()
+endmacro()
+
+function(vcpkg_cmake_configure)
+    cmake_parse_arguments(PARSE_ARGV 0 "arg"
+        "PREFER_NINJA;DISABLE_PARALLEL_CONFIGURE;WINDOWS_USE_MSBUILD;NO_CHARSET_FLAG"
+        "SOURCE_PATH;GENERATOR;LOGFILE_BASE"
+        "OPTIONS;OPTIONS_DEBUG;OPTIONS_RELEASE"
+    )
+
+    if(DEFINED CACHE{Z_VCPKG_CMAKE_GENERATOR})
+        message(WARNING "vcpkg_cmake_configure already called; this function should only be called once.")
+    endif()
+
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "vcpkg_cmake_buildsystem_build was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+    if(NOT DEFINED arg_SOURCE_PATH)
+        message(FATAL_ERROR "SOURCE_PATH must be set")
+    endif()
+    if(NOT DEFINED arg_LOGFILE_BASE)
+        set(arg_LOGFILE_BASE "config")
+    endif()
+
+    if(CMAKE_HOST_WIN32)
+        if(DEFINED ENV{PROCESSOR_ARCHITEW6432})
+            set(host_architecture "$ENV{PROCESSOR_ARCHITEW6432}")
+        else()
+            set(host_architecture "$ENV{PROCESSOR_ARCHITECTURE}")
+        endif()
+    endif()
+
+    set(ninja_can_be_used ON) # Ninja as generator
+    set(ninja_host ON) # Ninja as parallel configurator
+
+    if(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
+        set(targetting_uwp ON)
+    endif()
+
+    if(host_architecture STREQUAL "x86")
+        # Prebuilt ninja binaries are only provided for x64 hosts
+        set(ninja_can_be_used OFF)
+        set(ninja_host OFF)
+    elseif(targetting_uwp)
+        # Ninja and MSBuild have many differences when targetting UWP, so use MSBuild to maximize existing compatibility
+        set(ninja_can_be_used OFF)
+    endif()
+
+    set(generator)
+    if(DEFINED arg_GENERATOR)
+        set(generator "${arg_GENERATOR}")
+    elseif(arg_WINDOWS_USE_MSBUILD OR NOT ninja_can_be_used)
+        if(VCPKG_PLATFORM_TOOLSET STREQUAL "v120")
+            if(VCPKG_TARGET_ARCHITECTURE STREQUAL "x86")
+                set(generator "Visual Studio 12 2013")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "x64")
+                set(generator "Visual Studio 12 2013 Win64")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "arm")
+                set(generator "Visual Studio 12 2013 ARM")
+            endif()
+        elseif(VCPKG_PLATFORM_TOOLSET STREQUAL "v140")
+            if(VCPKG_TARGET_ARCHITECTURE STREQUAL "x86")
+                set(generator "Visual Studio 14 2015")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "x64")
+                set(generator "Visual Studio 14 2015 Win64")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "arm")
+                set(generator "Visual Studio 14 2015 ARM")
+            endif()
+        elseif(VCPKG_PLATFORM_TOOLSET STREQUAL "v141")
+            if(VCPKG_TARGET_ARCHITECTURE STREQUAL "x86")
+                set(generator "Visual Studio 15 2017")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "x64")
+                set(generator "Visual Studio 15 2017 Win64")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "arm")
+                set(generator "Visual Studio 15 2017 ARM")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "arm64")
+                set(generator "Visual Studio 15 2017")
+                set(arch "ARM64")
+            endif()
+        elseif(VCPKG_PLATFORM_TOOLSET STREQUAL "v142")
+            set(generator "Visual Studio 16 2019")
+            if(VCPKG_TARGET_ARCHITECTURE STREQUAL "x86")
+                set(arch "Win32")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "x64")
+                set(arch "x64")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "arm")
+                set(arch "ARM")
+            elseif(VCPKG_TARGET_ARCHITECTURE STREQUAL "arm64")
+                set(arch "ARM64")
+            else()
+                set(generator)
+            endif()
+        endif()
+    else()
+        set(generator "Ninja")
+    endif()
+
+    if(NOT DEFINED generator)
+        if(NOT VCPKG_CMAKE_SYSTEM_NAME)
+            set(VCPKG_CMAKE_SYSTEM_NAME Windows)
+        endif()
+        message(FATAL_ERROR "Unable to determine appropriate generator for: "
+            "${VCPKG_CMAKE_SYSTEM_NAME}-${VCPKG_TARGET_ARCHITECTURE}-${VCPKG_PLATFORM_TOOLSET}")
+    endif()
+
+    # If we use Ninja, make sure it's on PATH
+    if(generator STREQUAL "Ninja" AND NOT DEFINED ENV{VCPKG_FORCE_SYSTEM_BINARIES})
+        vcpkg_find_acquire_program(NINJA)
+        get_filename_component(ninja_path "${NINJA}" DIRECTORY)
+        vcpkg_add_to_path("${ninja_path}")
+        list(APPEND arg_OPTIONS "-DCMAKE_MAKE_PROGRAM=${NINJA}")
+    endif()
+
+    file(REMOVE_RECURSE
+        "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel"
+        "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg")
+
+    if(DEFINED VCPKG_CMAKE_SYSTEM_NAME)
+        list(APPEND arg_OPTIONS "-DCMAKE_SYSTEM_NAME=${VCPKG_CMAKE_SYSTEM_NAME}")
+        if(targetting_uwp AND NOT DEFINED VCPKG_CMAKE_SYSTEM_VERSION)
+            set(VCPKG_CMAKE_SYSTEM_VERSION 10.0)
+        elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "Android" AND NOT DEFINED VCPKG_CMAKE_SYSTEM_VERSION)
+            set(VCPKG_CMAKE_SYSTEM_VERSION 21)
+        endif()
+    endif()
+
+    if(DEFINED VCPKG_CMAKE_SYSTEM_VERSION)
+        list(APPEND arg_OPTIONS "-DCMAKE_SYSTEM_VERSION=${VCPKG_CMAKE_SYSTEM_VERSION}")
+    endif()
+
+    if(VCPKG_LIBRARY_LINKAGE STREQUAL "dynamic")
+        list(APPEND arg_OPTIONS "-DBUILD_SHARED_LIBS=ON")
+    elseif(VCPKG_LIBRARY_LINKAGE STREQUAL "static")
+        list(APPEND arg_OPTIONS "-DBUILD_SHARED_LIBS=OFF")
+    else()
+        message(FATAL_ERROR
+            "Invalid setting for VCPKG_LIBRARY_LINKAGE: \"${VCPKG_LIBRARY_LINKAGE}\". "
+            "It must be \"static\" or \"dynamic\"")
+    endif()
+
+    z_vcpkg_cmake_configure_both_set_or_unset(VCPKG_CXX_FLAGS_DEBUG VCPKG_C_FLAGS_DEBUG)
+    z_vcpkg_cmake_configure_both_set_or_unset(VCPKG_CXX_FLAGS_RELEASE VCPKG_C_FLAGS_RELASE)
+    z_vcpkg_cmake_configure_both_set_or_unset(VCPKG_CXX_FLAGS VCPKG_C_FLAGS)
+
+    set(VCPKG_SET_CHARSET_FLAG ON)
+    if(arg_NO_CHARSET_FLAG)
+        set(VCPKG_SET_CHARSET_FLAG OFF)
+    endif()
+
+    if(NOT DEFINED VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
+        if(NOT DEFINED VCPKG_CMAKE_SYSTEM_NAME OR _TARGETTING_UWP)
+            set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "${SCRIPTS}/toolchains/windows.cmake")
+        elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "Linux")
+            set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "${SCRIPTS}/toolchains/linux.cmake")
+        elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "Android")
+            set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "${SCRIPTS}/toolchains/android.cmake")
+        elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "Darwin")
+            set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "${SCRIPTS}/toolchains/osx.cmake")
+        elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "iOS")
+            set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "${SCRIPTS}/toolchains/ios.cmake")
+        elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "FreeBSD")
+            set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "${SCRIPTS}/toolchains/freebsd.cmake")
+        elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "OpenBSD")
+            set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "${SCRIPTS}/toolchains/openbsd.cmake")
+        elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "MinGW")
+            set(VCPKG_CHAINLOAD_TOOLCHAIN_FILE "${SCRIPTS}/toolchains/mingw.cmake")
+        endif()
+    endif()
+
+
+    list(APPEND arg_OPTIONS
+        "-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=${VCPKG_CHAINLOAD_TOOLCHAIN_FILE}"
+        "-DVCPKG_TARGET_TRIPLET=${TARGET_TRIPLET}"
+        "-DVCPKG_SET_CHARSET_FLAG=${VCPKG_SET_CHARSET_FLAG}"
+        "-DVCPKG_PLATFORM_TOOLSET=${VCPKG_PLATFORM_TOOLSET}"
+        "-DCMAKE_EXPORT_NO_PACKAGE_REGISTRY=ON"
+        "-DCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY=ON"
+        "-DCMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY=ON"
+        "-DCMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP=TRUE"
+        "-DCMAKE_VERBOSE_MAKEFILE=ON"
+        "-DVCPKG_APPLOCAL_DEPS=OFF"
+        "-DCMAKE_TOOLCHAIN_FILE=${SCRIPTS}/buildsystems/vcpkg.cmake"
+        "-DCMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION=ON"
+        "-DVCPKG_CXX_FLAGS=${VCPKG_CXX_FLAGS}"
+        "-DVCPKG_CXX_FLAGS_RELEASE=${VCPKG_CXX_FLAGS_RELEASE}"
+        "-DVCPKG_CXX_FLAGS_DEBUG=${VCPKG_CXX_FLAGS_DEBUG}"
+        "-DVCPKG_C_FLAGS=${VCPKG_C_FLAGS}"
+        "-DVCPKG_C_FLAGS_RELEASE=${VCPKG_C_FLAGS_RELEASE}"
+        "-DVCPKG_C_FLAGS_DEBUG=${VCPKG_C_FLAGS_DEBUG}"
+        "-DVCPKG_CRT_LINKAGE=${VCPKG_CRT_LINKAGE}"
+        "-DVCPKG_LINKER_FLAGS=${VCPKG_LINKER_FLAGS}"
+        "-DVCPKG_LINKER_FLAGS_RELEASE=${VCPKG_LINKER_FLAGS_RELEASE}"
+        "-DVCPKG_LINKER_FLAGS_DEBUG=${VCPKG_LINKER_FLAGS_DEBUG}"
+        "-DVCPKG_TARGET_ARCHITECTURE=${VCPKG_TARGET_ARCHITECTURE}"
+        "-DCMAKE_INSTALL_LIBDIR:STRING=lib"
+        "-DCMAKE_INSTALL_BINDIR:STRING=bin"
+        "-D_VCPKG_ROOT_DIR=${VCPKG_ROOT_DIR}"
+        "-D_VCPKG_INSTALLED_DIR=${_VCPKG_INSTALLED_DIR}"
+        "-DVCPKG_MANIFEST_INSTALL=OFF"
+    )
+
+    if(DEFINED arch)
+        list(APPEND arg_OPTIONS "-A${arch}")
+    endif()
+
+    # Sets configuration variables for macOS builds
+    foreach(config_var IN ITEMS INSTALL_NAME_DIR OSX_DEPLOYMENT_TARGET OSX_SYSROOT OSX_ARCHITECTURES)
+        if(DEFINED VCPKG_${config_var})
+            list(APPEND arg_OPTIONS "-DCMAKE_${config_var}=${VCPKG_${config_var}}")
+        endif()
+    endforeach()
+
+    if(ninja_host AND CMAKE_HOST_WIN32 AND NOT arg_DISABLE_PARALLEL_CONFIGURE)
+        list(APPEND arg_OPTIONS "-DCMAKE_DISABLE_SOURCE_CHANGES=ON")
+
+        vcpkg_find_acquire_program(NINJA)
+
+        if(NOT DEFINED ninja_path)
+            # if ninja_path was defined above, we've already done this
+            get_filename_component(ninja_path "${NINJA}" DIRECTORY)
+            vcpkg_add_to_path("${ninja_path}")
+        endif()
+
+        #parallelize the configure step
+        set(parallel_configure_contents
+            "rule CreateProcess\n  command = $process\n\n"
+        )
+
+        if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "release")
+            set(line "build ../CMakeCache.txt: CreateProcess\n  ")
+            string(APPEND line "process = \"${CMAKE_COMMAND}\" -S \"${arg_SOURCE_PATH}\" -B .. ")
+
+            if(DEFINED arg_OPTIONS AND NOT arg_OPTIONS STREQUAL "")
+                list(JOIN arg_OPTIONS "\" \"" options)
+                string(APPEND line "\"${options}\" ")
+            endif()
+            if(DEFINED arg_OPTIONS_RELEASE AND NOT arg_OPTIONS_RELEASE STREQUAL "")
+                list(JOIN arg_OPTIONS_RELEASE "\" \"" options_rel)
+                string(APPEND line "\"${options_rel}\" ")
+            endif()
+            string(APPEND line "-G \"${generator}\" ")
+            string(APPEND line "\"-DCMAKE_BUILD_TYPE=Release\" ")
+            string(APPEND line "\"-DCMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}\"")
+            string(APPEND parallel_configure_contents "${line}\n\n")
+        endif()
+        if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
+            set(line "build ../../${TARGET_TRIPLET}-dbg/CMakeCache.txt: CreateProcess\n  ")
+            string(APPEND line "process = \"${CMAKE_COMMAND}\" -S \"${arg_SOURCE_PATH}\" -B \"../../${TARGET_TRIPLET}-dbg\" ")
+
+            if(DEFINED arg_OPTIONS AND NOT arg_OPTIONS STREQUAL "")
+                list(JOIN arg_OPTIONS "\" \"" options)
+                string(APPEND line "\"${options}\" ")
+            endif()
+            if(DEFINED arg_OPTIONS_DEBUG AND NOT arg_OPTIONS_DEBUG STREQUAL "")
+                list(JOIN arg_OPTIONS_DEBUG "\" \"" options_dbg)
+                string(APPEND line "\"${options_dbg}\" ")
+            endif()
+            string(APPEND line "-G \"${generator}\" ")
+            string(APPEND line "\"-DCMAKE_BUILD_TYPE=Debug\" ")
+            string(APPEND line "\"-DCMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}/debug\"")
+            string(APPEND parallel_configure_contents "${line}\n\n")
+        endif()
+
+        file(MAKE_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel/vcpkg-parallel-configure")
+        file(WRITE "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel/vcpkg-parallel-configure/build.ninja" "${parallel_configure_contents}")
+
+        message(STATUS "Configuring ${TARGET_TRIPLET}")
+        vcpkg_execute_required_process(
+            COMMAND ninja -v
+            WORKING_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel/vcpkg-parallel-configure"
+            LOGNAME "${arg_LOGFILE_BASE}-${TARGET_TRIPLET}"
+        )
+    else()
+        if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
+            message(STATUS "Configuring ${TARGET_TRIPLET}-dbg")
+            file(MAKE_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg")
+            vcpkg_execute_required_process(
+                COMMAND
+                    "${CMAKE_COMMAND}" "${arg_SOURCE_PATH}"
+                    ${arg_OPTIONS}
+                    ${arg_OPTIONS_DEBUG}
+                    -G "${generator}"
+                    "-DCMAKE_BUILD_TYPE=Debug"
+                    "-DCMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}/debug"
+                WORKING_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg"
+                LOGNAME "${arg_LOGFILE_BASE}-${TARGET_TRIPLET}-dbg"
+            )
+        endif()
+
+        if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "release")
+            message(STATUS "Configuring ${TARGET_TRIPLET}-rel")
+            file(MAKE_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel")
+            vcpkg_execute_required_process(
+                COMMAND
+                    "${CMAKE_COMMAND}" "${arg_SOURCE_PATH}"
+                    ${arg_OPTIONS}
+                    ${arg_OPTIONS_RELEASE}
+                    -G "${generator}"
+                    "-DCMAKE_BUILD_TYPE=Release"
+                    "-DCMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}"
+                WORKING_DIRECTORY "${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel"
+                LOGNAME "${arg_LOGFILE_BASE}-rel"
+            )
+        endif()
+    endif()
+
+    set(Z_VCPKG_CMAKE_GENERATOR "${generator}" CACHE INTERNAL "The generator which was used to configure CMake.")
+endfunction()

ports/vcpkg-cmake/vcpkg_cmake_install.cmake

@@ -0,0 +1,46 @@
+#[===[.md:
+# vcpkg_cmake_install
+
+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)
+#]===]
+if(Z_VCPKG_CMAKE_INSTALL_GUARD)
+    return()
+endif()
+set(Z_VCPKG_CMAKE_INSTALL_GUARD ON CACHE INTERNAL "guard variable")
+
+function(vcpkg_cmake_install)
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "DISABLE_PARALLEL;ADD_BIN_TO_PATH" "" "")
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "vcpkg_cmake_install was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+
+    set(args)
+    foreach(arg IN ITEMS DISABLE_PARALLEL ADD_BIN_TO_PATH)
+        if(arg_${arg})
+            list(APPEND args "${arg}")
+        endif()
+    endforeach()
+
+    vcpkg_cmake_build(
+        ${args}
+        LOGFILE_BASE install
+        TARGET install
+    )
+endfunction()

scripts/ci.baseline.txt

@@ -27,8 +27,24 @@
 ##    x86-windows
 ##
 
-
 # Add new items alphabetically
+
+# script ports
+vcpkg-cmake:arm64-windows=fail
+vcpkg-cmake:arm-uwp=fail
+vcpkg-cmake:x64-uwp=fail
+vcpkg-cmake:x64-windows-static=fail
+vcpkg-cmake:x64-windows-static-md=fail
+vcpkg-cmake:x86-windows=fail
+
+vcpkg-cmake-config:arm64-windows=fail
+vcpkg-cmake-config:arm-uwp=fail
+vcpkg-cmake-config:x64-uwp=fail
+vcpkg-cmake-config:x64-windows-static=fail
+vcpkg-cmake-config:x64-windows-static-md=fail
+vcpkg-cmake-config:x86-windows=fail
+
+# other ports
 # Cross compiling CI machine cannot run gen_test_char to generate apr_escape_test_char.h
 apr:arm64-windows=fail
 # Requires ATL for ARM64 to be installed in CI

scripts/cmake/vcpkg_apply_patches.cmake

@@ -1,9 +1,10 @@
+# DEPRECATED: in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
+
 #[===[.md
 # vcpkg_apply_patches
 
-Apply a set of patches to a source tree. This function is deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
+Apply a set of patches to a source tree.
 
-## Usage
 ```cmake
 vcpkg_apply_patches(
     SOURCE_PATH <${SOURCE_PATH}>
@@ -11,63 +12,22 @@ vcpkg_apply_patches(
     PATCHES <patch1.patch>...
 )
 ```
-
-## Parameters
-### SOURCE_PATH
-The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
-
-### PATCHES
-A list of patches that are applied to the source tree.
-
-Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
-
-### QUIET
-Disables the warning message upon failure.
-
-This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
-
-## Examples
-
-* [libbson](https://github.com/Microsoft/vcpkg/blob/master/ports/libbson/portfile.cmake)
-* [gdal](https://github.com/Microsoft/vcpkg/blob/master/ports/gdal/portfile.cmake)
 #]===]
 
-include(vcpkg_execute_in_download_mode)
-
 function(vcpkg_apply_patches)
-    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
+    z_vcpkg_deprecation_message("vcpkg_apply_patches has been deprecated in favor of the `PATCHES` argument to `vcpkg_from_*`.")
-    cmake_parse_arguments(PARSE_ARGV 0 _ap "QUIET" "SOURCE_PATH" "PATCHES")
 
-    find_program(GIT NAMES git git.cmd)
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "QUIET" "SOURCE_PATH" "PATCHES")
-    if(DEFINED ENV{GIT_CONFIG_NOSYSTEM})
+
-        set(GIT_CONFIG_NOSYSTEM_BACKUP "$ENV{GIT_CONFIG_NOSYSTEM}")
+    if(arg_QUIET)
+        set(quiet "QUIET")
     else()
-        unset(GIT_CONFIG_NOSYSTEM_BACKUP)
+        set(quiet)
     endif()
-    set(ENV{GIT_CONFIG_NOSYSTEM} 1)
-    set(PATCHNUM 0)
-    foreach(PATCH ${_ap_PATCHES})
-        get_filename_component(ABSOLUTE_PATCH "${PATCH}" ABSOLUTE BASE_DIR "${CURRENT_PORT_DIR}")
-        message(STATUS "Applying patch ${PATCH}")
-        set(LOGNAME patch-${TARGET_TRIPLET}-${PATCHNUM})
-        vcpkg_execute_in_download_mode(
-            COMMAND ${GIT} -c core.longpaths=true -c core.autocrlf=false --work-tree=. --git-dir=.git apply "${ABSOLUTE_PATCH}" --ignore-whitespace --whitespace=nowarn --verbose
-            OUTPUT_FILE ${CURRENT_BUILDTREES_DIR}/${LOGNAME}-out.log
-            ERROR_VARIABLE error
-            WORKING_DIRECTORY ${_ap_SOURCE_PATH}
-            RESULT_VARIABLE error_code
-        )
-        file(WRITE "${CURRENT_BUILDTREES_DIR}/${LOGNAME}-err.log" "${error}")
 
-        if(error_code AND NOT _ap_QUIET)
+    z_vcpkg_apply_patches(
-            message(FATAL_ERROR "Applying patch failed. ${error}")
+        SOURCE_PATH "${arg_SOURCE_PATH}"
-        endif()
+        ${quiet}
-
+        PATCHES ${arg_PATCHES}
-        math(EXPR PATCHNUM "${PATCHNUM}+1")
+    )
-    endforeach()
-    if(DEFINED GIT_CONFIG_NOSYSTEM_BACKUP)
-        set(ENV{GIT_CONFIG_NOSYSTEM} "${GIT_CONFIG_NOSYSTEM_BACKUP}")
-    else()
-        unset(ENV{GIT_CONFIG_NOSYSTEM})
-    endif()
 endfunction()

scripts/cmake/vcpkg_build_cmake.cmake

@@ -1,6 +1,8 @@
 #[===[.md:
 # vcpkg_build_cmake
 
+**This function has been deprecated in favor of `vcpkg_cmake_build` from the vcpkg-cmake port.**
+
 Build a cmake project.
 
 ## Usage:
@@ -33,34 +35,44 @@ You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) functi
 #]===]
 
 function(vcpkg_build_cmake)
-    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
+    cmake_parse_arguments(PARSE_ARGV 0 "arg"
-    cmake_parse_arguments(PARSE_ARGV 0 _bc "DISABLE_PARALLEL;ADD_BIN_TO_PATH" "TARGET;LOGFILE_ROOT" "")
+        "DISABLE_PARALLEL;ADD_BIN_TO_PATH;Z_VCPKG_DISABLE_DEPRECATION_MESSAGE"
+        "TARGET;LOGFILE_ROOT"
+        ""
+    )
 
-    if(NOT _bc_LOGFILE_ROOT)
+    if(NOT arg_Z_VCPKG_DISABLE_DEPRECATION_MESSAGE)
-        set(_bc_LOGFILE_ROOT "build")
+        message(DEPRECATION "vcpkg_build_cmake has been deprecated in favor of vcpkg_cmake_build from the vcpkg-cmake port.")
+    endif()
+    if(Z_VCPKG_CMAKE_BUILD_GUARD)
+        message(FATAL_ERROR "The ${PORT} port already depends on vcpkg-cmake; using both vcpkg-cmake and vcpkg_build_cmake in the same port is unsupported.")
+    endif()
+
+    if(NOT arg_LOGFILE_ROOT)
+        set(arg_LOGFILE_ROOT "build")
     endif()
 
     set(PARALLEL_ARG)
     set(NO_PARALLEL_ARG)
 
-    if(_VCPKG_CMAKE_GENERATOR MATCHES "Ninja")
+    if(Z_VCPKG_CMAKE_GENERATOR MATCHES "Ninja")
         set(BUILD_ARGS "-v") # verbose output
         set(PARALLEL_ARG "-j${VCPKG_CONCURRENCY}")
         set(NO_PARALLEL_ARG "-j1")
-    elseif(_VCPKG_CMAKE_GENERATOR MATCHES "Visual Studio")
+    elseif(Z_VCPKG_CMAKE_GENERATOR MATCHES "Visual Studio")
         set(BUILD_ARGS
             "/p:VCPkgLocalAppDataDisabled=true"
             "/p:UseIntelMKL=No"
         )
         set(PARALLEL_ARG "/m")
-    elseif(_VCPKG_CMAKE_GENERATOR MATCHES "NMake")
+    elseif(Z_VCPKG_CMAKE_GENERATOR MATCHES "NMake")
         # No options are currently added for nmake builds
     else()
         message(FATAL_ERROR "Unrecognized GENERATOR setting from vcpkg_configure_cmake(). Valid generators are: Ninja, Visual Studio, and NMake Makefiles")
     endif()
 
-    if(_bc_TARGET)
+    if(arg_TARGET)
-        set(TARGET_PARAM "--target" ${_bc_TARGET})
+        set(TARGET_PARAM "--target" ${arg_TARGET})
     else()
         set(TARGET_PARAM)
     endif()
@@ -77,7 +89,7 @@ function(vcpkg_build_cmake)
 
             message(STATUS "Building ${TARGET_TRIPLET}-${SHORT_BUILDTYPE}")
 
-            if(_bc_ADD_BIN_TO_PATH)
+            if(arg_ADD_BIN_TO_PATH)
                 set(_BACKUP_ENV_PATH "$ENV{PATH}")
                 if(BUILDTYPE STREQUAL "debug")
                     vcpkg_add_to_path(PREPEND "${CURRENT_INSTALLED_DIR}/debug/bin")
@@ -86,22 +98,22 @@ function(vcpkg_build_cmake)
                 endif()
             endif()
 
-            if (_bc_DISABLE_PARALLEL)
+            if (arg_DISABLE_PARALLEL)
                 vcpkg_execute_build_process(
                     COMMAND ${CMAKE_COMMAND} --build . --config ${CONFIG} ${TARGET_PARAM} -- ${BUILD_ARGS} ${NO_PARALLEL_ARG}
                     WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-${SHORT_BUILDTYPE}
-                    LOGNAME "${_bc_LOGFILE_ROOT}-${TARGET_TRIPLET}-${SHORT_BUILDTYPE}"
+                    LOGNAME "${arg_LOGFILE_ROOT}-${TARGET_TRIPLET}-${SHORT_BUILDTYPE}"
                 )
             else()
                 vcpkg_execute_build_process(
                     COMMAND ${CMAKE_COMMAND} --build . --config ${CONFIG} ${TARGET_PARAM} -- ${BUILD_ARGS} ${PARALLEL_ARG}
                     NO_PARALLEL_COMMAND ${CMAKE_COMMAND} --build . --config ${CONFIG} ${TARGET_PARAM} -- ${BUILD_ARGS} ${NO_PARALLEL_ARG}
                     WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-${SHORT_BUILDTYPE}
-                    LOGNAME "${_bc_LOGFILE_ROOT}-${TARGET_TRIPLET}-${SHORT_BUILDTYPE}"
+                    LOGNAME "${arg_LOGFILE_ROOT}-${TARGET_TRIPLET}-${SHORT_BUILDTYPE}"
                 )
             endif()
 
-            if(_bc_ADD_BIN_TO_PATH)
+            if(arg_ADD_BIN_TO_PATH)
                 set(ENV{PATH} "${_BACKUP_ENV_PATH}")
             endif()
         endif()

scripts/cmake/vcpkg_check_features.cmake

@@ -2,53 +2,43 @@
 # vcpkg_check_features
 Check if one or more features are a part of a package installation.
 
-## Usage
 ```cmake
 vcpkg_check_features(
-  OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>
+    OUT_FEATURE_OPTIONS <out-var>
-  [FEATURES
+    [PREFIX <prefix>]
-    <cuda> <WITH_CUDA>
+    [FEATURES
-    [<opencv> <WITH_OPENCV>]
+        [<feature-name> <feature-var>]...
-    ...]
+        ]
-  [INVERTED_FEATURES
+    [INVERTED_FEATURES
-    <cuda> <IGNORE_PACKAGE_CUDA>
+        [<feature-name> <feature-var>]...
-    [<opencv> <IGNORE_PACKAGE_OPENCV>]
+        ]
-    ...]
 )
 ```
-`vcpkg_check_features()` accepts these parameters:
 
-* `OUT_FEATURE_OPTIONS`:
+The `<out-var>` should be set to `FEATURE_OPTIONS` by convention.
-  An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS`
-  and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`).
 
-  This should be set to `FEATURE_OPTIONS` by convention.
+`vcpkg_check_features()` will:
 
-* `FEATURES`:
+- for each `<feature-name>` passed in `FEATURES`:
-  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.
+    - if the feature is set, add `-D<feature-var>=ON` to `<out-var>`,
-  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
+      and set `<prefix>_<feature-var>` to ON.
+    - if the feature is not set, add `-D<feature-var>=OFF` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to OFF.
+- for each `<feature-name>` passed in `INVERTED_FEATURES`:
+    - if the feature is set, add `-D<feature-var>=OFF` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to OFF.
+    - if the feature is not set, add `-D<feature-var>=ON` to `<out-var>`,
+      and set `<prefix>_<feature-var>` to ON.
 
-    * `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
+If `<prefix>` is not passed, then the feature vars set are simply `<feature-var>`,
-    * `-D<OPTION_NAME>=OFF`, otherwise.
+not `_<feature-var>`.
 
-* `INVERTED_FEATURES`:
+If `INVERTED_FEATURES` is not passed, then the `FEATURES` keyword is optional.
-  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.
+This behavior is deprecated.
-  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:
-
-    * `-D<OPTION_NAME>=OFF`, if a feature is specified for installation,
-    * `-D<OPTION_NAME>=ON`, otherwise.
-
-
-## Notes
-
-The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used.
-
-At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call.
-
-Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication.
-If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists,
-two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
 
+If the same `<feature-var>` is passed multiple times,
+then `vcpkg_check_features` will cause a fatal error,
+since that is a bug.
 
 ## Examples
 
@@ -59,18 +49,18 @@ $ ./vcpkg install mimalloc[asm,secure]
 
 # ports/mimalloc/portfile.cmake
 vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
-  # Keyword FEATURES is optional if INVERTED_FEATURES are not used
+    FEATURES
-    asm       MI_SEE_ASM
+        asm       MI_SEE_ASM
-    override  MI_OVERRIDE
+        override  MI_OVERRIDE
-    secure    MI_SECURE
+        secure    MI_SECURE
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
+    SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
+    PREFER_NINJA
-  OPTIONS
+    OPTIONS
-    # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
+        # Expands to "-DMI_SEE_ASM=ON;-DMI_OVERRIDE=OFF;-DMI_SECURE=ON"
-    ${FEATURE_OPTIONS}
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -80,18 +70,18 @@ vcpkg_configure_cmake(
 $ ./vcpkg install cpprestsdk[websockets]
 
 # ports/cpprestsdk/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+vcpkg_check_features(
-  INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
+    INVERTED_FEATURES
-    brotli      CPPREST_EXCLUDE_BROTLI
+        brotli      CPPREST_EXCLUDE_BROTLI
-    websockets  CPPREST_EXCLUDE_WEBSOCKETS
+        websockets  CPPREST_EXCLUDE_WEBSOCKETS
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
+    SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
+    PREFER_NINJA
-  OPTIONS
+    OPTIONS
-    # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
+        # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON;-DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
-    ${FEATURE_OPTIONS}
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -101,18 +91,19 @@ vcpkg_configure_cmake(
 $ ./vcpkg install pcl[cuda]
 
 # ports/pcl/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+vcpkg_check_features(
-    cuda  WITH_CUDA
+    FEATURES
-    cuda  BUILD_CUDA
+        cuda  WITH_CUDA
-    cuda  BUILD_GPU
+        cuda  BUILD_CUDA
+        cuda  BUILD_GPU
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
+    SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
+    PREFER_NINJA
-  OPTIONS
+    OPTIONS
-    # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
+        # Expands to "-DWITH_CUDA=ON;-DBUILD_CUDA=ON;-DBUILD_GPU=ON"
-    ${FEATURE_OPTIONS}
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -122,19 +113,19 @@ vcpkg_configure_cmake(
 $ ./vcpkg install rocksdb[tbb]
 
 # ports/rocksdb/portfile.cmake
-vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+vcpkg_check_features(
-  FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
+    FEATURES
-    tbb   WITH_TBB
+        tbb   WITH_TBB
-  INVERTED_FEATURES
+    INVERTED_FEATURES
-    tbb   ROCKSDB_IGNORE_PACKAGE_TBB
+        tbb   ROCKSDB_IGNORE_PACKAGE_TBB
 )
 
 vcpkg_configure_cmake(
-  SOURCE_PATH ${SOURCE_PATH}
+    SOURCE_PATH ${SOURCE_PATH}
-  PREFER_NINJA
+    PREFER_NINJA
-  OPTIONS
+    OPTIONS
-    # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
+        # Expands to "-DWITH_TBB=ON;-DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
-    ${FEATURE_OPTIONS}
+        ${FEATURE_OPTIONS}
 )
 ```
 
@@ -145,52 +136,98 @@ vcpkg_configure_cmake(
 * [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
 #]===]
 
-function(vcpkg_check_features)
+function(z_vcpkg_check_features_last_feature out_var features_name features_list)
-    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
+    list(LENGTH features_list features_length)
-    cmake_parse_arguments(PARSE_ARGV 0 _vcf "" "OUT_FEATURE_OPTIONS" "FEATURES;INVERTED_FEATURES")
+    math(EXPR features_length_mod_2 "${features_length} % 2")
-
+    if(NOT features_length_mod_2 EQUAL 0)
-    if (NOT DEFINED _vcf_OUT_FEATURE_OPTIONS)
+        message(FATAL_ERROR "vcpkg_check_features has an incorrect number of arguments to ${features_name}")
-        message(FATAL_ERROR "OUT_FEATURE_OPTIONS must be specified.")
     endif()
 
-    macro(_check_features _vcf_ARGUMENT _set_if _set_else)
+    math(EXPR last_feature "${features_length} / 2 - 1")
-        list(LENGTH ${_vcf_ARGUMENT} FEATURES_SET_LEN)
+    set("${out_var}" "${last_feature}" PARENT_SCOPE)
-        math(EXPR _vcf_INCORRECT_ARGN "${FEATURES_SET_LEN} % 2")
+endfunction()
-        if(_vcf_INCORRECT_ARGN)
-            message(FATAL_ERROR "Called with incorrect number of arguments.")
-        endif()
 
-        set(_vcf_IS_FEATURE_NAME_ARG ON)
+function(z_vcpkg_check_features_get_feature idx features_list out_feature_name out_feature_var)
-        foreach(_vcf_ARG ${${_vcf_ARGUMENT}})
+    math(EXPR feature_name_idx "${idx} * 2")
-            if(_vcf_IS_FEATURE_NAME_ARG)
+    math(EXPR feature_var_idx "${feature_name_idx} + 1")
-                set(_vcf_FEATURE_NAME ${_vcf_ARG})
+
-                if(NOT ${_vcf_FEATURE_NAME} IN_LIST ALL_FEATURES)
+    list(GET features_list "${feature_name_idx}" feature_name)
-                    message(FATAL_ERROR "Unknown feature: ${_vcf_FEATURE_NAME}")
+    list(GET features_list "${feature_var_idx}" feature_var)
-                endif()
+
-                set(_vcf_IS_FEATURE_NAME_ARG OFF)
+    set("${out_feature_name}" "${feature_name}" PARENT_SCOPE)
+    set("${out_feature_var}" "${feature_var}" PARENT_SCOPE)
+endfunction()
+
+function(vcpkg_check_features)
+    cmake_parse_arguments(
+        PARSE_ARGV 0 "arg"
+        ""
+        "OUT_FEATURE_OPTIONS;PREFIX"
+        "FEATURES;INVERTED_FEATURES"
+    )
+
+    if(NOT DEFINED arg_OUT_FEATURE_OPTIONS)
+        message(FATAL_ERROR "OUT_FEATURE_OPTIONS must be defined.")
+    endif()
+    if(NOT DEFINED arg_PREFIX)
+        set(prefix "")
+    else()
+        set(prefix "${arg_PREFIX}_")
+    endif()
+
+    set(feature_options)
+    set(feature_variables)
+
+    if(NOT DEFINED arg_FEATURES AND NOT DEFINED arg_INVERTED_FEATURES)
+        message(DEPRECATION
+"calling `vcpkg_check_features` without the `FEATURES` keyword has been deprecated.
+    Please add the `FEATURES` keyword to the call.")
+        set(arg_FEATURES "${arg_UNPARSED_ARGUMENTS}")
+    elseif(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "vcpkg_check_features called with unknown arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+
+
+
+    z_vcpkg_check_features_last_feature(last_feature "FEATURES" "${arg_FEATURES}")
+    if(last_feature GREATER_EQUAL 0)
+        foreach(feature_pair_idx RANGE "${last_feature}")
+            z_vcpkg_check_features_get_feature("${feature_pair_idx}" "${arg_FEATURES}" feature_name feature_var)
+
+            list(APPEND feature_variables "${feature_var}")
+            if(feature_name IN_LIST FEATURES)
+                list(APPEND feature_options "-D${feature_var}=ON")
+                set("${prefix}${feature_var}" ON PARENT_SCOPE)
             else()
-                set(_vcf_FEATURE_VARIABLE ${_vcf_ARG})
+                list(APPEND feature_options "-D${feature_var}=OFF")
-                if(${_vcf_FEATURE_NAME} IN_LIST FEATURES)
+                set("${prefix}${feature_var}" OFF PARENT_SCOPE)
-                    list(APPEND _vcf_FEATURE_OPTIONS "-D${_vcf_FEATURE_VARIABLE}=${_set_if}")
-                    set(${_vcf_FEATURE_VARIABLE} "${_set_if}" PARENT_SCOPE)
-                else()
-                    list(APPEND _vcf_FEATURE_OPTIONS "-D${_vcf_FEATURE_VARIABLE}=${_set_else}")
-                    set(${_vcf_FEATURE_VARIABLE} "${_set_else}" PARENT_SCOPE)
-                endif()
-                set(_vcf_IS_FEATURE_NAME_ARG ON)
             endif()
         endforeach()
-    endmacro()
-
-    set(_vcf_FEATURE_OPTIONS)
-
-    if (DEFINED _vcf_FEATURES OR DEFINED _vcf_INVERTED_FEATURES)
-        _check_features(_vcf_FEATURES ON OFF)
-        _check_features(_vcf_INVERTED_FEATURES OFF ON)
-    else()
-        # Skip arguments that correspond to OUT_FEATURE_OPTIONS and its value.
-        list(SUBLIST ARGN 2 -1 _vcf_ARGN)
-        _check_features(_vcf_ARGN ON OFF)
     endif()
-    set(${_vcf_OUT_FEATURE_OPTIONS} "${_vcf_FEATURE_OPTIONS}" PARENT_SCOPE)
+
+    z_vcpkg_check_features_last_feature(last_inverted_feature "INVERTED_FEATURES" "${arg_INVERTED_FEATURES}")
+    if(last_inverted_feature GREATER_EQUAL 0)
+        foreach(feature_pair_idx RANGE "${last_inverted_feature}")
+            z_vcpkg_check_features_get_feature("${feature_pair_idx}" "${arg_INVERTED_FEATURES}" feature_name feature_var)
+
+            list(APPEND feature_variables "${feature_var}")
+            if(feature_name IN_LIST FEATURES)
+                list(APPEND feature_options "-D${feature_var}=OFF")
+                set("${prefix}${feature_var}" OFF PARENT_SCOPE)
+            else()
+                list(APPEND feature_options "-D${feature_var}=ON")
+                set("${prefix}${feature_var}" ON PARENT_SCOPE)
+            endif()
+        endforeach()
+    endif()
+
+    list(SORT feature_variables)
+    set(last_variable)
+    foreach(variable IN LISTS feature_variables)
+        if(variable STREQUAL last_variable)
+            message(FATAL_ERROR "vcpkg_check_features passed the same feature variable multiple times: '${variable}'")
+        endif()
+    endforeach()
+
+    set("${arg_OUT_FEATURE_OPTIONS}" "${feature_options}" PARENT_SCOPE)
 endfunction()

scripts/cmake/vcpkg_common_definitions.cmake

@@ -1,9 +1,8 @@
 #[===[.md:
 # vcpkg_common_definitions
 
-File contains helpful variabls for portfiles which are commonly needed or used.
+This file defines the following variabls which are commonly needed or used in portfiles:
 
-## The following variables are available:
 ```cmake
 VCPKG_TARGET_IS_<target>                 with <target> being one of the following: WINDOWS, UWP, LINUX, OSX, ANDROID, FREEBSD, OPENBSD. only defined if <target>
 VCPKG_HOST_IS_<target>                   with <host> being one of the following: WINDOWS, LINUX, OSX, FREEBSD, OPENBSD. only defined if <host>
@@ -27,39 +26,39 @@ portfiles are able to use find_library calls to discover dependent libraries wit
 #]===]
 
 #Helper variable to identify the Target system. VCPKG_TARGET_IS_<targetname>
-if (NOT VCPKG_CMAKE_SYSTEM_NAME OR VCPKG_CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
+if (NOT DEFINED VCPKG_CMAKE_SYSTEM_NAME OR VCPKG_CMAKE_SYSTEM_NAME STREQUAL "")
-    set(VCPKG_TARGET_IS_WINDOWS 1)
+    set(VCPKG_TARGET_IS_WINDOWS ON)
-    if(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
+elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
-        set(VCPKG_TARGET_IS_UWP 1)
+    set(VCPKG_TARGET_IS_WINDOWS ON)
-    endif()
+    set(VCPKG_TARGET_IS_UWP ON)
 elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "Darwin")
-    set(VCPKG_TARGET_IS_OSX 1)
+    set(VCPKG_TARGET_IS_OSX ON)
 elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "iOS")
-    set(VCPKG_TARGET_IS_IOS 1)
+    set(VCPKG_TARGET_IS_IOS ON)
 elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "Linux")
-    set(VCPKG_TARGET_IS_LINUX 1)
+    set(VCPKG_TARGET_IS_LINUX ON)
 elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "Android")
-    set(VCPKG_TARGET_IS_ANDROID 1)
+    set(VCPKG_TARGET_IS_ANDROID ON)
 elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "FreeBSD")
-    set(VCPKG_TARGET_IS_FREEBSD 1)
+    set(VCPKG_TARGET_IS_FREEBSD ON)
 elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "OpenBSD")
-    set(VCPKG_TARGET_IS_OPENBSD 1)
+    set(VCPKG_TARGET_IS_OPENBSD ON)
 elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "MinGW")
-    set(VCPKG_TARGET_IS_WINDOWS 1)
+    set(VCPKG_TARGET_IS_WINDOWS ON)
-    set(VCPKG_TARGET_IS_MINGW 1)
+    set(VCPKG_TARGET_IS_MINGW ON)
 endif()
 
 #Helper variables to identify the host system name
 if (CMAKE_HOST_WIN32)
-    set(VCPKG_HOST_IS_WINDOWS 1)
+    set(VCPKG_HOST_IS_WINDOWS ON)
 elseif (CMAKE_HOST_SYSTEM_NAME STREQUAL "Darwin")
-    set(VCPKG_HOST_IS_OSX 1)
+    set(VCPKG_HOST_IS_OSX ON)
 elseif(CMAKE_HOST_SYSTEM_NAME STREQUAL "Linux")
-    set(VCPKG_HOST_IS_LINUX 1)
+    set(VCPKG_HOST_IS_LINUX ON)
 elseif(CMAKE_HOST_SYSTEM_NAME STREQUAL "FreeBSD")
-    set(VCPKG_HOST_IS_FREEBSD 1)
+    set(VCPKG_HOST_IS_FREEBSD ON)
 elseif(CMAKE_HOST_SYSTEM_NAME STREQUAL "OpenBSD")
-    set(VCPKG_HOST_IS_OPENBSD 1)
+    set(VCPKG_HOST_IS_OPENBSD ON)
 endif()
 
 #Helper variable to identify the host path separator.
@@ -152,12 +151,12 @@ endif()
 
 # Platforms with libstdc++
 if(VCPKG_TARGET_IS_LINUX OR VCPKG_TARGET_IS_ANDROID OR VCPKG_TARGET_IS_FREEBSD OR VCPKG_TARGET_IS_OPENBSD OR VCPKG_TARGET_IS_MINGW)
-    list(APPEND VCPKG_SYSTEM_LIBRARIES [=[stdc\+\+]=])
+    list(APPEND VCPKG_SYSTEM_LIBRARIES [[stdc\+\+]])
 endif()
 
 # Platforms with libc++
 if(VCPKG_TARGET_IS_OSX)
-    list(APPEND VCPKG_SYSTEM_LIBRARIES [=[c\+\+]=])
+    list(APPEND VCPKG_SYSTEM_LIBRARIES [[c\+\+]])
 endif()
 
 # Platforms with librt
@@ -199,5 +198,5 @@ if(VCPKG_TARGET_IS_WINDOWS)
     list(APPEND VCPKG_SYSTEM_LIBRARIES wsock32)
     list(APPEND VCPKG_SYSTEM_LIBRARIES Ws2_32)
     list(APPEND VCPKG_SYSTEM_LIBRARIES wldap32)
-    list(APPEND VCPKG_SYSTEM_LIBRARIES crypt32)	
+    list(APPEND VCPKG_SYSTEM_LIBRARIES crypt32)
 endif()

scripts/cmake/vcpkg_configure_cmake.cmake

@@ -1,6 +1,8 @@
 #[===[.md:
 # vcpkg_configure_cmake
 
+**This function has been deprecated in favor of `vcpkg_cmake_configure` from the vcpkg-cmake port.**
+
 Configure CMake for Debug and Release builds of a project.
 
 ## Usage
@@ -67,8 +69,12 @@ This command supplies many common arguments to CMake. To see the full list, exam
 #]===]
 
 function(vcpkg_configure_cmake)
-    # parse parameters such that semicolons in arguments to OPTIONS don't get erased
+    message(DEPRECATION "vcpkg_configure_cmake has been deprecated in favor of vcpkg_cmake_configure from the vcpkg-cmake port.")
-    cmake_parse_arguments(PARSE_ARGV 0 _csc
+    if(Z_VCPKG_CMAKE_CONFIGURE_GUARD)
+        message(FATAL_ERROR "The ${PORT} port already depends on vcpkg-cmake; using both vcpkg-cmake and vcpkg_configure_cmake in the same port is unsupported.")
+    endif()
+
+    cmake_parse_arguments(PARSE_ARGV 0 arg
         "PREFER_NINJA;DISABLE_PARALLEL_CONFIGURE;NO_CHARSET_FLAG"
         "SOURCE_PATH;GENERATOR;LOGNAME"
         "OPTIONS;OPTIONS_DEBUG;OPTIONS_RELEASE"
@@ -79,15 +85,15 @@ function(vcpkg_configure_cmake)
             "however, vcpkg.exe must be rebuilt by re-running bootstrap-vcpkg.bat\n")
     endif()
 
-    if(NOT _csc_LOGNAME)
+    if(NOT arg_LOGNAME)
-        set(_csc_LOGNAME config-${TARGET_TRIPLET})
+        set(arg_LOGNAME config-${TARGET_TRIPLET})
     endif()
 
     if(CMAKE_HOST_WIN32)
         if(DEFINED ENV{PROCESSOR_ARCHITEW6432})
-            set(_csc_HOST_ARCHITECTURE $ENV{PROCESSOR_ARCHITEW6432})
+            set(arg_HOST_ARCHITECTURE $ENV{PROCESSOR_ARCHITEW6432})
         else()
-            set(_csc_HOST_ARCHITECTURE $ENV{PROCESSOR_ARCHITECTURE})
+            set(arg_HOST_ARCHITECTURE $ENV{PROCESSOR_ARCHITECTURE})
         endif()
     endif()
 
@@ -98,7 +104,7 @@ function(vcpkg_configure_cmake)
         set(_TARGETTING_UWP 1)
     endif()
 
-    if(_csc_HOST_ARCHITECTURE STREQUAL "x86")
+    if(arg_HOST_ARCHITECTURE STREQUAL "x86")
         # Prebuilt ninja binaries are only provided for x64 hosts
         set(NINJA_CAN_BE_USED OFF)
         set(NINJA_HOST OFF)
@@ -107,9 +113,9 @@ function(vcpkg_configure_cmake)
         set(NINJA_CAN_BE_USED OFF)
     endif()
 
-    if(_csc_GENERATOR)
+    if(arg_GENERATOR)
-        set(GENERATOR ${_csc_GENERATOR})
+        set(GENERATOR ${arg_GENERATOR})
-    elseif(_csc_PREFER_NINJA AND NINJA_CAN_BE_USED)
+    elseif(arg_PREFER_NINJA AND NINJA_CAN_BE_USED)
         set(GENERATOR "Ninja")
     elseif(VCPKG_CHAINLOAD_TOOLCHAIN_FILE OR (VCPKG_CMAKE_SYSTEM_NAME AND NOT _TARGETTING_UWP))
         set(GENERATOR "Ninja")
@@ -164,13 +170,13 @@ function(vcpkg_configure_cmake)
         vcpkg_find_acquire_program(NINJA)
         get_filename_component(NINJA_PATH ${NINJA} DIRECTORY)
         vcpkg_add_to_path("${NINJA_PATH}")
-        list(APPEND _csc_OPTIONS "-DCMAKE_MAKE_PROGRAM=${NINJA}")
+        list(APPEND arg_OPTIONS "-DCMAKE_MAKE_PROGRAM=${NINJA}")
     endif()
 
     file(REMOVE_RECURSE ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg)
 
     if(DEFINED VCPKG_CMAKE_SYSTEM_NAME)
-        list(APPEND _csc_OPTIONS "-DCMAKE_SYSTEM_NAME=${VCPKG_CMAKE_SYSTEM_NAME}")
+        list(APPEND arg_OPTIONS "-DCMAKE_SYSTEM_NAME=${VCPKG_CMAKE_SYSTEM_NAME}")
         if(_TARGETTING_UWP AND NOT DEFINED VCPKG_CMAKE_SYSTEM_VERSION)
             set(VCPKG_CMAKE_SYSTEM_VERSION 10.0)
         elseif(VCPKG_CMAKE_SYSTEM_NAME STREQUAL "Android" AND NOT DEFINED VCPKG_CMAKE_SYSTEM_VERSION)
@@ -179,13 +185,13 @@ function(vcpkg_configure_cmake)
     endif()
 
     if(DEFINED VCPKG_CMAKE_SYSTEM_VERSION)
-        list(APPEND _csc_OPTIONS "-DCMAKE_SYSTEM_VERSION=${VCPKG_CMAKE_SYSTEM_VERSION}")
+        list(APPEND arg_OPTIONS "-DCMAKE_SYSTEM_VERSION=${VCPKG_CMAKE_SYSTEM_VERSION}")
     endif()
 
     if(VCPKG_LIBRARY_LINKAGE STREQUAL "dynamic")
-        list(APPEND _csc_OPTIONS -DBUILD_SHARED_LIBS=ON)
+        list(APPEND arg_OPTIONS -DBUILD_SHARED_LIBS=ON)
     elseif(VCPKG_LIBRARY_LINKAGE STREQUAL "static")
-        list(APPEND _csc_OPTIONS -DBUILD_SHARED_LIBS=OFF)
+        list(APPEND arg_OPTIONS -DBUILD_SHARED_LIBS=OFF)
     else()
         message(FATAL_ERROR
             "Invalid setting for VCPKG_LIBRARY_LINKAGE: \"${VCPKG_LIBRARY_LINKAGE}\". "
@@ -203,7 +209,7 @@ function(vcpkg_configure_cmake)
     check_both_vars_are_set(VCPKG_CXX_FLAGS VCPKG_C_FLAGS)
 
     set(VCPKG_SET_CHARSET_FLAG ON)
-    if(_csc_NO_CHARSET_FLAG)
+    if(arg_NO_CHARSET_FLAG)
         set(VCPKG_SET_CHARSET_FLAG OFF)
     endif()
 
@@ -228,7 +234,7 @@ function(vcpkg_configure_cmake)
     endif()
 
 
-    list(APPEND _csc_OPTIONS
+    list(APPEND arg_OPTIONS
         "-DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=${VCPKG_CHAINLOAD_TOOLCHAIN_FILE}"
         "-DVCPKG_TARGET_TRIPLET=${TARGET_TRIPLET}"
         "-DVCPKG_SET_CHARSET_FLAG=${VCPKG_SET_CHARSET_FLAG}"
@@ -260,7 +266,7 @@ function(vcpkg_configure_cmake)
     )
 
     if(DEFINED ARCH)
-        list(APPEND _csc_OPTIONS
+        list(APPEND arg_OPTIONS
             "-A${ARCH}"
         )
     endif()
@@ -268,23 +274,23 @@ function(vcpkg_configure_cmake)
     # Sets configuration variables for macOS builds
     foreach(config_var  INSTALL_NAME_DIR OSX_DEPLOYMENT_TARGET OSX_SYSROOT OSX_ARCHITECTURES)
         if(DEFINED VCPKG_${config_var})
-            list(APPEND _csc_OPTIONS "-DCMAKE_${config_var}=${VCPKG_${config_var}}")
+            list(APPEND arg_OPTIONS "-DCMAKE_${config_var}=${VCPKG_${config_var}}")
         endif()
     endforeach()
 
     set(rel_command
-        ${CMAKE_COMMAND} ${_csc_SOURCE_PATH} "${_csc_OPTIONS}" "${_csc_OPTIONS_RELEASE}"
+        ${CMAKE_COMMAND} ${arg_SOURCE_PATH} "${arg_OPTIONS}" "${arg_OPTIONS_RELEASE}"
         -G ${GENERATOR}
         -DCMAKE_BUILD_TYPE=Release
         -DCMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR})
     set(dbg_command
-        ${CMAKE_COMMAND} ${_csc_SOURCE_PATH} "${_csc_OPTIONS}" "${_csc_OPTIONS_DEBUG}"
+        ${CMAKE_COMMAND} ${arg_SOURCE_PATH} "${arg_OPTIONS}" "${arg_OPTIONS_DEBUG}"
         -G ${GENERATOR}
         -DCMAKE_BUILD_TYPE=Debug
         -DCMAKE_INSTALL_PREFIX=${CURRENT_PACKAGES_DIR}/debug)
 
-    if(NINJA_HOST AND CMAKE_HOST_WIN32 AND NOT _csc_DISABLE_PARALLEL_CONFIGURE)
+    if(NINJA_HOST AND CMAKE_HOST_WIN32 AND NOT arg_DISABLE_PARALLEL_CONFIGURE)
-        list(APPEND _csc_OPTIONS "-DCMAKE_DISABLE_SOURCE_CHANGES=ON")
+        list(APPEND arg_OPTIONS "-DCMAKE_DISABLE_SOURCE_CHANGES=ON")
 
         vcpkg_find_acquire_program(NINJA)
         get_filename_component(NINJA_PATH ${NINJA} DIRECTORY)
@@ -319,7 +325,7 @@ function(vcpkg_configure_cmake)
         vcpkg_execute_required_process(
             COMMAND ninja -v
             WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel/vcpkg-parallel-configure
-            LOGNAME ${_csc_LOGNAME}
+            LOGNAME ${arg_LOGNAME}
         )
     else()
         if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
@@ -328,7 +334,7 @@ function(vcpkg_configure_cmake)
             vcpkg_execute_required_process(
                 COMMAND ${dbg_command}
                 WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg
-                LOGNAME ${_csc_LOGNAME}-dbg
+                LOGNAME ${arg_LOGNAME}-dbg
             )
         endif()
 
@@ -338,10 +344,10 @@ function(vcpkg_configure_cmake)
             vcpkg_execute_required_process(
                 COMMAND ${rel_command}
                 WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
-                LOGNAME ${_csc_LOGNAME}-rel
+                LOGNAME ${arg_LOGNAME}-rel
             )
         endif()
     endif()
 
-    set(_VCPKG_CMAKE_GENERATOR "${GENERATOR}" PARENT_SCOPE)
+    set(Z_VCPKG_CMAKE_GENERATOR "${GENERATOR}" PARENT_SCOPE)
 endfunction()

scripts/cmake/vcpkg_copy_pdbs.cmake

@@ -3,78 +3,70 @@
 
 Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
 
-## Usage
 ```cmake
-vcpkg_copy_pdbs([BUILD_PATHS <${CURRENT_PACKAGES_DIR}/bin/*.dll> ...])
+vcpkg_copy_pdbs(
+    [BUILD_PATHS <glob>...])
 ```
 
+The `<glob>`s are patterns which will be passed to `file(GLOB_RECURSE)`,
+for locating DLLs. It defaults to using:
+
+- `${CURRENT_PACKAGES_DIR}/bin/*.dll`
+- `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`
+
+since that is generally where DLLs are located.
+
 ## Notes
 This command should always be called by portfiles after they have finished rearranging the binary output.
 
-## Parameters
-### BUILD_PATHS
-Path patterns passed to `file(GLOB_RECURSE)` for locating dlls.
-
-Defaults to `${CURRENT_PACKAGES_DIR}/bin/*.dll` and `${CURRENT_PACKAGES_DIR}/debug/bin/*.dll`.
-
 ## 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)
 #]===]
-
 function(vcpkg_copy_pdbs)
-    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "" "" "BUILD_PATHS")
-    cmake_parse_arguments(PARSE_ARGV 0 _vcp "" "" "BUILD_PATHS")
+
-    
+    if(NOT DEFINED arg_BUILD_PATHS)
-    if(NOT _vcp_BUILD_PATHS)
         set(
-            _vcp_BUILD_PATHS
+            arg_BUILD_PATHS
-            ${CURRENT_PACKAGES_DIR}/bin/*.dll
+            "${CURRENT_PACKAGES_DIR}/bin/*.dll"
-            ${CURRENT_PACKAGES_DIR}/debug/bin/*.dll
+            "${CURRENT_PACKAGES_DIR}/debug/bin/*.dll"
         )
     endif()
 
-    function(merge_filelist OUTVAR INVAR)
+    set(dlls_without_matching_pdbs)
-        set(MSG "")
-        foreach(VAR ${${INVAR}})
-            set(MSG "${MSG}    ${VAR}\n")
-        endforeach()
-        set(${OUTVAR} ${MSG} PARENT_SCOPE)
-    endfunction()
 
-    if(VCPKG_LIBRARY_LINKAGE STREQUAL dynamic AND NOT VCPKG_TARGET_IS_MINGW)
+    if(VCPKG_LIBRARY_LINKAGE STREQUAL "dynamic" AND VCPKG_TARGET_IS_WINDOWS AND NOT VCPKG_TARGET_IS_MINGW)
-        file(GLOB_RECURSE DLLS ${_vcp_BUILD_PATHS})
+        file(GLOB_RECURSE dlls ${arg_BUILD_PATHS})
 
-        set(DLLS_WITHOUT_MATCHING_PDBS)
+        set(vslang_backup "$ENV{VSLANG}")
-
-        set(PREVIOUS_VSLANG $ENV{VSLANG})
         set(ENV{VSLANG} 1033)
 
-        foreach(DLL ${DLLS})
+        foreach(dll IN LISTS dlls)
-            execute_process(COMMAND dumpbin /PDBPATH ${DLL}
+            execute_process(COMMAND dumpbin /PDBPATH ${dll}
                             COMMAND findstr PDB
-                OUTPUT_VARIABLE PDB_LINE
+                OUTPUT_VARIABLE pdb_line
                 ERROR_QUIET
                 RESULT_VARIABLE error_code
             )
 
-            if(NOT error_code AND PDB_LINE MATCHES "PDB file found at")
+            if(NOT error_code AND pdb_line MATCHES "PDB file found at")
-                string(REGEX MATCH '.*' PDB_PATH ${PDB_LINE}) # Extract the path which is in single quotes
+                string(REGEX MATCH [['.*']] pdb_path "${pdb_line}") # Extract the path which is in single quotes
-                string(REPLACE ' "" PDB_PATH ${PDB_PATH}) # Remove single quotes
+                string(REPLACE "'" "" pdb_path "${pdb_path}") # Remove single quotes
-                get_filename_component(DLL_DIR ${DLL} DIRECTORY)
+                get_filename_component(dll_dir "${dll}" DIRECTORY)
-                file(COPY ${PDB_PATH} DESTINATION ${DLL_DIR})
+                file(COPY "${pdb_path}" DESTINATION "${dll_dir}")
             else()
-                list(APPEND DLLS_WITHOUT_MATCHING_PDBS ${DLL})
+                list(APPEND dlls_without_matching_pdbs "${dll}")
             endif()
         endforeach()
 
-        set(ENV{VSLANG} ${PREVIOUS_VSLANG})
+        set(ENV{VSLANG} "${vslang_backup}")
 
-        list(LENGTH DLLS_WITHOUT_MATCHING_PDBS UNMATCHED_DLLS_LENGTH)
+        list(LENGTH dlls_without_matching_pdbs unmatched_dlls_length)
-        if(UNMATCHED_DLLS_LENGTH GREATER 0)
+        if(unmatched_dlls_length GREATER 0)
-            merge_filelist(MSG DLLS_WITHOUT_MATCHING_PDBS)
+            list(JOIN dlls_without_matching_pdbs "\n    " message)
-            message(STATUS "Warning: Could not find a matching pdb file for:\n${MSG}")
+            message(WARNING "Could not find a matching pdb file for:${message}\n")
         endif()
     endif()
 

scripts/cmake/vcpkg_extract_source_archive_ex.cmake

@@ -54,7 +54,6 @@ Specifies that the default removal of the top level folder should not occur.
 * [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake)
 #]===]
 
-include(vcpkg_apply_patches)
 include(vcpkg_extract_source_archive)
 
 function(vcpkg_extract_source_archive_ex)
@@ -142,7 +141,7 @@ function(vcpkg_extract_source_archive_ex)
             set (QUIET)
         endif()
 
-        vcpkg_apply_patches(
+        z_vcpkg_apply_patches(
             ${QUIET}
             SOURCE_PATH ${TEMP_SOURCE_PATH}
             PATCHES ${_vesae_PATCHES}

scripts/cmake/vcpkg_fixup_cmake_targets.cmake

@@ -1,6 +1,8 @@
 #[===[.md:
 # vcpkg_fixup_cmake_targets
 
+**This function has been deprecated in favor of `vcpkg_cmake_config_fixup` from the vcpkg-cmake-config port.**
+
 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.
@@ -23,7 +25,7 @@ This needs to be specified if the port name differs from the `find_package()` na
 
 Defaults to `share/${PORT}`.
 
-### DO_NOT_DELETE_PARENT_CONFIG_PATH 
+### DO_NOT_DELETE_PARENT_CONFIG_PATH
 By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
 Passing this option disable such behavior, as it is convenient for ports that install
 more than one CMake package configuration file.
@@ -51,31 +53,35 @@ Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targe
 #]===]
 
 function(vcpkg_fixup_cmake_targets)
-    # parse parameters such that semicolons in options arguments to COMMAND don't get erased
+    message(DEPRECATION "vcpkg_fixup_cmake_targets has been deprecated in favor of vcpkg_cmake_config_fixup from the vcpkg-cmake-config port.")
-    cmake_parse_arguments(PARSE_ARGV 0 _vfct "DO_NOT_DELETE_PARENT_CONFIG_PATH" "CONFIG_PATH;TARGET_PATH;NO_PREFIX_CORRECTION" "")
+    if(Z_VCPKG_CMAKE_CONFIG_FIXUP_GUARD)
-
+        message(FATAL_ERROR "The ${PORT} port already depends on vcpkg-cmake-config; using both vcpkg-cmake-config and vcpkg_fixup_cmake_targets in the same port is unsupported.")
-    if(_vfct_UNPARSED_ARGUMENTS)
-        message(FATAL_ERROR "vcpkg_fixup_cmake_targets was passed extra arguments: ${_vfct_UNPARSED_ARGUMENTS}")
     endif()
 
-    if(NOT _vfct_TARGET_PATH)
+    cmake_parse_arguments(PARSE_ARGV 0 arg "DO_NOT_DELETE_PARENT_CONFIG_PATH" "CONFIG_PATH;TARGET_PATH;NO_PREFIX_CORRECTION" "")
-        set(_vfct_TARGET_PATH share/${PORT})
+
+    if(arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "vcpkg_fixup_cmake_targets was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+
+    if(NOT arg_TARGET_PATH)
+        set(arg_TARGET_PATH share/${PORT})
     endif()
 
     string(REPLACE "." "\\." EXECUTABLE_SUFFIX "${VCPKG_TARGET_EXECUTABLE_SUFFIX}")
 
-    set(DEBUG_SHARE ${CURRENT_PACKAGES_DIR}/debug/${_vfct_TARGET_PATH})
+    set(DEBUG_SHARE ${CURRENT_PACKAGES_DIR}/debug/${arg_TARGET_PATH})
-    set(RELEASE_SHARE ${CURRENT_PACKAGES_DIR}/${_vfct_TARGET_PATH})
+    set(RELEASE_SHARE ${CURRENT_PACKAGES_DIR}/${arg_TARGET_PATH})
 
-    if(_vfct_CONFIG_PATH AND NOT RELEASE_SHARE STREQUAL "${CURRENT_PACKAGES_DIR}/${_vfct_CONFIG_PATH}")
+    if(arg_CONFIG_PATH AND NOT RELEASE_SHARE STREQUAL "${CURRENT_PACKAGES_DIR}/${arg_CONFIG_PATH}")
-        if(_vfct_CONFIG_PATH STREQUAL "share")
+        if(arg_CONFIG_PATH STREQUAL "share")
             file(RENAME ${CURRENT_PACKAGES_DIR}/debug/share ${CURRENT_PACKAGES_DIR}/debug/share2)
             file(RENAME ${CURRENT_PACKAGES_DIR}/share ${CURRENT_PACKAGES_DIR}/share2)
-            set(_vfct_CONFIG_PATH share2)
+            set(arg_CONFIG_PATH share2)
         endif()
 
-        set(DEBUG_CONFIG ${CURRENT_PACKAGES_DIR}/debug/${_vfct_CONFIG_PATH})
+        set(DEBUG_CONFIG ${CURRENT_PACKAGES_DIR}/debug/${arg_CONFIG_PATH})
-        set(RELEASE_CONFIG ${CURRENT_PACKAGES_DIR}/${_vfct_CONFIG_PATH})
+        set(RELEASE_CONFIG ${CURRENT_PACKAGES_DIR}/${arg_CONFIG_PATH})
         if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
             if(NOT EXISTS ${DEBUG_CONFIG})
                 message(FATAL_ERROR "'${DEBUG_CONFIG}' does not exist.")
@@ -95,13 +101,13 @@ function(vcpkg_fixup_cmake_targets)
         if(NOT DEFINED VCPKG_BUILD_TYPE OR VCPKG_BUILD_TYPE STREQUAL "debug")
             get_filename_component(DEBUG_CONFIG_DIR_NAME ${DEBUG_CONFIG} NAME)
             string(TOLOWER "${DEBUG_CONFIG_DIR_NAME}" DEBUG_CONFIG_DIR_NAME)
-            if(DEBUG_CONFIG_DIR_NAME STREQUAL "cmake" AND NOT _vfct_DO_NOT_DELETE_PARENT_CONFIG_PATH)
+            if(DEBUG_CONFIG_DIR_NAME STREQUAL "cmake" AND NOT arg_DO_NOT_DELETE_PARENT_CONFIG_PATH)
                 file(REMOVE_RECURSE ${DEBUG_CONFIG})
             else()
                 get_filename_component(DEBUG_CONFIG_PARENT_DIR ${DEBUG_CONFIG} DIRECTORY)
                 get_filename_component(DEBUG_CONFIG_DIR_NAME ${DEBUG_CONFIG_PARENT_DIR} NAME)
                 string(TOLOWER "${DEBUG_CONFIG_DIR_NAME}" DEBUG_CONFIG_DIR_NAME)
-                if(DEBUG_CONFIG_DIR_NAME STREQUAL "cmake" AND NOT _vfct_DO_NOT_DELETE_PARENT_CONFIG_PATH)
+                if(DEBUG_CONFIG_DIR_NAME STREQUAL "cmake" AND NOT arg_DO_NOT_DELETE_PARENT_CONFIG_PATH)
                     file(REMOVE_RECURSE ${DEBUG_CONFIG_PARENT_DIR})
                 endif()
             endif()
@@ -109,13 +115,13 @@ function(vcpkg_fixup_cmake_targets)
 
         get_filename_component(RELEASE_CONFIG_DIR_NAME ${RELEASE_CONFIG} NAME)
         string(TOLOWER "${RELEASE_CONFIG_DIR_NAME}" RELEASE_CONFIG_DIR_NAME)
-        if(RELEASE_CONFIG_DIR_NAME STREQUAL "cmake" AND NOT _vfct_DO_NOT_DELETE_PARENT_CONFIG_PATH)
+        if(RELEASE_CONFIG_DIR_NAME STREQUAL "cmake" AND NOT arg_DO_NOT_DELETE_PARENT_CONFIG_PATH)
             file(REMOVE_RECURSE ${RELEASE_CONFIG})
         else()
             get_filename_component(RELEASE_CONFIG_PARENT_DIR ${RELEASE_CONFIG} DIRECTORY)
             get_filename_component(RELEASE_CONFIG_DIR_NAME ${RELEASE_CONFIG_PARENT_DIR} NAME)
             string(TOLOWER "${RELEASE_CONFIG_DIR_NAME}" RELEASE_CONFIG_DIR_NAME)
-            if(RELEASE_CONFIG_DIR_NAME STREQUAL "cmake" AND NOT _vfct_DO_NOT_DELETE_PARENT_CONFIG_PATH)
+            if(RELEASE_CONFIG_DIR_NAME STREQUAL "cmake" AND NOT arg_DO_NOT_DELETE_PARENT_CONFIG_PATH)
                 file(REMOVE_RECURSE ${RELEASE_CONFIG_PARENT_DIR})
             endif()
         endif()
@@ -165,18 +171,18 @@ function(vcpkg_fixup_cmake_targets)
         endforeach()
     endif()
 
-    #Fix ${_IMPORT_PREFIX} in cmake generated targets and configs; 
+    #Fix ${_IMPORT_PREFIX} in cmake generated targets and configs;
     #Since those can be renamed we have to check in every *.cmake
     file(GLOB_RECURSE MAIN_CMAKES "${RELEASE_SHARE}/*.cmake")
 
     foreach(MAIN_CMAKE IN LISTS MAIN_CMAKES)
         file(READ ${MAIN_CMAKE} _contents)
         #This correction is not correct for all cases. To make it correct for all cases it needs to consider
-        #original folder deepness to CURRENT_PACKAGES_DIR in comparison to the moved to folder deepness which 
+        #original folder deepness to CURRENT_PACKAGES_DIR in comparison to the moved to folder deepness which
-        #is always at least (>=) 2, e.g. share/${PORT}. Currently the code assumes it is always 2 although 
+        #is always at least (>=) 2, e.g. share/${PORT}. Currently the code assumes it is always 2 although
         #this requirement is only true for the *Config.cmake. The targets are not required to be in the same
         #folder as the *Config.cmake!
-        if(NOT _vfct_NO_PREFIX_CORRECTION)
+        if(NOT arg_NO_PREFIX_CORRECTION)
             string(REGEX REPLACE
                 "get_filename_component\\(_IMPORT_PREFIX \"\\\${CMAKE_CURRENT_LIST_FILE}\" PATH\\)(\nget_filename_component\\(_IMPORT_PREFIX \"\\\${_IMPORT_PREFIX}\" PATH\\))*"
                 "get_filename_component(_IMPORT_PREFIX \"\${CMAKE_CURRENT_LIST_FILE}\" PATH)\nget_filename_component(_IMPORT_PREFIX \"\${_IMPORT_PREFIX}\" PATH)\nget_filename_component(_IMPORT_PREFIX \"\${_IMPORT_PREFIX}\" PATH)"
@@ -196,7 +202,7 @@ function(vcpkg_fixup_cmake_targets)
         #an imported target for it. We could add more logic here to identify defect target files.
         #Since the replacement here in a multi config build always requires a generator expression
         #in front of the absoulte path to ${CURRENT_INSTALLED_DIR}. So the match should always be at
-        #least >:${CURRENT_INSTALLED_DIR}. 
+        #least >:${CURRENT_INSTALLED_DIR}.
         #In general the following generator expressions should be there:
         #\$<\$<CONFIG:DEBUG>:${CURRENT_INSTALLED_DIR}/debug/lib/somelib>
         #and/or
@@ -228,4 +234,4 @@ function(vcpkg_fixup_cmake_targets)
     endforeach()
 endfunction()
 
- 
+

scripts/cmake/vcpkg_install_cmake.cmake

@@ -1,6 +1,8 @@
 #[===[.md:
 # vcpkg_install_cmake
 
+**This function has been deprecated in favor of `vcpkg_cmake_install` from the vcpkg-cmake port.**
+
 Build and install a cmake project.
 
 ## Usage:
@@ -24,5 +26,26 @@ parameter.
 #]===]
 
 function(vcpkg_install_cmake)
-    vcpkg_build_cmake(LOGFILE_ROOT install TARGET install ${ARGN})
+    message(DEPRECATION "vcpkg_install_cmake has been deprecated in favor of vcpkg_cmake_install from the vcpkg-cmake port.")
+    if(Z_VCPKG_CMAKE_INSTALL_GUARD)
+        message(FATAL_ERROR "The ${PORT} port already depends on vcpkg-cmake; using both vcpkg-cmake and vcpkg_install_cmake in the same port is unsupported.")
+    endif()
+
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "DISABLE_PARALLEL;ADD_BIN_TO_PATH" "" "")
+    if(DEFINED arg_UNPARSED_ARGUMENTS)
+        message(FATAL_ERROR "vcpkg_cmake_install was passed extra arguments: ${arg_UNPARSED_ARGUMENTS}")
+    endif()
+
+    set(args)
+    foreach(arg IN ITEMS DISABLE_PARALLEL ADD_BIN_TO_PATH)
+        if(arg_${arg})
+            list(APPEND args "${arg}")
+        endif()
+    endforeach()
+
+    vcpkg_build_cmake(Z_VCPKG_DISABLE_DEPRECATION MESSAGE
+        ${args}
+        LOGFILE_ROOT install
+        TARGET install
+    )
 endfunction()

scripts/cmake/z_vcpkg_apply_patches.cmake

@@ -0,0 +1,67 @@
+#[===[.md:
+# z_vcpkg_apply_patches
+
+**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.
+#]===]
+
+function(z_vcpkg_apply_patches)
+    cmake_parse_arguments(PARSE_ARGV 0 "arg" "QUIET" "SOURCE_PATH" "PATCHES")
+
+    find_program(GIT NAMES git git.cmd REQUIRED)
+    if(DEFINED ENV{GIT_CONFIG_NOSYSTEM})
+        set(git_config_nosystem_backuP "$ENV{GIT_CONFIG_NOSYSTEM}")
+    else()
+        unset(git_config_nosystem_backup)
+    endif()
+
+    set(ENV{GIT_CONFIG_NOSYSTEM} 1)
+    set(patchnum 0)
+    foreach(patch IN LISTS arg_PATCHES)
+        get_filename_component(absolute_patch "${patch}" ABSOLUTE BASE_DIR "${CURRENT_PORT_DIR}")
+        message(STATUS "Applying patch ${patch}")
+        set(logname patch-${TARGET_TRIPLET}-${patchnum})
+        vcpkg_execute_in_download_mode(
+            COMMAND "${GIT}" -c core.longpaths=true -c core.autocrlf=false --work-tree=. --git-dir=.git apply "${absolute_patch}" --ignore-whitespace --whitespace=nowarn --verbose
+            OUTPUT_FILE "${CURRENT_BUILDTREES_DIR}/${logname}-out.log"
+            ERROR_VARIABLE error
+            WORKING_DIRECTORY "${arg_SOURCE_PATH}"
+            RESULT_VARIABLE error_code
+        )
+        file(WRITE "${CURRENT_BUILDTREES_DIR}/${logname}-err.log" "${error}")
+
+        if(error_code AND NOT arg_QUIET)
+            message(FATAL_ERROR "Applying patch failed: ${error}")
+        endif()
+
+        math(EXPR patchnum "${patchnum} + 1")
+    endforeach()
+    if(DEFINED git_config_nosystem_backup)
+        set(ENV{GIT_CONFIG_NOSYSTEM} "${git_config_nosystem_backup}")
+    else()
+        unset(ENV{GIT_CONFIG_NOSYSTEM})
+    endif()
+endfunction()

scripts/ports.cmake

@@ -10,6 +10,11 @@ function(debug_message)
         message(STATUS "[DEBUG] " "${ARG_STRING}")
     endif()
 endfunction()
+function(z_vcpkg_deprecation_message)
+    z_vcpkg_function_arguments(ARGS)
+    list(JOIN ARGS " " ARG_STRING)
+    message(DEPRECATION "${ARG_STRING}")
+endfunction()
 
 option(_VCPKG_PROHIBIT_BACKCOMPAT_FEATURES "Controls whether use of a backcompat only support feature fails the build.")
 if (_VCPKG_PROHIBIT_BACKCOMPAT_FEATURES)
@@ -18,7 +23,7 @@ else()
     set(Z_VCPKG_BACKCOMPAT_MESSAGE_LEVEL "WARNING")
 endif()
 
-list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake")
+list(APPEND CMAKE_MODULE_PATH "${SCRIPTS}/cmake")
 include("${SCRIPTS}/cmake/vcpkg_minimum_required.cmake")
 vcpkg_minimum_required(VERSION 2021-01-13)
 
@@ -128,6 +133,7 @@ if(CMD MATCHES "^BUILD$")
     include("${SCRIPTS}/cmake/vcpkg_replace_string.cmake")
     include("${SCRIPTS}/cmake/vcpkg_test_cmake.cmake")
 
+    include("${SCRIPTS}/cmake/z_vcpkg_apply_patches.cmake")
     include("${SCRIPTS}/cmake/z_vcpkg_prettify_command_line.cmake")
 
     include("${CURRENT_PORT_DIR}/portfile.cmake")

versions/baseline.json

@@ -1994,7 +1994,7 @@
     },
     "fmt": {
       "baseline": "7.1.3",
-      "port-version": 0
+      "port-version": 1
     },
     "folly": {
       "baseline": "2020.10.19.00",
@@ -6112,6 +6112,14 @@
       "baseline": "1.0.1",
       "port-version": 0
     },
+    "vcpkg-cmake": {
+      "baseline": "2021-02-26",
+      "port-version": 0
+    },
+    "vcpkg-cmake-config": {
+      "baseline": "2021-02-26",
+      "port-version": 0
+    },
     "vcpkg-gfortran": {
       "baseline": "3",
       "port-version": 0

versions/f-/fmt.json

@@ -1,5 +1,10 @@
 {
   "versions": [
+    {
+      "git-tree": "4f8427eb0bd40da1856d4e67bde39a4fda689d72",
+      "version": "7.1.3",
+      "port-version": 1
+    },
     {
       "git-tree": "dd8cf5e1a2dce2680189a0744102d4b0f1cfb8b6",
       "version-string": "7.1.3",

versions/v-/vcpkg-cmake-config.json

@@ -0,0 +1,9 @@
+{
+  "versions": [
+    {
+      "git-tree": "d255b3d566a8861dcc99a958240463e678528066",
+      "version-date": "2021-02-26",
+      "port-version": 0
+    }
+  ]
+}

versions/v-/vcpkg-cmake.json

@@ -0,0 +1,9 @@
+{
+  "versions": [
+    {
+      "git-tree": "51896aa8073adb5c8450daa423d03eedf0dfc61f",
+      "version-date": "2021-02-26",
+      "port-version": 0
+    }
+  ]
+}