From c5ca6fd46b5816dcf41ae8e0ab9a9aea49363557 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Fri, 23 Sep 2022 12:30:43 -0700 Subject: [PATCH] [docs] Fix issues encountered during publishing 2022-09-01 (#26794) * [docs] Document 'host' field in manifests * [docs] Assorted fixes found while regenerating website * Update docs/users/manifests.md Co-authored-by: Victor Romero --- docs/commands/common-options.md | 2 +- docs/commands/install.md | 14 ++++++++------ docs/commands/remove.md | 2 +- docs/commands/update-baseline.md | 8 ++++---- docs/users/manifests.md | 20 ++++++++++++++------ 5 files changed, 28 insertions(+), 18 deletions(-) diff --git a/docs/commands/common-options.md b/docs/commands/common-options.md index 86fb64595b64da..c58fb984fdde76 100644 --- a/docs/commands/common-options.md +++ b/docs/commands/common-options.md @@ -56,7 +56,7 @@ Specifies the path to lay out installed packages. In Classic Mode, defaults to `installed/` under the vcpkg root folder. -In [Manifest Mode][../users/manifests.md], defaults to `vcpkg_installed/` under the manifest folder. +In [Manifest Mode](../users/manifests.md), defaults to `vcpkg_installed/` under the manifest folder. diff --git a/docs/commands/install.md b/docs/commands/install.md index 6db460d34cf37b..f79929edb80d13 100644 --- a/docs/commands/install.md +++ b/docs/commands/install.md @@ -45,7 +45,7 @@ All vcpkg commands support a set of [common options](common-options.md). Instead of stopping on an unsupported port, continue with a warning. -By default, vcpkg refuses to execute an install plan containing a port installation for a triplet outside its [`"supports"`][] clause. The [`"supports"`][] clause of a package describes the full set of platforms a package is expected to be buildable on. This flag instructs vcpkg to warn that the build is expected to fail instead of stopping. +By default, vcpkg refuses to execute an install plan containing a port installation for a triplet outside its [`"supports"`][supports] clause. The [`"supports"`][supports] clause of a package describes the full set of platforms a package is expected to be buildable on. This flag instructs vcpkg to warn that the build is expected to fail instead of stopping. ### `--clean-after-build` @@ -103,6 +103,8 @@ Fail install if a port has detected problems or attempts to use a deprecated fea By default, vcpkg will run several checks on built packages and emit warnings if any issues are detected. This flag upgrades those warnings to an error. + + ### `--x-feature=` **Experimental and may change or be removed at any time** @@ -111,7 +113,7 @@ By default, vcpkg will run several checks on built packages and emit warnings if Specify an additional [feature](../users/manifests.md#features) from the `vcpkg.json` to install dependencies for. -By default, only [`"dependencies"`](../users/manifests.md#dependencies) and the dependencies of the [`"default-features"`](../users/manifests.md#default-features) will be installed. +By default, only [`"dependencies"`][dependencies] and the dependencies of the [`"default-features"`][default-features] will be installed. ### `--head` @@ -135,7 +137,7 @@ By default, vcpkg will stop at the first package build failure. This flag instru Don't install the default features from the top-level manifest. -When using `install` in Manifest Mode, by default all dependencies of the features listed in [`"default-features"`][] will be installed. This flag disables that behavior so (without any `TODO` flags) only the dependencies listed in [`"dependencies"`][] will be installed. +When using `install` in Manifest Mode, by default all dependencies of the features listed in [`"default-features"`][default-features] will be installed. This flag disables that behavior so only features explicitly enabled by [`--x-feature`](#feature) will be installed. ### `--no-downloads` @@ -186,6 +188,6 @@ Suppress generation of usage text printed at the end of installation. [Asset Caching]: ../users/assetcaching.md [Binary Caching]: ../users/binarycaching.md [Manifest Mode]: ../users/manifests.md -[`"supports"`]: ../users/manifests.md#supports -[`"default-features"`]: ../users/manifests.md#default-features -[`"dependencies"`]: ../users/manifests.md#dependencies +[supports]: ../users/manifests.md#supports +[default-features]: ../users/manifests.md#default-features +[dependencies]: ../users/manifests.md#dependencies diff --git a/docs/commands/remove.md b/docs/commands/remove.md index dd47374aab0fe0..4e1cb0c1c25703 100644 --- a/docs/commands/remove.md +++ b/docs/commands/remove.md @@ -16,7 +16,7 @@ vcpkg remove --outdated [options] Remove port packages from Classic Mode. -`remove` removes listed packages and any packages that require them from the Classic Mode [installed directory][common-options.md#install-root]. See the [install command documentation](install.md#package-syntax) for detailed syntax of the `` parameter. +`remove` removes listed packages and any packages that require them from the Classic Mode [installed directory](common-options.md#install-root). See the [install command documentation](install.md#package-syntax) for detailed syntax of the `` parameter. This command is not currently supported in [Manifest Mode][]. diff --git a/docs/commands/update-baseline.md b/docs/commands/update-baseline.md index 3b499b2551f691..8a5b36711f11d3 100644 --- a/docs/commands/update-baseline.md +++ b/docs/commands/update-baseline.md @@ -14,7 +14,7 @@ vcpkg x-update-baseline [options] [--add-initial-baseline] [--dry-run] Update baselines for all configured [registries][]. -In [Manifest Mode][], this command operates on all [registries][] in the `vcpkg.json` and the [`vcpkg-configuration.json`][]. In Classic Mode, this command operates on the [`vcpkg-configuration.json`][] in the vcpkg instance (`$VCPKG_ROOT`). +In [Manifest Mode][], this command operates on all [registries][] in the `vcpkg.json` and the [`vcpkg-configuration.json`][vcj]. In Classic Mode, this command operates on the [`vcpkg-configuration.json`][vcj] in the vcpkg instance (`$VCPKG_ROOT`). See the [versioning documentation](../users/versioning.md#baselines) for more information about baselines. @@ -32,11 +32,11 @@ Print the planned baseline upgrades, but do not modify the files on disk. **[Manifest Mode][] Only** -Add a [`"builtin-baseline"`][] field to the `vcpkg.json` if it does not already have one. +Add a [`"builtin-baseline"`][builtin-baseline] field to the `vcpkg.json` if it does not already have one. Without this flag, it is an error to run this command on a manifest that does not have any [registries][] configured. [Manifest Mode]: ../users/manifests.md -[`"builtin-baseline"`]: ../users/manifests.md#builtin-baseline -[`vcpkg-configuration.json`]: ../users/registries.md#vcpkg-configurationjson +[builtin-baseline]: ../users/manifests.md#builtin-baseline +[vcj]: ../users/registries.md#vcpkg-configurationjson [registries]: ../users/registries.md diff --git a/docs/users/manifests.md b/docs/users/manifests.md index 1817a10072e547..fc4e7dac13b2a5 100644 --- a/docs/users/manifests.md +++ b/docs/users/manifests.md @@ -31,6 +31,7 @@ manifest mode. - [`"name"`](#dependencies-name) - [`"default-features"`](#dependencies-default-features) - [`"features"`](#dependencies-features) + - [`"host"`](#host) - [`"platform"`](#platform) - [`"version>="`](#version-gt) - [`"overrides"`](#overrides) @@ -38,8 +39,6 @@ manifest mode. - [`"features"`](#features) - [`"default-features"`](#default-features) -See also [the original specification](../specifications/manifests.md) for more low-level details. - ## Simple Example Manifest ```json @@ -69,8 +68,9 @@ Manifests follow strict JSON: they can't contain C++-style comments (`//`) nor t you can use field names that start with `$` to write your comments in any object that has a well-defined set of keys. These comment fields are not allowed in any objects which permit user-defined keys (such as `"features"`). -Each manifest contains a top level object with the fields documented below; the most important ones are -[`"name"`](#name), the [version fields](#version-fields), and [`"dependencies"`](#dependencies): +The latest JSON Schema is available at https://raw.githubusercontent.com/microsoft/vcpkg/master/scripts/vcpkg.schema.json. IDEs with JSON Schema support such as Visual Studio and Visual Studio Code can use this file to provide IntelliSense and syntax checking. For most IDEs, you should set `"$schema"` in your `vcpkg.json` to this URL (like the above example). + +Each manifest contains a top level object with the following fields: @@ -80,8 +80,6 @@ This is the name of your project! It must be formatted in a way that vcpkg under it must be lowercase alphabetic characters, digits, and hyphens, and it must not start nor end with a hyphen. For example, `Boost.Asio` might be given the name `boost-asio`. -This is a required field. - ### Version Fields There are four version field options, depending on how the port orders its @@ -190,6 +188,16 @@ Then, you might just ask for: } ``` + + +#### `"host"` Field + +A boolean indicating that the dependency must be built for the [host triplet](host-dependencies.md) instead of the current port's triplet. Defaults to `false`. + +Any dependency that provides tools or scripts which should be "executed" during a build (such as buildsystems, code generators, or helpers) should be marked as `"host": true`. This enables correct cross-compilation in cases that the target is not executable -- such as when compiling for `arm64-android`. + +See [Host Dependencies](host-dependencies.md) for more information. + #### `"platform"` Field