[vcpkg_check_features] Set output variable explicitly and allow reverse-logic check (#7558)

* [vcpkg_check_features] Set OUT_EXPAND_OPTIONS explicitly

* [vcpkg_check_features] Allow reverse logic for features

* [vcpkg_check_features] Document new parameters

* [vcpkg_check_features] Remove unnecessary logging

* Do not create variables for each feature only set OUT_FEATURE_OPTIONS

* Improve documentation

* Update ports that use vcpkg_check_features()

* Missing documentation updates

* [pcl] Fix tools feature

* [opencv,opencv4] Fix usage of vcpkg_check_features()

* [opencv4] Fix typo

4 files changed, 148 insertions, 51 deletions

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index b98d89192..eadebf49a 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -24,4 +24,5 @@
 - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)

 - [vcpkg\_install\_cmake](vcpkg_install_cmake.md)

 - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)

+- [vcpkg\_prettify\_command](vcpkg_prettify_command.md)

 - [vcpkg\_test\_cmake](vcpkg_test_cmake.md)

diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md
index 46ee9051a..cec01dde2 100644
--- a/docs/maintainers/vcpkg_check_features.md
+++ b/docs/maintainers/vcpkg_check_features.md
@@ -1,71 +1,148 @@
 # vcpkg_check_features
-
-Check if one or more features are a part of the package installation.
+Check if one or more features are a part of a package installation.
 
 ## Usage
 ```cmake
 vcpkg_check_features(
-    <feature1> <output_variable1>
-    [<feature2> <output_variable2>]
-    ...
+  OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>  
+  [FEATURES
+    <cuda> <WITH_CUDA>
+    [<opencv> <WITH_OPENCV>]
+    ...]
+  [INVERTED_FEATURES
+    <cuda> <IGNORE_PACKAGE_CUDA>
+    [<opencv> <IGNORE_PACKAGE_OPENCV>]
+    ...]
 )
 ```
+`vcpkg_check_features()` accepts these parameters: 
 
-`vcpkg_check_features` accepts a list of (feature, output_variable) pairs. If a feature is specified, the corresponding output variable will be set as `ON`, or `OFF` otherwise. The syntax is similar to the `PROPERTIES` argument of `set_target_properties`.
+* `OUT_FEATURE_OPTIONS`:  
+  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.
+  
+* `FEATURES`:  
+  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.  
+  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:   
+    
+    * `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
+    * `-D<OPTION_NAME>=OFF`, otherwise. 
+
+* `INVERTED_FEATURES`:  
+  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.  
+  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. 
 
-`vcpkg_check_features` will create a variable `FEATURE_OPTIONS` in the parent scope, which you can pass as a part of `OPTIONS` argument when calling functions like `vcpkg_config_cmake`:
-```cmake
-vcpkg_config_cmake(
-    SOURCE_PATH ${SOURCE_PATH}
-    PREFER_NINJA
-    OPTIONS
-        -DBUILD_TESTING=ON
-        ${FEATURE_OPTIONS}
-)
-```
 
 ## 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`.
+
+
+## Examples
+
+### Example 1: Regular features
+
 ```cmake
-vcpkg_check_features(<feature> <output_variable>)
-```
-can be used as a replacement of:
-```cmake
-if(<feature> IN_LIST FEATURES)
-    set(<output_variable> ON)
-else()
-    set(<output_variable> OFF)
-endif()
+$ ./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
+    asm       MI_SEE_ASM
+    override  MI_OVERRIDE
+    secure    MI_SECURE
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
+    ${FEATURE_OPTIONS}
+)
 ```
 
-However, if you have a feature that was checked like this before:
+### Example 2: Inverted features
+
 ```cmake
-if(<feature> IN_LIST FEATURES)
-    set(<output_variable> OFF)
-else()
-    set(<output_variable> ON)
-endif()
+$ ./vcpkg install cpprestsdk[websockets]
+
+# ports/cpprestsdk/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
+    brotli      CPPREST_EXCLUDE_BROTLI
+    websockets  CPPREST_EXCLUDE_WEBSOCKETS
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
+    ${FEATURE_OPTIONS}
+)
 ```
-then you should not use `vcpkg_check_features` instead. [```oniguruma```](https://github.com/microsoft/vcpkg/blob/master/ports/oniguruma/portfile.cmake), for example, has a feature named `non-posix` which is checked with:
+
+### Example 3: Set multiple options for same feature
+
 ```cmake
-if("non-posix" IN_LIST FEATURES)
-    set(ENABLE_POSIX_API OFF)
-else()
-    set(ENABLE_POSIX_API ON)
-endif()
-```
-and by replacing these code with:
+$ ./vcpkg install pcl[cuda]
+
+# ports/pcl/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+    cuda  WITH_CUDA
+    cuda  BUILD_CUDA
+    cuda  BUILD_GPU
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
+    ${FEATURE_OPTIONS}
+)
+``` 
+
+### Example 4: Use regular and inverted features
+
 ```cmake
-vcpkg_check_features(non-posix ENABLE_POSIX_API)
-```
-is totally wrong.
+$ ./vcpkg install rocksdb[tbb]
 
-`vcpkg_check_features` is supposed to be called only once. Otherwise, the `FEATURE_OPTIONS` variable set by a previous call will be overwritten.
+# ports/rocksdb/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
+    tbb   WITH_TBB
+  INVERTED_FEATURES
+    tbb   ROCKSDB_IGNORE_PACKAGE_TBB
+)
 
-## Examples
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
+    ${FEATURE_OPTIONS}
+)
+``` 
+
+## Examples in portfiles
+
+* [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
+* [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
 
-* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
-* [xsimd](https://github.com/microsoft/vcpkg/blob/master/ports/xsimd/portfile.cmake)
-* [xtensor](https://github.com/microsoft/vcpkg/blob/master/ports/xtensor/portfile.cmake)
 
 ## Source
 [scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)

diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
index b78ef54d9..ebbd92ed1 100644
--- a/docs/maintainers/vcpkg_configure_cmake.md
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -18,14 +18,15 @@ vcpkg_configure_cmake(
 
 ## Parameters
 ### SOURCE_PATH
-Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+Specifies the directory containing the `CMakeLists.txt`.
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
 
 ### PREFER_NINJA
-Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja.
+Indicates that, when available, Vcpkg should use Ninja to perform the build.
+This should be specified unless the port is known to not work under Ninja.
 
 ### DISABLE_PARALLEL_CONFIGURE
 Disables running the CMake configure step in parallel.
-
 This is needed for libraries which write back into their source directory during configure.
 
 ### NO_CHARSET_FLAG
@@ -36,7 +37,8 @@ This is needed for libraries that set their own source code's character set.
 ### GENERATOR
 Specifies the precise generator to use.
 
-This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. If used for this purpose, it should be set to "NMake Makefiles".
+This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build.
+If used for this purpose, it should be set to "NMake Makefiles".
 
 ### OPTIONS
 Additional options passed to CMake during the configuration.
diff --git a/docs/maintainers/vcpkg_prettify_command.md b/docs/maintainers/vcpkg_prettify_command.md
new file mode 100644
index 000000000..1856e06b4
--- /dev/null
+++ b/docs/maintainers/vcpkg_prettify_command.md
@@ -0,0 +1,17 @@
+# vcpkg_prettify_command
+
+Turns list of command arguments into a formatted string.
+
+## Usage
+```cmake
+vcpkg_prettify_command()
+```
+
+## Examples
+
+* `scripts/cmake/vcpkg_execute_build_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
+
+## Source
+[scripts/cmake/vcpkg_prettify_command.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_prettify_command.cmake)