Skip to content

Commit 741f0e5

Browse files
borsbors
committed
Auto merge of #7733 - ehuss:doc-updates, r=Eh2406
Various doc updates This is a collection of documentation updates that have been in my todo list for a while. Each change is in a separate commit. The "features" chapter will probably get significant changes in the future, as it is pretty bare right now. Similarly the "workspace" chapter could probably use more examples. Closes #3062 Closes #3817 Closes #3971 Closes #4212 Closes #4438 Closes #4756 Closes #5822 Closes #6913 Closes #7055
2 parents 7c2cadd + 493eb34 commit 741f0e5

56 files changed

Lines changed: 1813 additions & 1084 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/doc/man/cargo-fix.adoc‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,18 @@ executing:
2828

2929
cargo fix --edition
3030

31-
which behaves the same as `cargo check --all-targets`. Similarly if you'd like
32-
to fix code for different platforms you can do:
31+
which behaves the same as `cargo check --all-targets`.
3332

34-
cargo fix --edition --target x86_64-pc-windows-gnu
33+
`cargo fix` is only capable of fixing code that is normally compiled with
34+
`cargo check`. If code is conditionally enabled with optional features, you
35+
will need to enable those features for that code to be analyzed:
36+
37+
cargo fix --edition --features foo
3538

36-
or if your crate has optional features:
39+
Similarly, other `cfg` expressions like platform-specific code will need to
40+
pass `--target` to fix code for the given target.
3741

38-
cargo fix --edition --no-default-features --features foo
42+
cargo fix --edition --target x86_64-pc-windows-gnu
3943

4044
If you encounter any problems with `cargo fix` or otherwise have any questions
4145
or feature requests please don't hesitate to file an issue at

‎src/doc/man/cargo-package.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ steps:
3333
about the current VCS checkout hash if available (not included with
3434
`--allow-dirty`).
3535
. Extract the `.crate` file and build it to verify it can build.
36+
- This will rebuild your package from scratch to ensure that it can be
37+
built from a pristine state. The `--no-verify` flag can be used to skip
38+
this step.
3639
. Check that build scripts did not modify any source files.
3740

3841
The list of files included can be controlled with the `include` and `exclude`

‎src/doc/man/cargo-rustc.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ flags.
2525

