[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.
microsoft · Feb 28, 2021 · 3426db0 · gvanem · Apr 4, 2021 · 3426db0
1 parent e25b620
commit 3426db0
Show file tree

Hide file tree

Showing 98 changed files with 2,111 additions and 510 deletions.
diff --git a/docs/maintainers/execute_process.md b/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)
diff --git a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md b/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
@@ -1,5 +1,7 @@
 # vcpkg_internal_get_cmake_vars
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
 **Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
 Runs a cmake configure with a dummy project to extract certain cmake variables
 
@@ -26,4 +28,4 @@ If possible avoid usage in portfiles.
 * [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
 
 ## Source
-[scripts/cmake/vcpkg_internal_get_cmake_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_internal_get_cmake_vars.cmake)
+[scripts/cmake/vcpkg\_internal\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_internal_get_cmake_vars.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_apply_patches.md b/docs/maintainers/internal/z_vcpkg_apply_patches.md
@@ -0,0 +1,32 @@
+# z_vcpkg_apply_patches
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
+**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
+
+Apply a set of patches to a source tree.
+
+```cmake
+z_vcpkg_apply_patches(
+    SOURCE_PATH <path-to-source>
+    [QUIET]
+    PATCHES <patch>...
+)
+```
+
+The `<path-to-source>` should be set to `${SOURCE_PATH}` by convention,
+and is the path to apply the patches in.
+
+`z_vcpkg_apply_patches` will take the list of `<patch>`es,
+which are by default relative to the port directory,
+and apply them in order using `git apply`.
+Generally, these `<patch>`es take the form of `some.patch`
+to select patches in the port directory.
+One may also download patches and use `${VCPKG_DOWNLOADS}/path/to/some.patch`.
+
+If `QUIET` is not passed, it is a fatal error for a patch to fail to apply;
+otherwise, if `QUIET` is passed, no message is printed.
+This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
+
+## Source
+[scripts/cmake/z\_vcpkg\_apply\_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_apply_patches.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_function_arguments.md b/docs/maintainers/internal/z_vcpkg_function_arguments.md
@@ -1,5 +1,7 @@
 # z_vcpkg_function_arguments
 
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/).
+
 **Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
 Get a list of the arguments which were passed in.
 Unlike `ARGV`, which is simply the arguments joined with `;`,
@@ -24,4 +26,4 @@ endfunction()
 ```
 
 ## Source
-[scripts/cmake/z_vcpkg_function_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)
+[scripts/cmake/z\_vcpkg\_function\_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_prettify_command_line.md b/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
@@ -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)
diff --git a/docs/maintainers/portfile-functions.md b/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)
diff --git a/docs/maintainers/ports/vcpkg-cmake-config.md b/docs/maintainers/ports/vcpkg-cmake-config.md
@@ -0,0 +1,10 @@
+# vcpkg-cmake-config
+
+`vcpkg-cmake-config` provides `vcpkg_cmake_config_fixup()`,
+a function which both:
+
+- Fixes common mistakes in port build systems, like using absolute paths
+- Merges the debug and release config files.
+
+This function should almost always be used when a port has `*config.cmake` files,
+even when the buildsystem of the project is not CMake.
diff --git a/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md b/docs/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md
@@ -0,0 +1,51 @@
+# vcpkg_cmake_config_fixup
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md).
+
+Merge release and debug CMake targets and configs to support multiconfig generators.
+
+Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
+
+```cmake
+vcpkg_cmake_config_fixup(
+    [PACKAGE_NAME <name>]
+    [CONFIG_PATH <config-directory>]
+    [DO_NOT_DELETE_CONFIG_PATH_PARENT]
+    [NO_PREFIX_CORRECTION]
+)
+```
+
+For many ports, `vcpkg_cmake_config_fixup()` on its own should work,
+as `PACKAGE_NAME` defaults to `${PORT}` and `CONFIG_PATH` defaults to `share/${PACKAGE_NAME}`.
+For ports where the package name passed to `find_package` is distinct from the port name,
+`PACKAGE_NAME` should be changed to be that name instead.
+For ports where the directory of the `*config.cmake` files cannot be set,
+use the `CONFIG_PATH` to change the directory where the files come from.
+
+By default the parent directory of CONFIG_PATH is removed if it is named "cmake".
+Passing the `DO_NOT_DELETE_PARENT_CONFIG_PATH` option disable such behavior,
+as it is convenient for ports that install
+more than one CMake package configuration file.
+
+The `NO_PREFIX_CORRECTION` option disables the correction of `_IMPORT_PREFIX`
+done by vcpkg due to moving the config files.
+Currently the correction does not take into account how the files are moved,
+and applies a rather simply correction which in some cases will yield the wrong results.
+
+## How it Works
+
+1. Moves `/debug/<CONFIG_PATH>/*targets-debug.cmake` to `/share/${PACKAGE_NAME}`.
+2. Removes `/debug/<CONFIG_PATH>/*config.cmake`.
+3. Transform all references matching `/bin/*.exe` to `/tools/<port>/*.exe` on Windows.
+4. Transform all references matching `/bin/*` to `/tools/<port>/*` on other platforms.
+5. Fixes `${_IMPORT_PREFIX}` in auto generated targets.
+6. Replace `${CURRENT_INSTALLED_DIR}` with `${_IMPORT_PREFIX}` in configs and targets.
+
+## Examples
+
+* [concurrentqueue](https://github.com/Microsoft/vcpkg/blob/master/ports/concurrentqueue/portfile.cmake)
+* [curl](https://github.com/Microsoft/vcpkg/blob/master/ports/curl/portfile.cmake)
+* [nlohmann-json](https://github.com/Microsoft/vcpkg/blob/master/ports/nlohmann-json/portfile.cmake)
+
+## Source
+[ports/vcpkg-cmake-config/vcpkg\_cmake\_config\_fixup.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake.md b/docs/maintainers/ports/vcpkg-cmake.md
@@ -0,0 +1,7 @@
+# vcpkg-cmake
+
+This port contains cmake functions for dealing with a CMake buildsystem.
+
+In the common case, `vcpkg_cmake_configure()` (with appropriate arguments)
+followed by `vcpkg_cmake_install()` will be enough to build and install a port.
+`vcpkg_cmake_build()` is provided for more complex cases.
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md
@@ -0,0 +1,36 @@
+# vcpkg_cmake_build
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake/vcpkg_cmake_build.md).
+
+Build a cmake project.
+
+```cmake
+vcpkg_cmake_build(
+    [TARGET <target>]
+    [LOGFILE_BASE <base>]
+    [DISABLE_PARALLEL]
+    [ADD_BIN_TO_PATH]
+)
+```
+
+`vcpkg_cmake_build` builds an already-configured cmake project.
+You can use the alias [`vcpkg_cmake_install()`] function
+if your CMake build system supports the `install` TARGET,
+and this is something we recommend doing whenever possible.
+Otherwise, you can use `TARGET` to set the target to build.
+This function defaults to not passing a target to cmake.
+
+`LOGFILE_BASE` is used to set the base of the logfile names;
+by default, this is `build`, and thus the logfiles end up being something like
+`build-x86-windows-dbg.log`; if you use `vcpkg_cmake_install`,
+this is set to `install`, so you'll get log names like `install-x86-windows-dbg.log`.
+
+For build systems that are buggy when run in parallel,
+using `DISABLE_PARALLEL` will run the build with only one job.
+
+Finally, `ADD_BIN_TO_PATH` adds the appropriate (either release or debug)
+`bin/` directories to the path during the build,
+such that executables run during the build will be able to access those DLLs.
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_build.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_build.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md
@@ -0,0 +1,76 @@
+# vcpkg_cmake_configure
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md).
+
+Configure a CMake buildsystem.
+
+```cmake
+vcpkg_cmake_configure(
+    SOURCE_PATH <source-path>
+    [LOGFILE_BASE <logname-base>]
+    [DISABLE_PARALLEL_CONFIGURE]
+    [NO_CHARSET_FLAG]
+    [WINDOWS_USE_MSBUILD]
+    [GENERATOR <generator>]
+    [OPTIONS
+        <configure-setting>...]
+    [OPTIONS_RELEASE
+        <configure-setting>...]
+    [OPTIONS_DEBUG
+        <configure-setting>...]
+)
+```
+
+`vcpkg_cmake_configure` configures a CMake build system for use with
+`vcpkg_cmake_buildsystem_build` and `vcpkg_cmake_buildsystem_install`.
+`source-path` is where the source is located; by convention,
+this is usually `${SOURCE_PATH}`, which is set by one of the `vcpkg_from_*` functions.
+This function configures the build system for both Debug and Release builds by default,
+assuming that `VCPKG_BUILD_TYPE` is not set; if it is, then it will only configure for
+that build type.
+
+Use the `OPTIONS` argument to set the configure settings for both release and debug,
+and use `OPTIONS_RELEASE` and `OPTIONS_DEBUG` to set the configure settings for
+release only and debug only repsectively.
+
+By default, when possible, `vcpkg_cmake_configure` uses [ninja-build]
+as its build system. If the `WINDOWS_USE_MSBUILD` argument is passed, then
+`vcpkg_cmake_configure` will use a Visual Studio generator on Windows;
+on every other platform, `vcpkg_cmake_configure` just uses Ninja.
+
+[ninja-build]: https://ninja-build.org/
+
+Additionally, one may pass the specific generator a port should use with `GENERATOR`.
+This is useful if some project-specific buildsystem
+has been wrapped in a CMake build system that doesn't perform an actual build.
+If used for this purpose, it should be set to `"NMake Makefiles"`.
+`vcpkg_cmake_buildsystem_build` and `install` do not support this being set to anything
+except for NMake.
+
+For libraries which cannot be configured in parallel,
+pass the `DISABLE_PARALLEL_CONFIGURE` flag. This is needed, for example,
+if the library's build system writes back into the source directory during configure.
+This also disables the `CMAKE_DISABLE_SOURCE_CHANGES` option.
+
+By default, this function adds flags to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`
+which set the default character set to utf-8 for MSVC.
+If the library sets its own code page, pass the `NO_CHARSET_FLAG` option.
+
+`LOGFILE_BASE` is used to set the base of the logfile names;
+by default, this is `config`, and thus the logfiles end up being something like
+`config-x86-windows-dbg.log`. You can set it to anything you like;
+if you set it to `config-the-first`,
+you'll get something like `config-the-first-x86-windows.dbg.log`.
+
+## Notes
+This command supplies many common arguments to CMake. To see the full list, examine the source.
+
+## Examples
+
+* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
+
+## Source
+[ports/vcpkg-cmake/vcpkg\_cmake\_configure.cmake](https://github.com/Microsoft/vcpkg/blob/master/ports/vcpkg-cmake/vcpkg_cmake_configure.cmake)
diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_install.md
@@ -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)
diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/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)
diff --git a/docs/maintainers/vcpkg_add_to_path.md b/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)
diff --git a/docs/maintainers/vcpkg_apply_patches.md b/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)