Merge branch 'master' into path_separator

5 files changed, 215 insertions, 69 deletions

diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
index e4938844f..f52172356 100644
--- a/docs/maintainers/maintainer-guide.md
+++ b/docs/maintainers/maintainer-guide.md
@@ -1,26 +1,37 @@
 # Maintainer Guidelines and Policies

 

-This document lists a set of policies that you should apply when adding or updating a port recipe. It is intended to serve the role of [Debian's Policy Manual](https://www.debian.org/doc/debian-policy/), [Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and [Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).

+This document lists a set of policies that you should apply when adding or updating a port recipe. 

+It is intended to serve the role of 

+[Debian's Policy Manual](https://www.debian.org/doc/debian-policy/), 

+[Homebrew's Maintainer Guidelines](https://docs.brew.sh/Maintainer-Guidelines), and 

+[Homebrew's Formula Cookbook](https://docs.brew.sh/Formula-Cookbook).

 

 ## PR Structure

 

 ### Make separate Pull Requests per port

 

-Whenever possible, separate changes into multiple PR's. This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.

+Whenever possible, separate changes into multiple PRs. 

+This makes them significantly easier to review and prevents issues with one set of changes from holding up every other change.

 

 ### Avoid trivial changes in untouched files

 

-For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand. However, if you need to modify the file for the primary purpose of the PR (updating the library), then obviously beneficial changes like fixing typos are appreciated!

+For example, avoid reformatting or renaming variables in portfiles that otherwise have no reason to be modified for the issue at hand. 

+However, if you need to modify the file for the primary purpose of the PR (updating the library), 

+then obviously beneficial changes like fixing typos are appreciated!

 

 ### Check names against other repositories

 

-A good service to check many at once is [Repology](https://repology.org/). If the library you are adding could be confused with another one, consider renaming to make it clear.

+A good service to check many at once is [Repology](https://repology.org/). 

+If the library you are adding could be confused with another one, 

+consider renaming to make it clear.

 

 ### Use GitHub Draft PRs

 

-GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge. Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.

+GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge. 

+Most new PRs should be opened as drafts and converted to normal PRs once the CI passes.

 

-More information about GitHub Draft PRs: https://github.blog/2019-02-14-introducing-draft-pull-requests/

+More information about GitHub Draft PRs: 

+https://github.blog/2019-02-14-introducing-draft-pull-requests/

 

 ## Portfiles

 

@@ -28,29 +39,33 @@ More information about GitHub Draft PRs: https://github.blog/2019-02-14-introduc
 

 At this time, the following helpers are deprecated:

 

-1. `vcpkg_extract_archive()` should be replaced by `vcpkg_extract_archive_ex()`

-2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. `vcpkg_from_github()`)

-3. `vcpkg_build_msbuild()` should be replaced by `vcpkg_install_msbuild()`

+1. `vcpkg_extract_archive()` should be replaced by [`vcpkg_extract_archive_ex()`](vcpkg_extract_archive_ex.md)

+2. `vcpkg_apply_patches()` should be replaced by the `PATCHES` arguments to the "extract" helpers (e.g. [`vcpkg_from_github()`](vcpkg_from_github.md))

+3. `vcpkg_build_msbuild()` should be replaced by [`vcpkg_install_msbuild()`](vcpkg_install_msbuild.md)

 

 ### Avoid excessive comments in portfiles

 

-Ideally, portfiles should be short, simple, and as declarative as possible. Remove any boiler plate comments introduced by the `create` command before submitting a PR.

+Ideally, portfiles should be short, simple, and as declarative as possible. 

+Remove any boiler plate comments introduced by the `create` command before submitting a PR.

 

 ## Build Techniques

 

 ### Do not use vendored dependencies

 

-Do not use embedded copies of libraries. All dependencies should be split out and packaged separately so they can be updated and maintained.

+Do not use embedded copies of libraries. 

+All dependencies should be split out and packaged separately so they can be updated and maintained.

 

 ### Prefer using CMake

 

-When multiple buildsystems are available, prefer using CMake. Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.

+When multiple buildsystems are available, prefer using CMake. 

+Additionally, when appropriate, it can be easier and more maintainable to rewrite alternative buildsystems into CMake using `file(GLOB)` directives.

 

 Examples: [abseil](../../ports/abseil/portfile.cmake)

 

 ### Choose either static or shared binaries

 

-By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`, however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:

+By default, `vcpkg_configure_cmake()` will pass in the appropriate setting for `BUILD_SHARED_LIBS`, 

+however for libraries that don't respect that variable, you can switch on `VCPKG_LIBRARY_LINKAGE`:

 

 ```cmake

 string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)

@@ -67,19 +82,37 @@ vcpkg_configure_cmake(
 

 ### When defining features, explicitly control dependencies

 

-When defining a feature that captures an optional dependency, ensure that the dependency will not be used accidentally when the feature is not explicitly enabled. For example:

+When defining a feature that captures an optional dependency, 

+ensure that the dependency will not be used accidentally when the feature is not explicitly enabled. 

 

 ```cmake

-set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)

-if("zlib" IN_LIST FEATURES)

-    set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)

+if ("zlib" IN_LIST FEATURES)

+  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)

+else()

+  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)

 endif()

 

 vcpkg_configure_cmake(

+  SOURCE_PATH ${SOURCE_PATH}

+  PREFER_NINJA

+  OPTIONS

+    -CMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}

+)

+```

+

+The snippet below using `vcpkg_check_features()` is equivalent,  [see the documentation](vcpkg_check_features.md).

+

+```cmake

+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS

+  INVERTED_FEATURES

+    "zlib"    CMAKE_DISABLE_FIND_PACKAGE_ZLIB

+)

+

+vcpkg_configure_cmake(

     SOURCE_PATH ${SOURCE_PATH}

     PREFER_NINJA

     OPTIONS

-        -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}

+      ${FEATURE_OPTIONS}    

 )

 ```

 

@@ -125,6 +158,22 @@ Common options that allow avoiding patching:
 2. [CMAKE] Calls to `find_package(XYz)` in CMake scripts can be disabled via [`-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html)

 3. [CMAKE] Cache variables (declared as `set(VAR "value" CACHE STRING "Documentation")` or `option(VAR "Documentation" "Default Value")`) can be overriden by just passing them in on the command line as `-DVAR:STRING=Foo`. One notable exception is if the `FORCE` parameter is passed to `set()`. See also the [CMake `set` documentation](https://cmake.org/cmake/help/v3.15/command/set.html)

 

+### Prefer patching over overriding `VCPKG_<VARIABLE>` values

+

+Some variables prefixed with `VCPKG_<VARIABLE>` have an equivalent `CMAKE_<VARIABLE>`.  

+However, not all of them are passed to the internal package build [(see implementation: Windows toolchain)](../../scripts/toolchains/windows.cmake).

+

+Consider the following example:

+

+```cmake

+set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")

+set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")

+```

+

+Using `vcpkg`'s built-in toolchains this works, because the value of `VCPKG_<LANG>_FLAGS` is forwarded to the appropriate `CMAKE_LANG_FLAGS` variable. But, a custom toolchain that is not aware of `vcpkg`'s variables will not forward them.

+

+Because of this, it is preferable to patch the buildsystem directly when setting `CMAKE_<LANG>_FLAGS`.

+

 ### Minimize patches

 

 When making changes to a library, strive to minimize the final diff. This means you should _not_ reformat the upstream source code when making changes that affect a region. Also, when disabling a conditional, it is better to add a `AND FALSE` or `&& 0` to the condition than to delete every line of the conditional.

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)