[host dependencies] add support in the scripts (#16627)

This contains all the docs and scripts changes from #16479,
without any of the ports changes, for easier CR

11 files changed, 128 insertions, 16 deletions

diff --git a/docs/index.md b/docs/index.md
index 492890bce..af8584fb9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -16,6 +16,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [Configuration and Environment](users/config-environment.md)
 - [Usage with Android](users/android.md)
 - [Using a manifest file to declare your dependencies](users/manifests.md)
+- [Host Dependencies](users/host-dependencies.md)
 
 ### Maintainer help
 
diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md
index 5fcb11ab2..a97723c1b 100644
--- a/docs/maintainers/vcpkg_common_definitions.md
+++ b/docs/maintainers/vcpkg_common_definitions.md
@@ -19,6 +19,10 @@ VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX       import library suffix for target (same
 VCPKG_FIND_LIBRARY_PREFIXES              target dependent prefixes used for find_library calls in portfiles
 VCPKG_FIND_LIBRARY_SUFFIXES              target dependent suffixes used for find_library calls in portfiles
 VCPKG_SYSTEM_LIBRARIES                   list of libraries are provide by the toolchain and are not managed by vcpkg
+TARGET_TRIPLET                           the name of the current triplet to build for
+CURRENT_INSTALLED_DIR                    the absolute path to the installed files for the current triplet
+HOST_TRIPLET                             the name of the triplet corresponding to the host
+CURRENT_HOST_INSTALLED_DIR               the absolute path to the installed files for the host triplet
 ```
 
 CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and CMAKE_IMPORT_LIBRARY_(PREFIX|SUFFIX) are defined for the target
diff --git a/docs/users/config-environment.md b/docs/users/config-environment.md
index 309a78654..e164bc0e7 100644
--- a/docs/users/config-environment.md
+++ b/docs/users/config-environment.md
@@ -38,11 +38,15 @@ Example: `D:\2017`
 

 This environment variable can be set to a triplet name which will be used for unqualified triplet references in command lines.

 

+#### VCPKG_DEFAULT_HOST_TRIPLET

+

+This environment variable can be set to a triplet name which will be used for unqualified host port references in command lines and all host port references in dependency lists. See [the Tools documentation](tools.md) for more information.

+

 #### VCPKG_OVERLAY_PORTS

 

 This environment variable allows users to override ports with alternate versions according to the

-[ports overlay](../specifications/ports-overlay.md) specification. List paths to overlays using 

-the platform dependent PATH seperator (Windows `;` | others `:`) 

+[ports overlay](../specifications/ports-overlay.md) specification. List paths to overlays using

+the platform dependent PATH seperator (Windows `;` | others `:`)

 

 Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3`

 

@@ -50,7 +54,7 @@ Example (Windows): `C:\custom-ports\boost;C:\custom-ports\sqlite3`
 

 This environment variable allows users to add directories to search for triplets.

 [Example: overlay triplets](../examples/overlay-triplets-linux-dynamic.md).

-List paths to overlays using the platform dependent PATH seperator (Windows `;`, others `:`) 

+List paths to overlays using the platform dependent PATH seperator (Windows `;`, others `:`)

 

 #### VCPKG_FORCE_SYSTEM_BINARIES

 

diff --git a/docs/users/host-dependencies.md b/docs/users/host-dependencies.md
new file mode 100644
index 000000000..061e21804
--- /dev/null
+++ b/docs/users/host-dependencies.md
@@ -0,0 +1,59 @@
+# Host Dependencies
+
+Tools used at build time by other ports to generate code or implement a custom build system can be packaged inside vcpkg.
+
+## Consuming
+
+When consuming a port as a tool, you must set the dependency's `"host"` field to true. For example:
+```json
+{
+    "name": "contoso-http-library",
+    "version-string": "1.0.0",
+    "description": "Contoso's http runtime library",
+    "dependencies": [
+        "contoso-core-library",
+        {
+            "name": "contoso-code-generator",
+            "host": true
+        },
+        {
+            "name": "contoso-build-system",
+            "host": true
+        }
+    ]
+}
+```
+In this case, the `contoso-code-generator` and `contoso-build-system` (including any transitive dependencies) will be built and installed for the host triplet before `contoso-http-library` is built.
+
+>Note: Consumers must use `vcpkg.json` instead of `CONTROL` as their metadata format. You can easily convert an existing `CONTROL` file using `vcpkg format-manifest /path/to/CONTROL`.
+
+Then, within the portfile of the consumer (`contoso-http-library` in the example), the CMake variable `CURRENT_HOST_INSTALLED_DIR` will be defined to `installed/<host-triplet>` and should be used to locate any required assets. In the example, `contoso-code-generator` might have installed `tools/contoso-code-generator/ccg.exe` which the consumer would add to its local path via
+```cmake
+# ports/contoso-http-library/portfile.cmake
+vcpkg_add_to_path(${CURRENT_HOST_INSTALLED_DIR}/tools/contoso-code-generator)
+```
+
+## Specifying the Host Triplet
+
+The default host triplets are chosen based on the host architecture and operating system, for example `x64-windows`, `x64-linux`, or `x64-osx`. They can be overridden via:
+
+1. In CMake-based manifest mode, calling `set(VCPKG_HOST_TRIPLET "<triplet>" CACHE STRING "")` before the first `project()` directive
+2. In MSBuild-based manifest mode, setting the `VcpkgHostTriplet` property
+3. On the command line, via the flag `--host-triplet=...`
+4. The `VCPKG_DEFAULT_HOST_TRIPLET` environment variable
+
+## Producing
+
+Producing a tool has no special requirements; tools should be authored as a standard port, following all the normal policies and practices. Notably, they should build against `TARGET_TRIPLET`, not `HOST_TRIPLET` within the context of their portfile.
+
+Sometimes, it can be useful to determine whether the current context is a cross-compiling one or not. This should be done by comparing the strings `TARGET_TRIPLET` and `HOST_TRIPLET`. For example:
+
+```cmake
+string(COMPARE EQUAL "${TARGET_TRIPLET}" "${HOST_TRIPLET}" I_AM_NOT_CROSSCOMPILING)
+
+if(TARGET_TRIPLET STREQUAL HOST_TRIPLET)
+    # This is a native build
+else()
+    # This is a cross build
+endif()
+```
diff --git a/docs/users/manifests.md b/docs/users/manifests.md
index e9736e364..2ee64ec3e 100644
--- a/docs/users/manifests.md
+++ b/docs/users/manifests.md
@@ -323,6 +323,20 @@ automatically bootstrapped if missing and invoked to install your dependencies i
 All vcpkg-affecting variables must be defined before the first `project()` directive, such as via the command line or
 `set()` statements.
 
+#### `VCPKG_TARGET_TRIPLET`
+
+This variable controls which triplet dependencies will be installed for.
+
+If unset, vcpkg will automatically detect an appropriate default triplet given the current compiler settings.
+
+#### `VCPKG_HOST_TRIPLET`
+
+This variable controls which triplet host dependencies will be installed for.
+
+If unset, vcpkg will automatically detect an appropriate native triplet (x64-windows, x64-osx, x64-linux).
+
+See also [Host Dependencies](host-dependencies.md).
+
 #### `VCPKG_MANIFEST_MODE`
 
 This variable controls whether vcpkg operates in manifest mode or in classic mode. To disable manifest mode even with a
@@ -443,6 +457,14 @@ This can be set to "false" to explicitly disable vcpkg integration for the proje
 
 This can be set to a custom triplet to use for integration (such as x64-windows-static)
 
+#### `VcpkgHostTriplet` (Host Triplet)
+
+This can be set to a custom triplet to use for resolving host dependencies.
+
+If unset, this will default to the "native" triplet (x64-windows, x64-osx, x64-linux).
+
+See also [Host Dependencies](host-dependencies.md).
+
 #### `VcpkgAdditionalInstallOptions` (Additional Options)
 
 When using a manifest, this option specifies additional command line flags to pass to the underlying vcpkg tool
diff --git a/scripts/buildsystems/msbuild/vcpkg-general.xml b/scripts/buildsystems/msbuild/vcpkg-general.xml
index 49865e74e..5c84aa0da 100644
--- a/scripts/buildsystems/msbuild/vcpkg-general.xml
+++ b/scripts/buildsystems/msbuild/vcpkg-general.xml
@@ -65,6 +65,9 @@
   <StringProperty Name="VcpkgTriplet" DisplayName="Triplet" Category="Conditional" Subtype="Text"
                   Description="Specifies the triplet used by Vcpkg. Does not include the '-static' suffix that may be added by the 'Use static libraries' flag." />
 
+  <StringProperty Name="VcpkgHostTriplet" DisplayName="Host Triplet" Category="Conditional" Subtype="Text"
+                  Description="Specifies the host triplet used by Vcpkg. If empty, this will be automatically determined." />
+
   <StringProperty Name="VcpkgAdditionalInstallOptions" DisplayName="Additional Options" Category="General" Subtype="Text"
                   Description="Additional command line options to be passed to the underlying vcpkg tool when installing in manifest mode." />
 
diff --git a/scripts/buildsystems/msbuild/vcpkg.targets b/scripts/buildsystems/msbuild/vcpkg.targets
index 074d35d90..b99011324 100644
--- a/scripts/buildsystems/msbuild/vcpkg.targets
+++ b/scripts/buildsystems/msbuild/vcpkg.targets
@@ -30,6 +30,10 @@
 
     <VcpkgConfigSubdir Condition="'$(VcpkgNormalizedConfiguration)' == 'Debug'">debug\</VcpkgConfigSubdir>
     <VcpkgApplocalDeps Condition="'$(VcpkgApplocalDeps)' == ''">true</VcpkgApplocalDeps>
+
+    <_ZVcpkgHostTripletParameter Condition="'$(VcpkgHostTriplet)' != ''">"--host-triplet=$(VcpkgHostTriplet)"</_ZVcpkgHostTripletParameter>
+    <_ZVcpkgExecutable>$([System.IO.Path]::Combine($(VcpkgRoot), 'vcpkg.exe'))</_ZVcpkgExecutable>
+
     <ProjectStateLine>VcpkgTriplet=$(VcpkgTriplet):$(ProjectStateLine)</ProjectStateLine>
   </PropertyGroup>
 
@@ -77,7 +81,7 @@
   <Target Name="VcpkgInstallManifestDependencies" BeforeTargets="ClCompile"
           Condition="'$(VcpkgEnabled)' == 'true' and '$(VcpkgEnableManifest)' == 'true' and '$(VcpkgManifestInstall)' == 'true'"
           Inputs="@(_ZVcpkgInstallManifestDependenciesInputs)"
-          Outputs="$(TLogLocation)VcpkgInstallManifest$(VcpkgTriplet).read.1u.tlog;$(VcpkgInstalledDir).msbuildstamp-$(VcpkgTriplet)">
+          Outputs="$(TLogLocation)VcpkgInstallManifest$(VcpkgTriplet).read.1u.tlog;$(VcpkgInstalledDir).msbuildstamp-$(VcpkgTriplet).$(VcpkgHostTriplet).stamp">
     <Message Text="Installing vcpkg dependencies to $(VcpkgInstalledDir)" Importance="High" />
     <MakeDir Directories="$(TLogLocation)" />
     <ItemGroup>
@@ -85,15 +89,15 @@
       <_VcpkgItemToDelete Include="$(VcpkgInstalledDir).msbuildstamp-*" />
     </ItemGroup>
     <Delete Files="@(_VcpkgItemToDelete)" />
-    <Message Text="%22$([System.IO.Path]::Combine($(VcpkgRoot), 'vcpkg.exe'))%22 install --x-wait-for-lock --triplet %22$(VcpkgTriplet)%22 --vcpkg-root %22$(VcpkgRoot)\%22 %22--x-manifest-root=$(VcpkgManifestRoot)\%22 %22--x-install-root=$(VcpkgInstalledDir)\%22 $(VcpkgAdditionalInstallOptions)"
+    <Message Text="%22$(_ZVcpkgExecutable)%22 install $(_ZVcpkgHostTripletParameter) --x-wait-for-lock --triplet %22$(VcpkgTriplet)%22 --vcpkg-root %22$(VcpkgRoot)\%22 %22--x-manifest-root=$(VcpkgManifestRoot)\%22 %22--x-install-root=$(VcpkgInstalledDir)\%22 $(VcpkgAdditionalInstallOptions)"
           Importance="High" />
-    <Exec Command="%22$([System.IO.Path]::Combine($(VcpkgRoot), 'vcpkg.exe'))%22 install --x-wait-for-lock --triplet %22$(VcpkgTriplet)%22 --vcpkg-root %22$(VcpkgRoot)\%22 %22--x-manifest-root=$(VcpkgManifestRoot)\%22 %22--x-install-root=$(VcpkgInstalledDir)\%22 $(VcpkgAdditionalInstallOptions)"
+    <Exec Command="%22$(_ZVcpkgExecutable)%22 install $(_ZVcpkgHostTripletParameter) --x-wait-for-lock --triplet %22$(VcpkgTriplet)%22 --vcpkg-root %22$(VcpkgRoot)\%22 %22--x-manifest-root=$(VcpkgManifestRoot)\%22 %22--x-install-root=$(VcpkgInstalledDir)\%22 $(VcpkgAdditionalInstallOptions)"
           StandardOutputImportance="High" />
-    <WriteLinesToFile File="$(TLogLocation)VcpkgInstallManifest$(VcpkgTriplet).read.1u.tlog"
+    <WriteLinesToFile File="$(TLogLocation)VcpkgInstallManifest$(VcpkgTriplet).$(VcpkgHostTriplet).read.1u.tlog"
                       Lines="@(_VcpkgInstallManifestDependenciesInputs -> '^%(Identity)')"
                       Encoding="Unicode"
                       Overwrite="true"/>
-    <Touch Files="$(VcpkgInstalledDir).msbuildstamp-$(VcpkgTriplet)" AlwaysCreate="true" />
+    <Touch Files="$(VcpkgInstalledDir).msbuildstamp-$(VcpkgTriplet).$(VcpkgHostTriplet).stamp" AlwaysCreate="true" />
 
     <CreateProperty Value="false">
       <Output TaskParameter="ValueSetByTask" PropertyName="Link_MinimalRebuildFromTracking" />
diff --git a/scripts/buildsystems/vcpkg.cmake b/scripts/buildsystems/vcpkg.cmake
index c830644e9..9bdf6573e 100644
--- a/scripts/buildsystems/vcpkg.cmake
+++ b/scripts/buildsystems/vcpkg.cmake
@@ -578,6 +578,11 @@ if(VCPKG_MANIFEST_MODE AND VCPKG_MANIFEST_INSTALL AND NOT Z_VCPKG_CMAKE_IN_TRY_C
         message(STATUS "Running vcpkg install")
 
         set(Z_VCPKG_ADDITIONAL_MANIFEST_PARAMS)
+
+        if(DEFINED VCPKG_HOST_TRIPLET AND NOT VCPKG_HOST_TRIPLET STREQUAL "")
+            list(APPEND Z_VCPKG_ADDITIONAL_MANIFEST_PARAMS "--host-triplet=${VCPKG_HOST_TRIPLET}")
+        endif()
+
         if(VCPKG_OVERLAY_PORTS)
             foreach(Z_VCPKG_OVERLAY_PORT IN LISTS VCPKG_OVERLAY_PORTS)
                 list(APPEND Z_VCPKG_ADDITIONAL_MANIFEST_PARAMS "--overlay-ports=${Z_VCPKG_OVERLAY_PORT}")
diff --git a/scripts/cmake/vcpkg_common_definitions.cmake b/scripts/cmake/vcpkg_common_definitions.cmake
index 897d30832..b505f3693 100644
--- a/scripts/cmake/vcpkg_common_definitions.cmake
+++ b/scripts/cmake/vcpkg_common_definitions.cmake
@@ -18,6 +18,10 @@ VCPKG_TARGET_IMPORT_LIBRARY_SUFFIX       import library suffix for target (same
 VCPKG_FIND_LIBRARY_PREFIXES              target dependent prefixes used for find_library calls in portfiles
 VCPKG_FIND_LIBRARY_SUFFIXES              target dependent suffixes used for find_library calls in portfiles
 VCPKG_SYSTEM_LIBRARIES                   list of libraries are provide by the toolchain and are not managed by vcpkg
+TARGET_TRIPLET                           the name of the current triplet to build for
+CURRENT_INSTALLED_DIR                    the absolute path to the installed files for the current triplet
+HOST_TRIPLET                             the name of the triplet corresponding to the host
+CURRENT_HOST_INSTALLED_DIR               the absolute path to the installed files for the host triplet
 ```
 
 CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and CMAKE_IMPORT_LIBRARY_(PREFIX|SUFFIX) are defined for the target
diff --git a/scripts/ports.cmake b/scripts/ports.cmake
index 62ee9f6aa..4adb48149 100644
--- a/scripts/ports.cmake
+++ b/scripts/ports.cmake
@@ -79,6 +79,9 @@ if(CMD MATCHES "^BUILD$")
         endforeach()
     endif()
 
+    set(HOST_TRIPLET "${_HOST_TRIPLET}")
+    set(CURRENT_HOST_INSTALLED_DIR "${_VCPKG_INSTALLED_DIR}/${HOST_TRIPLET}" CACHE PATH "Location to install final packages for the host")
+
     set(TRIPLET_SYSTEM_ARCH "${VCPKG_TARGET_ARCHITECTURE}")
     include("${SCRIPTS}/cmake/vcpkg_common_definitions.cmake")
     include("${SCRIPTS}/cmake/execute_process.cmake")
diff --git a/scripts/vcpkg.schema.json b/scripts/vcpkg.schema.json
index c485aa415..215f5dd9c 100644
--- a/scripts/vcpkg.schema.json
+++ b/scripts/vcpkg.schema.json
@@ -128,6 +128,10 @@
             "$ref": "#/definitions/identifier"
           }
         },
+        "host": {
+          "type": "boolean",
+          "default": false
+        },
         "default-features": {
           "type": "boolean",
           "default": true
@@ -190,9 +194,6 @@
       "description": "A package feature that can be activated by consumers.",
       "type": "object",
       "properties": {
-        "name": {
-          "$ref": "#/definitions/identifier"
-        },
         "description": {
           "$ref": "#/definitions/description-field"
         },
@@ -208,7 +209,6 @@
         "^\\$": {}
       },
       "required": [
-        "name",
         "description"
       ],
       "additionalProperties": false
@@ -279,10 +279,13 @@
           }
         },
         "features": {
-          "description": "An array of features supported by the package",
-          "type": "array",
-          "items": {
-            "$ref": "#/definitions/feature"
+          "description": "An object of features supported by the package",
+          "type": "object",
+          "patternProperties": {
+            "^\\$": {},
+            "^[a-z-]+": {
+              "$ref": "#/definitions/feature"
+            }
           }
         },
         "default-features": {