From eaaa48fbaa04e985e84ee6195fda3083e4a016d6 Mon Sep 17 00:00:00 2001 From: jofas Date: Fri, 20 Jan 2023 15:00:46 +0100 Subject: [PATCH 1/6] added link to 'target triple' in documentation for cargo-metadata and cargo-tree commands --- src/doc/src/commands/cargo-metadata.md | 3 ++- src/doc/src/commands/cargo-tree.md | 5 ++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md index feb56f87af3..0f6b42b4ad6 100644 --- a/src/doc/src/commands/cargo-metadata.md +++ b/src/doc/src/commands/cargo-metadata.md @@ -311,7 +311,8 @@ possible value.
--filter-platform triple
This filters the resolve output to only include dependencies for the -given target triple. Without this flag, the resolve includes all targets.

+given target triple. Without this flag, the resolve includes +all targets.

Note that the dependencies listed in the "packages" array still includes all dependencies. Each package definition is intended to be an unaltered reproduction of the information within Cargo.toml.

diff --git a/src/doc/src/commands/cargo-tree.md b/src/doc/src/commands/cargo-tree.md index e7cf3f26294..ad431004569 100644 --- a/src/doc/src/commands/cargo-tree.md +++ b/src/doc/src/commands/cargo-tree.md @@ -137,9 +137,8 @@ kind given, then it will automatically include the other dependency kinds.
--target triple
-
Filter dependencies matching the given target-triple. The default is the host -platform. Use the value all to include all targets.
- +
Filter dependencies matching the given target triple. +The default is the host platform. Use the value all to include all targets.
From 30a0daf9e369c35bbf30b0f973cec387bb7d54e4 Mon Sep 17 00:00:00 2001 From: jofas Date: Fri, 20 Jan 2023 15:07:42 +0100 Subject: [PATCH 2/6] added link to 'target' in documentation for build cache section of the guide --- src/doc/src/guide/build-cache.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md index a8453f615fb..a79b41dbaa1 100644 --- a/src/doc/src/guide/build-cache.md +++ b/src/doc/src/guide/build-cache.md @@ -24,7 +24,7 @@ For historical reasons, the `dev` and `test` profiles are stored in the same name as the profile. When building for another target with `--target`, the output is placed in a -directory with the name of the target: +directory with the name of the [target]: Directory | Example ----------|-------- @@ -98,6 +98,7 @@ configuration][config]. Refer to sccache documentation for more details. [build scripts]: ../reference/build-scripts.md [config]: ../reference/config.md [def-workspace]: ../appendix/glossary.md#workspace '"workspace" (glossary entry)' +[target]: ../appendix/glossary.md#target '"target" (glossary entry)' [environment variable]: ../reference/environment-variables.md [incremental output]: ../reference/profiles.md#incremental [sccache]: https://github.com/mozilla/sccache From 40a615ef00b309e42419b71e9f9e5ca8b3e3c164 Mon Sep 17 00:00:00 2001 From: jofas Date: Fri, 20 Jan 2023 15:58:10 +0100 Subject: [PATCH 3/6] added links to 'target' in documentation for unstable section of the reference --- src/doc/src/reference/unstable.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 14c4ed0d16e..75d828cf25e 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -459,17 +459,19 @@ CLI paths are relative to the current working directory. * Tracking Issue: [#9453](https://github.com/rust-lang/cargo/issues/9453) Historically, Cargo's behavior for whether the `linker` and `rustflags` -configuration options from environment variables and `[target]` are -respected for build scripts, plugins, and other artifacts that are -_always_ built for the host platform has been somewhat inconsistent. +configuration options from environment variables and +[`[target]`](config.md#target) are respected for build scripts, plugins, +and other artifacts that are _always_ built for the host platform has +been somewhat inconsistent. When `--target` is _not_ passed, Cargo respects the same `linker` and `rustflags` for build scripts as for all other compile artifacts. When `--target` _is_ passed, however, Cargo respects `linker` from -`[target.]`, and does not pick up any `rustflags` -configuration. This dual behavior is confusing, but also makes it -difficult to correctly configure builds where the host triple and the -target triple happen to be the same, but artifacts intended to run on -the build host should still be configured differently. +[`[target.]`](config.md#targettriplelinker), and does not +pick up any `rustflags` configuration. +This dual behavior is confusing, but also makes it difficult to correctly +configure builds where the host triple and the [target triple] happen to +be the same, but artifacts intended to run on the build host should still +be configured differently. `-Ztarget-applies-to-host` enables the top-level `target-applies-to-host` setting in Cargo configuration files which @@ -1432,7 +1434,7 @@ information. The `-Z multitarget` option has been stabilized in the 1.64 release. See [`build.target`](config.md#buildtarget) for more information about -setting the default target platform triples. +setting the default [target platform triples][target triple]. ### crate-type @@ -1459,3 +1461,5 @@ terminal where Cargo can automatically detect the width. Sparse registry support has been stabilized in the 1.68 release. See [Registry Protocols](registries.md#registry-protocols) for more information. + +[target triple]: ../appendix/glossary.md#target '"target" (glossary)' From 7f0ee923300dd3383ce12036d8c04665b431dcf2 Mon Sep 17 00:00:00 2001 From: jofas Date: Fri, 20 Jan 2023 16:13:26 +0100 Subject: [PATCH 4/6] properly added links to the 'target' glossary entry of the 'cargo tree' and 'cargo metadata' command man pages --- src/doc/man/cargo-metadata.md | 3 ++- src/doc/man/cargo-tree.md | 4 ++-- src/doc/man/generated_txt/cargo-metadata.txt | 5 +++-- src/doc/man/generated_txt/cargo-tree.txt | 6 ++++-- src/doc/src/commands/cargo-metadata.md | 4 ++-- src/doc/src/commands/cargo-tree.md | 3 ++- src/etc/man/cargo-metadata.1 | 3 ++- src/etc/man/cargo-tree.1 | 4 ++-- 8 files changed, 19 insertions(+), 13 deletions(-) diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md index c1a8920bc2b..5197f03c200 100644 --- a/src/doc/man/cargo-metadata.md +++ b/src/doc/man/cargo-metadata.md @@ -311,7 +311,8 @@ possible value. {{#option "`--filter-platform` _triple_" }} This filters the `resolve` output to only include dependencies for the -given target triple. Without this flag, the resolve includes all targets. +given [target triple](../appendix/glossary.html#target). +Without this flag, the resolve includes all targets. Note that the dependencies listed in the "packages" array still includes all dependencies. Each package definition is intended to be an unaltered diff --git a/src/doc/man/cargo-tree.md b/src/doc/man/cargo-tree.md index f0aaffc1d7b..51b1d9e0e14 100644 --- a/src/doc/man/cargo-tree.md +++ b/src/doc/man/cargo-tree.md @@ -137,8 +137,8 @@ The default is `normal,build,dev`. {{/option}} {{#option "`--target` _triple_" }} -Filter dependencies matching the given target-triple. The default is the host -platform. Use the value `all` to include *all* targets. +Filter dependencies matching the given [target triple](../appendix/glossary.html#target). +The default is the host platform. Use the value `all` to include *all* targets. {{/option}} {{/options}} diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt index efee01a9f9f..1bb33b4f2c0 100644 --- a/src/doc/man/generated_txt/cargo-metadata.txt +++ b/src/doc/man/generated_txt/cargo-metadata.txt @@ -299,8 +299,9 @@ OPTIONS --filter-platform triple This filters the resolve output to only include dependencies for the - given target triple. Without this flag, the resolve includes all - targets. + given target triple + . + Without this flag, the resolve includes all targets. Note that the dependencies listed in the "packages" array still includes all dependencies. Each package definition is intended to be diff --git a/src/doc/man/generated_txt/cargo-tree.txt b/src/doc/man/generated_txt/cargo-tree.txt index a661f9cf916..ee85eaf261d 100644 --- a/src/doc/man/generated_txt/cargo-tree.txt +++ b/src/doc/man/generated_txt/cargo-tree.txt @@ -133,8 +133,10 @@ OPTIONS The default is normal,build,dev. --target triple - Filter dependencies matching the given target-triple. The default is - the host platform. Use the value all to include all targets. + Filter dependencies matching the given target triple + . The + default is the host platform. Use the value all to include all + targets. Tree Formatting Options --charset charset diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md index 0f6b42b4ad6..4bac638fdaa 100644 --- a/src/doc/src/commands/cargo-metadata.md +++ b/src/doc/src/commands/cargo-metadata.md @@ -311,8 +311,8 @@ possible value.
--filter-platform triple
This filters the resolve output to only include dependencies for the -given target triple. Without this flag, the resolve includes -all targets.

