Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Doc]: Added links to the Target section of the glossary for occurences of target triple #11603

Merged
merged 6 commits into from
Jan 22, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/doc/man/cargo-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions src/doc/man/cargo-tree.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}}
Expand Down
5 changes: 3 additions & 2 deletions src/doc/man/generated_txt/cargo-metadata.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://doc.rust-lang.org/cargo/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
Expand Down
6 changes: 4 additions & 2 deletions src/doc/man/generated_txt/cargo-tree.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
<https://doc.rust-lang.org/cargo/appendix/glossary.html#target>. The
default is the host platform. Use the value all to include all
targets.

Tree Formatting Options
--charset charset
Expand Down
3 changes: 2 additions & 1 deletion src/doc/src/commands/cargo-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -311,7 +311,8 @@ possible value.</dd>

<dt class="option-term" id="option-cargo-metadata---filter-platform"><a class="option-anchor" href="#option-cargo-metadata---filter-platform"></a><code>--filter-platform</code> <em>triple</em></dt>
<dd class="option-desc">This filters the <code>resolve</code> output to only include dependencies for the
given target triple. Without this flag, the resolve includes all targets.</p>
given <a href="../appendix/glossary.html#target">target triple</a>.
Without this flag, the resolve includes all targets.</p>
<p>Note that the dependencies listed in the &quot;packages&quot; array still includes all
dependencies. Each package definition is intended to be an unaltered
reproduction of the information within <code>Cargo.toml</code>.</dd>
Expand Down
4 changes: 2 additions & 2 deletions src/doc/src/commands/cargo-tree.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,8 +137,8 @@ kind given, then it will automatically include the other dependency kinds.</li>


<dt class="option-term" id="option-cargo-tree---target"><a class="option-anchor" href="#option-cargo-tree---target"></a><code>--target</code> <em>triple</em></dt>
<dd class="option-desc">Filter dependencies matching the given target-triple. The default is the host
platform. Use the value <code>all</code> to include <em>all</em> targets.</dd>
<dd class="option-desc">Filter dependencies matching the given <a href="../appendix/glossary.html#target">target triple</a>.
The default is the host platform. Use the value <code>all</code> to include <em>all</em> targets.</dd>


</dl>
Expand Down
3 changes: 2 additions & 1 deletion src/doc/src/guide/build-cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------|--------
Expand Down Expand Up @@ -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
Expand Down
26 changes: 14 additions & 12 deletions src/doc/src/reference/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<triple>` where
the `<triple>` part can be any target triple like
the `<triple>` part can be any [target triple] like
`target.x86_64-pc-windows-msvc`.

#### `paths`
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1048,8 +1048,8 @@ 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
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 `<triple>` value or the `<cfg>` expression.

```toml
Expand All @@ -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 `<triple>` value is the filename stem.
If using a target spec JSON file, the [`<triple>`] value is the filename stem.
For example `--target foo/bar.json` would match `[target.bar]`.

##### `target.<triple>.ar`
Expand All @@ -1081,22 +1081,22 @@ This option is deprecated and unused.
* Environment: `CARGO_TARGET_<triple>_LINKER`

Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the
`<triple>` is being compiled for. By default, the linker is not overridden.
[`<triple>`] is being compiled for. By default, the linker is not overridden.

##### `target.<triple>.runner`
* Type: string or array of strings ([program path with args])
* Default: none
* Environment: `CARGO_TARGET_<triple>_RUNNER`

If a runner is provided, executables for the target `<triple>` will be
If a runner is provided, executables for the target [`<triple>`] 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.

##### `target.<cfg>.runner`

This is similar to the [target runner](#targettriplerunner), but using
a [`cfg()` expression]. If both a `<triple>` and `<cfg>` runner match,
a [`cfg()` expression]. If both a [`<triple>`] and `<cfg>` runner match,
the `<triple>` will take precedence. It is an error if more than one
`<cfg>` runner matches the current target.

Expand All @@ -1105,16 +1105,16 @@ the `<triple>` will take precedence. It is an error if more than one
* Default: none
* Environment: `CARGO_TARGET_<triple>_RUSTFLAGS`

Passes a set of custom flags to the compiler for this `<triple>`. The value
may be an array of strings or a space-separated string.
Passes a set of custom flags to the compiler for this [`<triple>`].
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.

##### `target.<cfg>.rustflags`

This is similar to the [target rustflags](#targettriplerustflags), but
using a [`cfg()` expression]. If several `<cfg>` and `<triple>` entries
using a [`cfg()` expression]. If several `<cfg>` and [`<triple>`] entries
match the current target, the flags are joined together.

##### `target.<triple>.<links>`
Expand Down Expand Up @@ -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)'
[`<triple>`]: ../appendix/glossary.md#target '"target" (glossary)'
22 changes: 13 additions & 9 deletions src/doc/src/reference/unstable.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.<host triple>]`, 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.<host triple>]`](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
Expand Down Expand Up @@ -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

Expand All @@ -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)'
3 changes: 2 additions & 1 deletion src/etc/man/cargo-metadata.1
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&.
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
Expand Down
4 changes: 2 additions & 2 deletions src/etc/man/cargo-tree.1
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&.
The default is the host platform. Use the value \fBall\fR to include \fIall\fR targets.
.RE
.SS "Tree Formatting Options"
.sp
Expand Down