mirror of https://github.com/rust-lang/cargo
Auto merge of #11603 - jofas:11398-fix, r=weihanglo
[Doc]: Added links to the `Target` section of the glossary for occurences of `target triple` Fix for #11398. #11398 raises the concern that it isn't always abundantly clear in the cargo book, what a `target triple` (i.e. `x86_64-unknown-linux-gnu`) is. This is unfortunate, as it is well described in the [glossary](https://doc.rust-lang.org/cargo/appendix/glossary.html#target) of the cargo book (including the command on how to get all targets supported by `rustc`). To mitigate this problem I added links to the glossary entry for target triples to the sections where triples are referenced, but not enough information is given on what they are and how they look like.
This commit is contained in:
commit
af8ec1407b
|
@ -311,7 +311,8 @@ possible value.
|
||||||
|
|
||||||
{{#option "`--filter-platform` _triple_" }}
|
{{#option "`--filter-platform` _triple_" }}
|
||||||
This filters the `resolve` output to only include dependencies for the
|
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
|
Note that the dependencies listed in the "packages" array still includes all
|
||||||
dependencies. Each package definition is intended to be an unaltered
|
dependencies. Each package definition is intended to be an unaltered
|
||||||
|
|
|
@ -137,8 +137,8 @@ The default is `normal,build,dev`.
|
||||||
{{/option}}
|
{{/option}}
|
||||||
|
|
||||||
{{#option "`--target` _triple_" }}
|
{{#option "`--target` _triple_" }}
|
||||||
Filter dependencies matching the given target-triple. The default is the host
|
Filter dependencies matching the given [target triple](../appendix/glossary.html#target).
|
||||||
platform. Use the value `all` to include *all* targets.
|
The default is the host platform. Use the value `all` to include *all* targets.
|
||||||
{{/option}}
|
{{/option}}
|
||||||
|
|
||||||
{{/options}}
|
{{/options}}
|
||||||
|
|
|
@ -299,8 +299,9 @@ OPTIONS
|
||||||
|
|
||||||
--filter-platform triple
|
--filter-platform triple
|
||||||
This filters the resolve output to only include dependencies for the
|
This filters the resolve output to only include dependencies for the
|
||||||
given target triple. Without this flag, the resolve includes all
|
given target triple
|
||||||
targets.
|
<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
|
Note that the dependencies listed in the "packages" array still
|
||||||
includes all dependencies. Each package definition is intended to be
|
includes all dependencies. Each package definition is intended to be
|
||||||
|
|
|
@ -133,8 +133,10 @@ OPTIONS
|
||||||
The default is normal,build,dev.
|
The default is normal,build,dev.
|
||||||
|
|
||||||
--target triple
|
--target triple
|
||||||
Filter dependencies matching the given target-triple. The default is
|
Filter dependencies matching the given target triple
|
||||||
the host platform. Use the value all to include all targets.
|
<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
|
Tree Formatting Options
|
||||||
--charset charset
|
--charset charset
|
||||||
|
|
|
@ -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>
|
<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
|
<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 "packages" array still includes all
|
<p>Note that the dependencies listed in the "packages" array still includes all
|
||||||
dependencies. Each package definition is intended to be an unaltered
|
dependencies. Each package definition is intended to be an unaltered
|
||||||
reproduction of the information within <code>Cargo.toml</code>.</dd>
|
reproduction of the information within <code>Cargo.toml</code>.</dd>
|
||||||
|
|
|
@ -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>
|
<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
|
<dd class="option-desc">Filter dependencies matching the given <a href="../appendix/glossary.html#target">target triple</a>.
|
||||||
platform. Use the value <code>all</code> to include <em>all</em> targets.</dd>
|
The default is the host platform. Use the value <code>all</code> to include <em>all</em> targets.</dd>
|
||||||
|
|
||||||
|
|
||||||
</dl>
|
</dl>
|
||||||
|
|
|
@ -24,7 +24,7 @@ For historical reasons, the `dev` and `test` profiles are stored in the
|
||||||
same name as the profile.
|
same name as the profile.
|
||||||
|
|
||||||
When building for another target with `--target`, the output is placed in a
|
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
|
Directory | Example
|
||||||
----------|--------
|
----------|--------
|
||||||
|
@ -98,6 +98,7 @@ configuration][config]. Refer to sccache documentation for more details.
|
||||||
[build scripts]: ../reference/build-scripts.md
|
[build scripts]: ../reference/build-scripts.md
|
||||||
[config]: ../reference/config.md
|
[config]: ../reference/config.md
|
||||||
[def-workspace]: ../appendix/glossary.md#workspace '"workspace" (glossary entry)'
|
[def-workspace]: ../appendix/glossary.md#workspace '"workspace" (glossary entry)'
|
||||||
|
[target]: ../appendix/glossary.md#target '"target" (glossary entry)'
|
||||||
[environment variable]: ../reference/environment-variables.md
|
[environment variable]: ../reference/environment-variables.md
|
||||||
[incremental output]: ../reference/profiles.md#incremental
|
[incremental output]: ../reference/profiles.md#incremental
|
||||||
[sccache]: https://github.com/mozilla/sccache
|
[sccache]: https://github.com/mozilla/sccache
|
||||||
|
|
|
@ -321,7 +321,7 @@ all capital letters.
|
||||||
|
|
||||||
This section documents all configuration keys. The description for keys with
|
This section documents all configuration keys. The description for keys with
|
||||||
variable parts are annotated with angled brackets like `target.<triple>` where
|
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`.
|
`target.x86_64-pc-windows-msvc`.
|
||||||
|
|
||||||
#### `paths`
|
#### `paths`
|
||||||
|
@ -418,7 +418,7 @@ Sets the executable to use for `rustdoc`.
|
||||||
* Default: host platform
|
* Default: host platform
|
||||||
* Environment: `CARGO_BUILD_TARGET`
|
* 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
|
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
|
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
|
Without `--target`, the flags will be passed to all compiler invocations
|
||||||
(including build scripts and proc macros) because dependencies are shared. If
|
(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
|
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
|
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
|
example, the flags driven by [profiles](profiles.md) are best handled by setting the
|
||||||
|
@ -1048,8 +1048,8 @@ If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch.
|
||||||
#### `[target]`
|
#### `[target]`
|
||||||
|
|
||||||
The `[target]` table is used for specifying settings for specific platform
|
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
|
targets. It consists of a sub-table which is either a [platform triple][target triple]
|
||||||
[`cfg()` expression]. The given values will be used if the target platform
|
or a [`cfg()` expression]. The given values will be used if the target platform
|
||||||
matches either the `<triple>` value or the `<cfg>` expression.
|
matches either the `<triple>` value or the `<cfg>` expression.
|
||||||
|
|
||||||
```toml
|
```toml
|
||||||
|
@ -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
|
`rustc` (such as those defined in `RUSTFLAGS`). Do not try to match on
|
||||||
`debug_assertions` or Cargo features like `feature="foo"`.
|
`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]`.
|
For example `--target foo/bar.json` would match `[target.bar]`.
|
||||||
|
|
||||||
##### `target.<triple>.ar`
|
##### `target.<triple>.ar`
|
||||||
|
@ -1081,14 +1081,14 @@ This option is deprecated and unused.
|
||||||
* Environment: `CARGO_TARGET_<triple>_LINKER`
|
* Environment: `CARGO_TARGET_<triple>_LINKER`
|
||||||
|
|
||||||
Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the
|
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`
|
##### `target.<triple>.runner`
|
||||||
* Type: string or array of strings ([program path with args])
|
* Type: string or array of strings ([program path with args])
|
||||||
* Default: none
|
* Default: none
|
||||||
* Environment: `CARGO_TARGET_<triple>_RUNNER`
|
* 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
|
executed by invoking the specified runner with the actual executable passed as
|
||||||
an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`]
|
an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`]
|
||||||
commands. By default, compiled executables are executed directly.
|
commands. By default, compiled executables are executed directly.
|
||||||
|
@ -1096,7 +1096,7 @@ commands. By default, compiled executables are executed directly.
|
||||||
##### `target.<cfg>.runner`
|
##### `target.<cfg>.runner`
|
||||||
|
|
||||||
This is similar to the [target runner](#targettriplerunner), but using
|
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
|
the `<triple>` will take precedence. It is an error if more than one
|
||||||
`<cfg>` runner matches the current target.
|
`<cfg>` runner matches the current target.
|
||||||
|
|
||||||
|
@ -1105,8 +1105,8 @@ the `<triple>` will take precedence. It is an error if more than one
|
||||||
* Default: none
|
* Default: none
|
||||||
* Environment: `CARGO_TARGET_<triple>_RUSTFLAGS`
|
* Environment: `CARGO_TARGET_<triple>_RUSTFLAGS`
|
||||||
|
|
||||||
Passes a set of custom flags to the compiler for this `<triple>`. The value
|
Passes a set of custom flags to the compiler for this [`<triple>`].
|
||||||
may be an array of strings or a space-separated string.
|
The value may be an array of strings or a space-separated string.
|
||||||
|
|
||||||
See [`build.rustflags`](#buildrustflags) for more details on the different
|
See [`build.rustflags`](#buildrustflags) for more details on the different
|
||||||
ways to specific extra flags.
|
ways to specific extra flags.
|
||||||
|
@ -1114,7 +1114,7 @@ ways to specific extra flags.
|
||||||
##### `target.<cfg>.rustflags`
|
##### `target.<cfg>.rustflags`
|
||||||
|
|
||||||
This is similar to the [target rustflags](#targettriplerustflags), but
|
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.
|
match the current target, the flags are joined together.
|
||||||
|
|
||||||
##### `target.<triple>.<links>`
|
##### `target.<triple>.<links>`
|
||||||
|
@ -1214,3 +1214,5 @@ Sets the width for progress bar.
|
||||||
[revision]: https://git-scm.com/docs/gitrevisions
|
[revision]: https://git-scm.com/docs/gitrevisions
|
||||||
[registries]: registries.md
|
[registries]: registries.md
|
||||||
[crates.io]: https://crates.io/
|
[crates.io]: https://crates.io/
|
||||||
|
[target triple]: ../appendix/glossary.md#target '"target" (glossary)'
|
||||||
|
[`<triple>`]: ../appendix/glossary.md#target '"target" (glossary)'
|
||||||
|
|
|
@ -459,17 +459,19 @@ CLI paths are relative to the current working directory.
|
||||||
* Tracking Issue: [#9453](https://github.com/rust-lang/cargo/issues/9453)
|
* Tracking Issue: [#9453](https://github.com/rust-lang/cargo/issues/9453)
|
||||||
|
|
||||||
Historically, Cargo's behavior for whether the `linker` and `rustflags`
|
Historically, Cargo's behavior for whether the `linker` and `rustflags`
|
||||||
configuration options from environment variables and `[target]` are
|
configuration options from environment variables and
|
||||||
respected for build scripts, plugins, and other artifacts that are
|
[`[target]`](config.md#target) are respected for build scripts, plugins,
|
||||||
_always_ built for the host platform has been somewhat inconsistent.
|
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
|
When `--target` is _not_ passed, Cargo respects the same `linker` and
|
||||||
`rustflags` for build scripts as for all other compile artifacts. When
|
`rustflags` for build scripts as for all other compile artifacts. When
|
||||||
`--target` _is_ passed, however, Cargo respects `linker` from
|
`--target` _is_ passed, however, Cargo respects `linker` from
|
||||||
`[target.<host triple>]`, and does not pick up any `rustflags`
|
[`[target.<host triple>]`](config.md#targettriplelinker), and does not
|
||||||
configuration. This dual behavior is confusing, but also makes it
|
pick up any `rustflags` configuration.
|
||||||
difficult to correctly configure builds where the host triple and the
|
This dual behavior is confusing, but also makes it difficult to correctly
|
||||||
target triple happen to be the same, but artifacts intended to run on
|
configure builds where the host triple and the [target triple] happen to
|
||||||
the build host should still be configured differently.
|
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
|
`-Ztarget-applies-to-host` enables the top-level
|
||||||
`target-applies-to-host` setting in Cargo configuration files which
|
`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.
|
The `-Z multitarget` option has been stabilized in the 1.64 release.
|
||||||
See [`build.target`](config.md#buildtarget) for more information about
|
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
|
### 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.
|
Sparse registry support has been stabilized in the 1.68 release.
|
||||||
See [Registry Protocols](registries.md#registry-protocols) for more information.
|
See [Registry Protocols](registries.md#registry-protocols) for more information.
|
||||||
|
|
||||||
|
[target triple]: ../appendix/glossary.md#target '"target" (glossary)'
|
||||||
|
|
|
@ -308,7 +308,8 @@ possible value.
|
||||||
\fB\-\-filter\-platform\fR \fItriple\fR
|
\fB\-\-filter\-platform\fR \fItriple\fR
|
||||||
.RS 4
|
.RS 4
|
||||||
This filters the \fBresolve\fR output to only include dependencies for the
|
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
|
.sp
|
||||||
Note that the dependencies listed in the "packages" array still includes all
|
Note that the dependencies listed in the "packages" array still includes all
|
||||||
dependencies. Each package definition is intended to be an unaltered
|
dependencies. Each package definition is intended to be an unaltered
|
||||||
|
|
|
@ -167,8 +167,8 @@ The default is \fBnormal,build,dev\fR\&.
|
||||||
.sp
|
.sp
|
||||||
\fB\-\-target\fR \fItriple\fR
|
\fB\-\-target\fR \fItriple\fR
|
||||||
.RS 4
|
.RS 4
|
||||||
Filter dependencies matching the given target\-triple. The default is the host
|
Filter dependencies matching the given \fItarget triple\fR <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&.
|
||||||
platform. Use the value \fBall\fR to include \fIall\fR targets.
|
The default is the host platform. Use the value \fBall\fR to include \fIall\fR targets.
|
||||||
.RE
|
.RE
|
||||||
.SS "Tree Formatting Options"
|
.SS "Tree Formatting Options"
|
||||||
.sp
|
.sp
|
||||||
|
|
Loading…
Reference in New Issue