From 0e1dc121856eef84bf1852134e548bf9898dabac Mon Sep 17 00:00:00 2001 From: nicole mazzuca <83086508+strega-nil-ms@users.noreply.github.com> Date: Tue, 20 Jul 2021 12:24:58 -0500 Subject: [rollup] Rollup PR 2021-07-16 (#19001) * [rollup:2021-07-16 1/7] PR #18201 (@JackBoosY) [vcpkg-cmake] Add check for unused cmake variables * [rollup:2021-07-16 2/7] PR #18397 (@strega-nil) [vcpkg_list] add new function * [rollup:2021-07-16 3/7] PR #18782 (@strega-nil) [scripts-audit] vcpkg_build_ninja * [rollup:2021-07-16 4/7] PR #18784 (@strega-nil) [scripts-audit] vcpkg_minimum_required * [rollup:2021-07-16 5/7] PR #18785 (@strega-nil) [scripts-audit] vcpkg_replace_string * [rollup:2021-07-16 6/7] PR #18786 (@strega-nil) [scripts-audit] windows scripts * [rollup:2021-07-16 7/7] PR #18945 (@strega-nil) [many ports] remove deprecated vcpkg_check_features call [1/5] Co-authored-by: nicole mazzuca Co-authored-by: PhoebeHui <20694052+PhoebeHui@users.noreply.github.com> --- docs/maintainers/portfile-functions.md | 1 + .../ports/vcpkg-cmake/vcpkg_cmake_configure.md | 7 ++ docs/maintainers/vcpkg_configure_cmake.md | 4 + docs/maintainers/vcpkg_list.md | 94 ++++++++++++++++++++++ docs/maintainers/vcpkg_replace_string.md | 3 +- 5 files changed, 107 insertions(+), 2 deletions(-) create mode 100644 docs/maintainers/vcpkg_list.md (limited to 'docs') diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index d6acc6471..0ba3533e2 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -51,6 +51,7 @@ - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md) - [vcpkg\_install\_nmake](vcpkg_install_nmake.md) - [vcpkg\_install\_qmake](vcpkg_install_qmake.md) +- [vcpkg\_list](vcpkg_list.md) - [vcpkg\_minimum\_required](vcpkg_minimum_required.md) - [vcpkg\_replace\_string](vcpkg_replace_string.md) diff --git a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md index 95830313d..3745df080 100644 --- a/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md +++ b/docs/maintainers/ports/vcpkg-cmake/vcpkg_cmake_configure.md @@ -18,6 +18,8 @@ vcpkg_cmake_configure( ...] [OPTIONS_DEBUG ...] + [MAYBE_UNUSED_VARIABLES + ...] ) ``` @@ -56,6 +58,11 @@ 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. +This function makes certain that all options passed in are used by the +underlying CMake build system. If there are options that might be unused, +perhaps on certain platforms, pass those variable names to +`MAYBE_UNUSED_VARIABLES`. + `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; diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md index 195017b3c..fd6ce1318 100644 --- a/docs/maintainers/vcpkg_configure_cmake.md +++ b/docs/maintainers/vcpkg_configure_cmake.md @@ -17,6 +17,7 @@ vcpkg_configure_cmake( [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] [OPTIONS_RELEASE <-DOPTIMIZE=1>...] [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] + [MAYBE_UNUSED_VARIABLES ...] ) ``` @@ -55,6 +56,9 @@ Additional options passed to CMake during the Release configuration. These are i ### OPTIONS_DEBUG Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`. +### MAYBE_UNUSED_VARIABLES +Any CMake variables which are explicitly passed in, but which may not be used on all platforms. + ### LOGNAME Name of the log to write the output of the configure call to. diff --git a/docs/maintainers/vcpkg_list.md b/docs/maintainers/vcpkg_list.md new file mode 100644 index 000000000..46aa7dabd --- /dev/null +++ b/docs/maintainers/vcpkg_list.md @@ -0,0 +1,94 @@ +# vcpkg_list + +The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_list.md). + +A replacement for CMake's `list()` function, which correctly handles elements +with internal semicolons (in other words, escaped semicolons). +Use `vcpkg_list()` instead of `list()` whenever possible. + +```cmake +vcpkg_list(SET [...]) +vcpkg_list( [...]) +``` + +In addition to all of the commands from `list()`, `vcpkg_list` adds +a `vcpkg_list(SET)` command. +This command takes its arguments, escapes them, and then concatenates +them into a list; this should be used instead of `set()` for setting any +list variable. + +Otherwise, the `vcpkg_list()` function is the same as the built-in +`list()` function, with the following restrictions: + +- `GET`, `REMOVE_ITEM`, and `REMOVE_AT` support only one index/value +- `POP_BACK` and `POP_FRONT` do not support getting the value into + another out variable. Use C++ style `GET` then `POP_(BACK|FRONT)`. +- `FILTER` and `TRANSFORM` are unsupported. + +See the [CMake documentation for `list()`](https://cmake.org/cmake/help/latest/command/list.html) +for more information. + +## Notes: Some Weirdnesses + +The most major weirdness is due to `""` pulling double-duty as "list of zero elements", +and "list of one element, which is empty". `vcpkg_list` always uses the former understanding. +This can cause weird behavior, for example: + +```cmake +set(lst "") +vcpkg_list(APPEND lst "" "") +# lst = ";" +``` + +This is because you're appending two elements to the empty list. +One very weird behavior that comes out of this would be: + +```cmake +set(lst "") +vcpkg_list(APPEND lst "") +# lst = "" +``` + +since `""` is the empty list, we append the empty element and end up with a list +of one element, which is empty. This does not happen for non-empty lists; +for example: + +```cmake +set(lst "a") +vcpkg_list(APPEND lst "") +# lst = "a;" +``` + +only the empty list has this odd behavior. + +## Examples + +### Creating a list + +```cmake +vcpkg_list(SET foo_param) +if(DEFINED arg_FOO) + vcpkg_list(SET foo_param FOO "${arg_FOO}") +endif() +``` + +### Appending to a list + +```cmake +set(OPTIONS -DFOO=BAR) +if(VCPKG_TARGET_IS_WINDOWS) + vcpkg_list(APPEND OPTIONS "-DOS=WINDOWS;FOO") +endif() +``` + +### Popping the end off a list + +```cmake +if(NOT list STREQUAL "") + vcpkg_list(GET list end -1) + vcpkg_list(POP_BACK list) +endif() +``` + +## Source +[scripts/cmake/vcpkg\_list.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_list.cmake) diff --git a/docs/maintainers/vcpkg_replace_string.md b/docs/maintainers/vcpkg_replace_string.md index 179b8a08d..967dd3c01 100644 --- a/docs/maintainers/vcpkg_replace_string.md +++ b/docs/maintainers/vcpkg_replace_string.md @@ -5,9 +5,8 @@ The latest version of this document lives in the [vcpkg repo](https://github.com Replace a string in a file. ```cmake -vcpkg_replace_string(filename match_string replace_string) +vcpkg_replace_string( ) ``` - ## Source [scripts/cmake/vcpkg\_replace\_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake) -- cgit v1.2.3