+given target triple. +Without this flag, the resolve includes all targets.

Note that the dependencies listed in the "packages" array still includes all dependencies. Each package definition is intended to be an unaltered reproduction of the information within Cargo.toml.

diff --git a/src/doc/src/commands/cargo-tree.md b/src/doc/src/commands/cargo-tree.md index ad431004569..9b1fde0eb11 100644 --- a/src/doc/src/commands/cargo-tree.md +++ b/src/doc/src/commands/cargo-tree.md @@ -137,9 +137,10 @@ kind given, then it will automatically include the other dependency kinds.
--target triple
-
Filter dependencies matching the given target triple. +
Filter dependencies matching the given target triple. The default is the host platform. Use the value all to include all targets.
+ ### Tree Formatting Options diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1 index 95c386eec7f..e9b90105546 100644 --- a/src/etc/man/cargo-metadata.1 +++ b/src/etc/man/cargo-metadata.1 @@ -308,7 +308,8 @@ possible value. \fB\-\-filter\-platform\fR \fItriple\fR .RS 4 This filters the \fBresolve\fR output to only include dependencies for the -given target triple. Without this flag, the resolve includes all targets. +given \fItarget triple\fR \&. +Without this flag, the resolve includes all targets. .sp Note that the dependencies listed in the "packages" array still includes all dependencies. Each package definition is intended to be an unaltered diff --git a/src/etc/man/cargo-tree.1 b/src/etc/man/cargo-tree.1 index 8c7e7815f4c..f99484b7580 100644 --- a/src/etc/man/cargo-tree.1 +++ b/src/etc/man/cargo-tree.1 @@ -167,8 +167,8 @@ The default is \fBnormal,build,dev\fR\&. .sp \fB\-\-target\fR \fItriple\fR .RS 4 -Filter dependencies matching the given target\-triple. The default is the host -platform. Use the value \fBall\fR to include \fIall\fR targets. +Filter dependencies matching the given \fItarget triple\fR \&. +The default is the host platform. Use the value \fBall\fR to include \fIall\fR targets. .RE .SS "Tree Formatting Options" .sp From 05e6d6febd590a4d429fb1c0be041f94ef965102 Mon Sep 17 00:00:00 2001 From: jofas Date: Fri, 20 Jan 2023 16:33:59 +0100 Subject: [PATCH 5/6] added links to 'target' glossary entry in documentation for configuration section of the reference --- src/doc/src/reference/config.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index 9a6dceade1d..596a0e568fb 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -321,7 +321,7 @@ all capital letters. This section documents all configuration keys. The description for keys with variable parts are annotated with angled brackets like `target.` where -the `` part can be any target triple like +the [``] part can be any [target triple] like `target.x86_64-pc-windows-msvc`. #### `paths` @@ -418,7 +418,7 @@ Sets the executable to use for `rustdoc`. * Default: host platform * Environment: `CARGO_BUILD_TARGET` -The default target platform triples to compile to. +The default [target platform triples][target triple] to compile to. This allows passing either a string or an array of strings. Each string value is a target platform triple. The selected build targets will be built for each @@ -468,7 +468,7 @@ for the host, such as build scripts or proc macros, will not receive the args. Without `--target`, the flags will be passed to all compiler invocations (including build scripts and proc macros) because dependencies are shared. If you have args that you do not want to pass to build scripts or proc macros and -are building for the host, pass `--target` with the host triple. +are building for the host, pass `--target` with the [host triple][target triple]. It is not recommended to pass in flags that Cargo itself usually manages. For example, the flags driven by [profiles](profiles.md) are best handled by setting the @@ -1048,9 +1048,9 @@ If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. #### `[target]` The `[target]` table is used for specifying settings for specific platform -targets. It consists of a sub-table which is either a platform triple or a -[`cfg()` expression]. The given values will be used if the target platform -matches either the `` value or the `` expression. +targets. It consists of a sub-table which is either a [platform triple][target triple] +or a [`cfg()` expression]. The given values will be used if the target platform +matches either the [``] value or the `` expression. ```toml [target.thumbv7m-none-eabi] @@ -1068,7 +1068,7 @@ to view), values set by [build scripts], and extra `--cfg` flags passed to `rustc` (such as those defined in `RUSTFLAGS`). Do not try to match on `debug_assertions` or Cargo features like `feature="foo"`. -If using a target spec JSON file, the `` value is the filename stem. +If using a target spec JSON file, the [``] value is the filename stem. For example `--target foo/bar.json` would match `[target.bar]`. ##### `target..ar` @@ -1081,14 +1081,14 @@ This option is deprecated and unused. * Environment: `CARGO_TARGET__LINKER` Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the -`` is being compiled for. By default, the linker is not overridden. +[``] is being compiled for. By default, the linker is not overridden. ##### `target..runner` * Type: string or array of strings ([program path with args]) * Default: none * Environment: `CARGO_TARGET__RUNNER` -If a runner is provided, executables for the target `` will be +If a runner is provided, executables for the target [``] will be executed by invoking the specified runner with the actual executable passed as an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`] commands. By default, compiled executables are executed directly. @@ -1096,7 +1096,7 @@ commands. By default, compiled executables are executed directly. ##### `target..runner` This is similar to the [target runner](#targettriplerunner), but using -a [`cfg()` expression]. If both a `` and `` runner match, +a [`cfg()` expression]. If both a [``] and `` runner match, the `` will take precedence. It is an error if more than one `` runner matches the current target. @@ -1105,8 +1105,8 @@ the `` will take precedence. It is an error if more than one * Default: none * Environment: `CARGO_TARGET__RUSTFLAGS` -Passes a set of custom flags to the compiler for this ``. The value -may be an array of strings or a space-separated string. +Passes a set of custom flags to the compiler for this [``]. +The value may be an array of strings or a space-separated string. See [`build.rustflags`](#buildrustflags) for more details on the different ways to specific extra flags. @@ -1114,7 +1114,7 @@ ways to specific extra flags. ##### `target..rustflags` This is similar to the [target rustflags](#targettriplerustflags), but -using a [`cfg()` expression]. If several `` and `` entries +using a [`cfg()` expression]. If several `` and [``] entries match the current target, the flags are joined together. ##### `target..` @@ -1214,3 +1214,5 @@ Sets the width for progress bar. [revision]: https://git-scm.com/docs/gitrevisions [registries]: registries.md [crates.io]: https://crates.io/ +[target triple]: ../appendix/glossary.md#target '"target" (glossary)' +[``]: ../appendix/glossary.md#target '"target" (glossary)' From 63e9b77d8ad9b6d4cfacde04f8eaf5a644dddf08 Mon Sep 17 00:00:00 2001 From: jofas Date: Sat, 21 Jan 2023 11:24:54 +0100 Subject: [PATCH 6/6] removed noisy links --- src/doc/src/reference/config.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index 596a0e568fb..b826beb75cc 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -321,7 +321,7 @@ all capital letters. This section documents all configuration keys. The description for keys with variable parts are annotated with angled brackets like `target.` where -the [``] part can be any [target triple] like +the `` part can be any [target triple] like `target.x86_64-pc-windows-msvc`. #### `paths` @@ -1050,7 +1050,7 @@ If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. The `[target]` table is used for specifying settings for specific platform targets. It consists of a sub-table which is either a [platform triple][target triple] or a [`cfg()` expression]. The given values will be used if the target platform -matches either the [``] value or the `` expression. +matches either the `` value or the `` expression. ```toml [target.thumbv7m-none-eabi]