[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

2 files changed, 173 insertions, 88 deletions

diff --git a/scripts/cmake/vcpkg_check_features.cmake b/scripts/cmake/vcpkg_check_features.cmake
index d089ac5b1..81ebc234d 100644
--- a/scripts/cmake/vcpkg_check_features.cmake
+++ b/scripts/cmake/vcpkg_check_features.cmake
@@ -1,112 +1,191 @@
 ## # 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 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`.
-##
-## `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}
-## )
-## ```
-##
+## `vcpkg_check_features()` accepts these parameters: 
+## 
+## * `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. 
+## 
+## 
 ## ## 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_check_features` is supposed to be called only once. Otherwise, the `FEATURE_OPTIONS` variable set by a previous call will be overwritten.
-##
-## ## Examples
-##
-## * [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)
+## $ ./vcpkg install rocksdb[tbb]
+## 
+## # 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
+## )
+## 
+## 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)
+## 
 function(vcpkg_check_features)
-    cmake_parse_arguments(_vcf "" "" "" ${ARGN})
-
-    list(LENGTH ARGN _vcf_ARGC)
-    math(EXPR _vcf_INCORRECT_ARGN "${_vcf_ARGC} % 2")
+    cmake_parse_arguments(_vcf "" "OUT_FEATURE_OPTIONS" "FEATURES;INVERTED_FEATURES" ${ARGN})
 
-    if(_vcf_INCORRECT_ARGN)
-        message(FATAL_ERROR "Called with incorrect number of arguments.")
+    if (NOT DEFINED _vcf_OUT_FEATURE_OPTIONS)
+        message(FATAL_ERROR "OUT_FEATURE_OPTIONS must be specified.")
     endif()
 
-    set(_vcf_IS_FEATURE_ARG ON)
-    set(_vcf_FEATURE_OPTIONS)
-
-    # Process (feature, output_var) pairs
-    foreach(_vcf_ARG ${ARGN})
-        if(_vcf_IS_FEATURE_ARG)
-            set(_vcf_FEATURE ${_vcf_ARG})
-
-            if(NOT ${_vcf_FEATURE} IN_LIST ALL_FEATURES)
-                message(FATAL_ERROR "Unknown feature: ${_vcf_FEATURE}")
-            endif()
-
-            set(_vcf_IS_FEATURE_ARG OFF)
-        else()
-            set(_vcf_FEATURE_VAR ${_vcf_ARG})
+    macro(_check_features _vcf_ARGUMENT _set_if _set_else)
+        list(LENGTH ${_vcf_ARGUMENT} FEATURES_SET_LEN)
+        math(EXPR _vcf_INCORRECT_ARGN "${FEATURES_SET_LEN} % 2")
+        if(_vcf_INCORRECT_ARGN)
+            message(FATAL_ERROR "Called with incorrect number of arguments.")
+        endif()
 
-            if(${_vcf_FEATURE} IN_LIST FEATURES)
-                set(${_vcf_FEATURE_VAR} ON PARENT_SCOPE)
-                list(APPEND _vcf_FEATURE_OPTIONS "-D${_vcf_FEATURE_VAR}=ON")
+        set(_vcf_IS_FEATURE_NAME_ARG ON)
+        foreach(_vcf_ARG ${${_vcf_ARGUMENT}})
+            if(_vcf_IS_FEATURE_NAME_ARG)
+                set(_vcf_FEATURE_NAME ${_vcf_ARG})
+                if(NOT ${_vcf_FEATURE_NAME} IN_LIST ALL_FEATURES)
+                    message(FATAL_ERROR "Unknown feature: ${_vcf_FEATURE_NAME}")
+                endif()
+                set(_vcf_IS_FEATURE_NAME_ARG OFF)
             else()
-                set(${_vcf_FEATURE_VAR} OFF PARENT_SCOPE)
-                list(APPEND _vcf_FEATURE_OPTIONS "-D${_vcf_FEATURE_VAR}=OFF")
+                set(_vcf_FEATURE_VARIABLE ${_vcf_ARG})
+                if(${_vcf_FEATURE_NAME} IN_LIST FEATURES)
+                    list(APPEND _vcf_FEATURE_OPTIONS "-D${_vcf_FEATURE_VARIABLE}=${_set_if}")
+                else()
+                    list(APPEND _vcf_FEATURE_OPTIONS "-D${_vcf_FEATURE_VARIABLE}=${_set_else}")
+                endif()
+                set(_vcf_IS_FEATURE_NAME_ARG ON)
             endif()
+        endforeach()
+    endmacro()
 
-            set(_vcf_IS_FEATURE_ARG ON)
-        endif()
-    endforeach()
+    set(_vcf_FEATURE_OPTIONS)
 
-    if(DEFINED FEATURE_OPTIONS)
-        message(WARNING "FEATURE_OPTIONS is already defined and will be overwritten.")
+    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(FEATURE_OPTIONS ${_vcf_FEATURE_OPTIONS} PARENT_SCOPE)
+    set(${_vcf_OUT_FEATURE_OPTIONS} "${_vcf_FEATURE_OPTIONS}" PARENT_SCOPE)
 endfunction()
diff --git a/scripts/cmake/vcpkg_configure_cmake.cmake b/scripts/cmake/vcpkg_configure_cmake.cmake
index 37362a5a2..6c392d385 100644
--- a/scripts/cmake/vcpkg_configure_cmake.cmake
+++ b/scripts/cmake/vcpkg_configure_cmake.cmake
@@ -8,6 +8,7 @@
 ##     SOURCE_PATH <${SOURCE_PATH}>
 ##     [PREFER_NINJA]
 ##     [DISABLE_PARALLEL_CONFIGURE]
+##     [NO_CHARSET_FLAG]
 ##     [GENERATOR <"NMake Makefiles">]
 ##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
 ##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
@@ -28,6 +29,11 @@
 ## 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
+## Disables passing `utf-8` as the default character set to `CMAKE_C_FLAGS` and `CMAKE_CXX_FLAGS`.
+##
+## This is needed for libraries that set their own source code's character set.
+##
 ## ### GENERATOR
 ## Specifies the precise generator to use.
 ##