[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 <mazzucan@outlook.com>
Co-authored-by: PhoebeHui <20694052+PhoebeHui@users.noreply.github.com>

5 files changed, 107 insertions, 2 deletions

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(
         <configure-setting>...]
     [OPTIONS_DEBUG
         <configure-setting>...]
+    [MAYBE_UNUSED_VARIABLES
+        <variable-name>...]
 )
 ```
 
@@ -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 <option-name>...]
 )
 ```
 
@@ -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 <out-var> [<element>...])
+vcpkg_list(<COMMAND> <list-var> [<other-arguments>...])
+```
+
+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(<filename> <match> <replace>)
 ```
 
-
 ## Source
 [scripts/cmake/vcpkg\_replace\_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)