2626
include::description-one-target.adoc[]
2727
To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS`
28-
environment variable or the `build.rustflags`
29-
linkcargo:reference/config.html[config value].
28+
linkcargo:reference/environment-variables.html[environment variable] or the
29+
`build.rustflags` linkcargo:reference/config.html[config value].
3030

3131
== OPTIONS
3232

‎src/doc/man/cargo-rustdoc.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ flags.
2525

2626
include::description-one-target.adoc[]
2727
To pass flags to all rustdoc processes spawned by Cargo, use the
28-
`RUSTDOCFLAGS` environment variable or the `build.rustdocflags` configuration
29-
option.
28+
`RUSTDOCFLAGS` linkcargo:reference/environment-variables.html[environment variable]
29+
or the `build.rustdocflags` linkcargo:reference/config.html[config value].
3030

3131
== OPTIONS
3232

‎src/doc/man/generated/cargo-bench.html‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,8 @@ <h3 id="cargo_bench_feature_selection">Feature Selection</h3>
213213
<dd>
214214
<p>Space or comma separated list of features to activate. These features only
215215
apply to the current directory&#8217;s package. Features of direct dependencies
216-
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
216+
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
217+
specified multiple times, which enables all specified features.</p>
217218
</dd>
218219
<dt class="hdlist1"><strong>--all-features</strong></dt>
219220
<dd>
@@ -241,6 +242,11 @@ <h3 id="cargo_bench_compilation_options">Compilation Options</h3>
241242
<p>This may also be specified with the <code>build.target</code>
242243
<a href="../reference/config.html">config value</a>.</p>
243244
</div>
245+
<div class="paragraph">
246+
<p>Note that specifying this flag makes Cargo run in a different mode where the
247+
target artifacts are placed in a separate directory. See the
248+
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
249+
</div>
244250
</dd>
245251
</dl>
246252
</div>

‎src/doc/man/generated/cargo-build.html‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,8 @@ <h3 id="cargo_build_feature_selection">Feature Selection</h3>
142142
<dd>
143143
<p>Space or comma separated list of features to activate. These features only
144144
apply to the current directory&#8217;s package. Features of direct dependencies
145-
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
145+
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
146+
specified multiple times, which enables all specified features.</p>
146147
</dd>
147148
<dt class="hdlist1"><strong>--all-features</strong></dt>
148149
<dd>
@@ -170,6 +171,11 @@ <h3 id="cargo_build_compilation_options">Compilation Options</h3>
170171
<p>This may also be specified with the <code>build.target</code>
171172
<a href="../reference/config.html">config value</a>.</p>
172173
</div>
174+
<div class="paragraph">
175+
<p>Note that specifying this flag makes Cargo run in a different mode where the
176+
target artifacts are placed in a separate directory. See the
177+
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
178+
</div>
173179
</dd>
174180
<dt class="hdlist1"><strong>--release</strong></dt>
175181
<dd>

‎src/doc/man/generated/cargo-check.html‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,8 @@ <h3 id="cargo_check_feature_selection">Feature Selection</h3>
146146
<dd>
147147
<p>Space or comma separated list of features to activate. These features only
148148
apply to the current directory&#8217;s package. Features of direct dependencies
149-
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
149+
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
150+
specified multiple times, which enables all specified features.</p>
150151
</dd>
151152
<dt class="hdlist1"><strong>--all-features</strong></dt>
152153
<dd>
@@ -174,6 +175,11 @@ <h3 id="cargo_check_compilation_options">Compilation Options</h3>
174175
<p>This may also be specified with the <code>build.target</code>
175176
<a href="../reference/config.html">config value</a>.</p>
176177
</div>
178+
<div class="paragraph">
179+
<p>Note that specifying this flag makes Cargo run in a different mode where the
180+
target artifacts are placed in a separate directory. See the
181+
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
182+
</div>
177183
</dd>
178184
<dt class="hdlist1"><strong>--release</strong></dt>
179185
<dd>

‎src/doc/man/generated/cargo-clean.html‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,11 @@ <h3 id="cargo_clean_clean_options">Clean Options</h3>
7373
<p>This may also be specified with the <code>build.target</code>
7474
<a href="../reference/config.html">config value</a>.</p>
7575
</div>
76+
<div class="paragraph">
77+
<p>Note that specifying this flag makes Cargo run in a different mode where the
78+
target artifacts are placed in a separate directory. See the
79+
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
80+
</div>
7681
</dd>
7782
</dl>
7883
</div>

‎src/doc/man/generated/cargo-doc.html‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,8 @@ <h3 id="cargo_doc_feature_selection">Feature Selection</h3>
124124
<dd>
125125
<p>Space or comma separated list of features to activate. These features only
126126
apply to the current directory&#8217;s package. Features of direct dependencies
127-
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
127+
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax. This flag may be
128+
specified multiple times, which enables all specified features.</p>
128129
</dd>
129130
<dt class="hdlist1"><strong>--all-features</strong></dt>
130131
<dd>
@@ -152,6 +153,11 @@ <h3 id="cargo_doc_compilation_options">Compilation Options</h3>
152153
<p>This may also be specified with the <code>build.target</code>
153154
<a href="../reference/config.html">config value</a>.</p>
154155
</div>
156+
<div class="paragraph">
157+
<p>Note that specifying this flag makes Cargo run in a different mode where the
158+
target artifacts are placed in a separate directory. See the
159+
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
160+
</div>
155161
</dd>
156162
<dt class="hdlist1"><strong>--release</strong></dt>
157163
<dd>

‎src/doc/man/generated/cargo-fetch.html‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,11 @@ <h3 id="cargo_fetch_fetch_options">Fetch options</h3>
5050
<p>This may also be specified with the <code>build.target</code>
5151
<a href="../reference/config.html">config value</a>.</p>
5252
</div>
53+
<div class="paragraph">
54+
<p>Note that specifying this flag makes Cargo run in a different mode where the
55+
target artifacts are placed in a separate directory. See the
56+
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
57+
</div>
5358
</dd>
5459
</dl>
5560
</div>

0 commit comments

Comments
 (0)