[vcpkg] Add Supports: field. Use contents of triplets instead of names for dependency resolution. (#8601)

* remove unfinished "supports" tag

* extract "supports" from control files
But do nothing with the value

* Start `Supports` documentation

* Use Supports in a bunch of control files

I only tried matching the already existing logic in the portfile.cmake.

* Cmake var provider (#8)

* Cmake var provider (#9)

* fix windows build (#10)

* Add missing files to build

* Fix test (#11)

* adding hooks for cmake variables in expressions

* Adding hooks for 'supports' in CI test

* Fix test (#12)

* Add overrides to evaluation environment

* use "supported" tag in CI testing

* cleanup comment

* Fix issues with PR

* [var_provider] Get library linkage variables from triplet

* Fix compilation errors in tests

* Add unimplemented functions

* Fix unit tests part 1

* Fix issue when buildtrees dir does not exist

* Change binary output hash

* Fix handling of * feature

* Add core feature when using *

* Do not add Default-Features when installing 'core'

* [vcpkg] WIP. 6 failing tests.

* [vcpkg] WIP. 1 failing tests.

* [vcpkg] WIP. 0 failing tests.

* [vcpkg] Removed 'remove_graph'. 0 failing tests.

* [vcpkg] Removed 'install_graph'. 0 failing tests.

* [vcpkg] Remove AnyAction; replace with ActionPlan

* [vcpkg] Minor cleanup.

* [vcpkg][z3][qt5-connectivity][qt5-purchasing] Improve error messages while parsing. Fix a few trivial port issues.

* [vcpkg] Work around ICE with MSVC v140

* [vcpkg] Add purge on fail to decompress for CI

* [vcpkg] Fix parsing of nested parentheses in qualifiers

* [vcpkg] Fix Linux builds (explicit qualification in declaration)

* [vcpkg] Fix Build-Depends implying default features. Fix qualified dependencies regression.

* [mmx] Add to skip list and full rebuild -- mmx causes problems by installing 'sched.h'

* [libpqxx][mqtt-cpp] Prevent installing include/CMakeLists.txt

* [cppitertools] Fix installed include namespace (should be include/cppitertools)

* [libsoundio] Move headers into soundio/ subdirectory as per original cmake

* [ci.baseline] Temporarily skip charls due to conflict with dcmtk

* [vcpkg] Add restricted include files post build check -- bump global abi version

* [libsoundio] Hotfix stray line in portfile

* [vcpkg] Fix regression: CMake information was not being displayed for build-and-install actions

* [jsonnet] Fix installation of internal headers; use system nlohmann-json

* [grpc][upb] Teach grpc to use packaged upb. Add find_package(upb). Remove inappropriate upb features.

* [zfp] Move problematic 'include/bitstream.h' to 'include/zfp/bitstream.h'

* [x265] Bump control version to trigger rebuild after zfp conflict

* [akali] Disable parallel configure

* [dirent][dlfcn-win32][getopt-win32][pthreads] Grandfather into VCPKG_POLICY_ALLOW_RESTRICTED_HEADERS

* [ci.baseline] Update baseline for improved upb support

* [tgui] Disable parallel configure

* [libiconv] Enable VCPKG_POLICY_ALLOW_RESTRICTED_HEADERS

* [aws-sdk-cpp] Disable parallel configure

* [vcpkg] Implement policy VCPKG_POLICY_ALLOW_RESTRICTED_HEADERS

* [aws-sdk-cpp] Fix amount of escaping semicolons -- Note: I do not know the root cause requiring this change

* [libodb-sqlite] Fix configuring into source directory

* [gettext] Grandfather into VCPKG_POLICY_ALLOW_RESTRICTED_HEADERS

* [libodb] DISABLE_PARALLEL_CONFIGURE

* [vcpkg] Add 'config.h' and 'local.h' to restricted header list

* [mcpp] Remove unused and problematic include 'config.h' from installed files

* [teemo] Move installed headers into subdirectory to prevent conflicts with x265

* [ci.baseline] Update current OSX. Skip libmesh on all platforms due to heavy conflicts.

* [vcpkg] Add 'slice.h' as a restricted header

* [osg] Improve accuracy of dependencies (disable some, add some to Depends)

* [vcpkg] Skip invoking a subprocess for 0 specs in load_tag_vars

* [ci.baseline] Skip mongo-c-driver on osx due to flakiness

* [teemo] Fix incorrect include file read

* [osg] Fix dependency typo: glut -> freeglut

* [vcpkg] Recover some lost performance with the addition of vcpkg_get_tags.

A huge performance cost was loading the triplet files over and over; instead, we splice the sources into a macro and load it once, then just call that macro for each port.
Remove use of hashing because we aren't cross-process-safe anyway (global static will do instead).

* [vcpkg] Change Supports atom 'windows' to include UWP. Improve Supports field documentation.

* [vcpkg] Add docs for VCPKG_ENV_PASSTHROUGH and VCPKG_DEP_INFO_OVERRIDE_VARS

* Fix typo

Co-authored-by: Curtis J Bezault <curtbezault@gmail.com>
Co-authored-by: Victor Romero <romerosanchezv@gmail.com>
Co-authored-by: Robert Schumacher <roschuma@microsoft.com>

2 files changed, 68 insertions, 18 deletions

diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md
index a074a7ae2..87468e6af 100644
--- a/docs/maintainers/control-files.md
+++ b/docs/maintainers/control-files.md
@@ -8,7 +8,7 @@ Field names are case-sensitive and start the line without leading whitespace.  P
 
 ## Source Paragraph
 
-The first paragraph in a `CONTROL` file is the Source paragraph.  It must have a `Source`, `Version`, and `Description` field.  It can optionally have a `Build-Depends` and `Default-Features` field.
+The first paragraph in a `CONTROL` file is the Source paragraph.  It must have a `Source`, `Version`, and `Description` field. The full set of fields is documented below.
 
 ### Examples:
 ```no-highlight
@@ -58,7 +58,7 @@ For example, given:
 
 Then if you update the source version today, you should give it version `2019-06-01`. If you need to make a change which doesn't adjust the source version, you should give it version `2019-02-14-2`.
 
-Example:
+##### Examples:
 ```no-highlight
 Version: 1.0.5-2
 ```
@@ -71,7 +71,7 @@ A description of the library.
 
 By convention the first line of the description is a summary of the library.  An optional detailed description follows.  The detailed description can be multiple lines, all starting with whitespace.
 
-Example:
+##### Examples:
 ```no-highlight
 Description: C++ header-only JSON library
 ```
@@ -96,17 +96,13 @@ Vcpkg does not distinguish between build-only dependencies and runtime dependenc
 
 *For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies*
 
-Example:
-```no-highlight
-Build-Depends: zlib, libpng, libjpeg-turbo, tiff
-```
-If the port is dependent on optional features of another library those can be specified using the `portname[featurelist]` syntax.
+If the port is dependent on optional features of another library those can be specified using the `portname[featurelist]` syntax. If the port does not require any features from the dependency, this should be specifed as `portname[core]`.
 
-Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside parentheses is substring-compared against the triplet name.  There must be a space between the name of the port and the filter. __This will change in a future version to not depend on the triplet name.__
+Dependencies can be filtered based on the target triplet to support differing requirements. These filters use the same syntax as the Supports field below and are surrounded in parentheses following the portname and feature list.
 
-Example:
+##### Example:
 ```no-highlight
-Build-Depends: curl[openssl] (!windows&!osx), curl[winssl] (windows), curl[darwinssl] (osx)
+Build-Depends: rapidjson, curl[core,openssl] (!windows), curl[core,winssl] (windows)
 ```
 
 #### Default-Features
@@ -114,10 +110,46 @@ Comma separated list of optional port features to install by default.
 
 This field is optional.
 
+##### Example:
 ```no-highlight
 Default-Features: dynamodb, s3, kinesis
 ```
 
+<a name="Supports"></a>
+#### Supports
+Expression that evaluates to true when the port is expected to build successfully for a triplet.
+
+Currently, this field is only used in the CI testing to skip ports. In the future, this mechanism is intended to warn users in advance that a given install tree is not expected to succeed. Therefore, this field should be used optimistically; in cases where a port is expected to succeed 10% of the time, it should still be marked "supported".
+
+The grammar for the supports expression uses standard operators:
+- `!expr` - negation
+- `expr|expr` - or (`||` is also supported)
+- `expr&expr` - and (`&&` is also supported)
+- `(expr)` - grouping/precedence
+
+The predefined expressions are computed from standard triplet settings:
+- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"`
+- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"`
+- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
+- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
+- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
+- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
+- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
+- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
+- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
+- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"`
+
+These predefined expressions can be overridden in the triplet file via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option.
+
+This field is optional and defaults to true.
+
+> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism.
+
+##### Example:
+```no-highlight
+Supports: !(uwp|arm)
+```
+
 ## Feature Paragraphs
 
 Multiple optional features can be specified in the `CONTROL` files.  It must have a `Feature` and `Description` field.  It can optionally have a `Build-Depends` field.  It must be separated from other paragraphs by one or more empty lines.
diff --git a/docs/users/triplets.md b/docs/users/triplets.md
index 6e52d347d..21dea5c31 100644
--- a/docs/users/triplets.md
+++ b/docs/users/triplets.md
@@ -2,20 +2,17 @@
 
 Triplet is a standard term used in cross compiling as a way to completely capture the target environment (cpu, os, compiler, runtime, etc) in a single convenient name.
 
-In Vcpkg, we use triplets to describe self-consistent builds of library sets. This means every library will be built using the same target cpu, OS, and compiler toolchain, but also CRT linkage and preferred library type.
+In Vcpkg, we use triplets to describe an imaginary "target configuration set" for every library. Within a triplet, libraries are generally built with the same configuration, but it is not a requirement. For example, you could have one triplet that builds `openssl` statically and `zlib` dynamically, one that builds them both statically, and one that builds them both dynamically (all for the same target OS and architecture). A single build will consume files from a single triplet.
 
 We currently provide many triplets by default (run `vcpkg help triplet`). However, you can easily add your own by creating a new file in the `triplets\` directory. The new triplet will immediately be available for use in commands, such as `vcpkg install boost:x86-windows-custom`.
 
 To change the triplet used by your project, such as to enable static linking, see our [Integration Document](integration.md#triplet-selection).
 
-
 ## Community triplets
 
-Triplets contained in the `triplets\community` folder are not tested by continuous integration.
-
-These triplets contain configurations commonly requested by the community, but for which we lack the resources to properly test.
+Triplets contained in the `triplets\community` folder are not tested by continuous integration, but are commonly requested by the community.
 
-Port updates may break compatibility with community triplets, such regressions won't get caught by our testing pipelines. Because of this, community involvement is paramount!
+Because we do not have continuous coverage, port updates may break compatibility with community triplets. Because of this, community involvement is paramount!
 
 We will gladly accept and review contributions that aim to solve issues with these triplets.
 
@@ -23,7 +20,7 @@ We will gladly accept and review contributions that aim to solve issues with the
 
 Community Triplets are enabled by default, when using a community triplet a message like the following one will be printed during a package install:
 
-```bash
+```no-highlight
 -- Using community triplet x86-uwp. This triplet configuration is not guaranteed to succeed.
 -- [COMMUNITY] Loading triplet configuration from: D:\src\viromer\vcpkg\triplets\community\x86-uwp.cmake
 ```
@@ -78,8 +75,29 @@ This option also has forms for configuration-specific and C flags:
 - `VCPKG_C_FLAGS_DEBUG`
 - `VCPKG_C_FLAGS_RELEASE`
 
+<a name="VCPKG_DEP_INFO_OVERRIDE_VARS"></a>
+### VCPKG_DEP_INFO_OVERRIDE_VARS
+Replaces the default computed list of triplet "Supports" terms.
+
+This option (if set) will override the default set of terms used for qualified dependency resolution and "Supports" field evaluation.
+
+See the [`Supports`](../maintainers/control-files.md#Supports) control file field documentation for more details.
+
+> Implementers' Note: this list is extracted via the `vcpkg_get_dep_info` mechanism.
+
 ## Windows Variables
 
+### VCPKG_ENV_PASSTHROUGH
+Instructs vcpkg to allow additional environment variables into the build process.
+
+On Windows, vcpkg builds packages in a special clean environment that is isolated from the current command prompt to ensure build reliability and consistency.
+
+This triplet option can be set to a list of additional environment variables that will be added to the clean environment.
+
+See also the `vcpkg env` command for how you can inspect the precise environment that will be used.
+
+> Implementers' Note: this list is extracted via the `vcpkg_get_tags` mechanism.
+
 <a name="VCPKG_VISUAL_STUDIO_PATH"></a>
 ### VCPKG_VISUAL_STUDIO_PATH
 Specifies the Visual Studio installation to use.