Skip to content

Commit 8c7c35e

Browse files
Aaron1011Aaron1011
committed
Update docs
1 parent c2332dc commit 8c7c35e

26 files changed

+281
-30
lines changed

‎src/doc/man/cargo-build.md

+1
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ See <https://github.com/rust-lang/cargo/issues/5579> for more information.
8989

9090
{{#options}}
9191
{{> options-jobs }}
92+
{{> options-future-incompat }}
9293
{{/options}}
9394

9495
{{> section-environment }}

‎src/doc/man/cargo-check.md

+1
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ they have `required-features` that are missing.
7474

7575
{{#options}}
7676
{{> options-jobs }}
77+
{{> options-future-incompat }}
7778
{{/options}}
7879

7980
{{> section-environment }}

‎src/doc/man/cargo-report.md

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# cargo-report(1)
2+
3+
## NAME
4+
5+
cargo-report - Generate and display various kinds of reports
6+
7+
## SYNOPSIS
8+
9+
`cargo report` _type_ [_options_]
10+
11+
### DESCRIPTION
12+
13+
Displays a report of the given _type_ - currently, only `future-incompat` is supported
14+
15+
## OPTIONS
16+
17+
{{#options}}
18+
19+
{{#option "`--id` _id_" }}
20+
Show the report with the specified Cargo-generated id
21+
{{/option}}
22+
23+
{{#option "`-p` _spec_..." "`--package` _spec_..." }}
24+
Only display a report for the specified package
25+
{{/option}}
26+
27+
{{/options}}
28+
29+
## EXAMPLES
30+
31+
1. Display the latest future-incompat report:
32+
33+
cargo report future-incompat
34+
35+
2. Display the latest future-incompat report for a specific package:
36+
37+
cargo report future-incompat --package my-dep:0.0.1
38+
39+
## SEE ALSO
40+
{{man "cargo" 1}}

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

+1
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ See the [the reference](../reference/profiles.html) for more details on profiles
100100

101101
{{#options}}
102102
{{> options-jobs }}
103+
{{> options-future-incompat }}
103104
{{/options}}
104105

105106
{{> section-environment }}

‎src/doc/man/cargo-test.md

+1
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ includes an option to control the number of threads used:
153153
{{#options}}
154154

155155
{{> options-jobs }}
156+
{{> options-future-incompat }}
156157

157158
{{/options}}
158159

‎src/doc/man/generated_txt/cargo-build.txt

+6
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,12 @@ OPTIONS
287287
<https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
288288
the number of CPUs.
289289

290+
--future-incompat-report
291+
Displays a future-incompat report for any future-incompatible
292+
warnings produced during execution of this command
293+
294+
See cargo-report(1)
295+
290296
ENVIRONMENT
291297
See the reference
292298
<https://doc.rust-lang.org/cargo/reference/environment-variables.html>

‎src/doc/man/generated_txt/cargo-check.txt

+6
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,12 @@ OPTIONS
281281
<https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
282282
the number of CPUs.
283283

284+
--future-incompat-report
285+
Displays a future-incompat report for any future-incompatible
286+
warnings produced during execution of this command
287+
288+
See cargo-report(1)
289+
284290
ENVIRONMENT
285291
See the reference
286292
<https://doc.rust-lang.org/cargo/reference/environment-variables.html>

‎src/doc/man/generated_txt/cargo-report.txt

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
CARGO-REPORT(1)
2+
3+
NAME
4+
cargo-report - Generate and display various kinds of reports
5+
6+
SYNOPSIS
7+
cargo report type [options]
8+
9+
DESCRIPTION
10+
Displays a report of the given type - currently, only future-incompat is
11+
supported
12+
13+
OPTIONS
14+
--id id
15+
Show the report with the specified Cargo-generated id
16+
17+
-p spec..., --package spec...
18+
Only display a report for the specified package
19+
20+
EXAMPLES
21+
1. Display the latest future-incompat report:
22+
23+
cargo report future-incompat
24+
25+
2. Display the latest future-incompat report for a specific package:
26+
27+
cargo report future-incompat --package my-dep:0.0.1
28+
29+
SEE ALSO
30+
cargo(1)
31+

‎src/doc/man/generated_txt/cargo-rustc.txt

+6
Original file line numberDiff line numberDiff line change
@@ -276,6 +276,12 @@ OPTIONS
276276
<https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
277277
the number of CPUs.
278278

279+
--future-incompat-report
280+
Displays a future-incompat report for any future-incompatible
281+
warnings produced during execution of this command
282+
283+
See cargo-report(1)
284+
279285
ENVIRONMENT
280286
See the reference
281287
<https://doc.rust-lang.org/cargo/reference/environment-variables.html>

‎src/doc/man/generated_txt/cargo-test.txt

+6
Original file line numberDiff line numberDiff line change
@@ -357,6 +357,12 @@ OPTIONS
357357
<https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
358358
the number of CPUs.
359359

360+
--future-incompat-report
361+
Displays a future-incompat report for any future-incompatible
362+
warnings produced during execution of this command
363+
364+
See cargo-report(1)
365+
360366
ENVIRONMENT
361367
See the reference
362368
<https://doc.rust-lang.org/cargo/reference/environment-variables.html>

‎src/doc/man/includes/options-future-incompat.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{#option "`--future-incompat-report`"}}
2+
Displays a future-incompat report for any future-incompatible warnings
3+
produced during execution of this command
4+
5+
See {{man "cargo-report" 1}}
6+
{{/option}}

‎src/doc/src/SUMMARY.md

+2
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
* [Registries](reference/registries.md)
3939
* [Dependency Resolution](reference/resolver.md)
4040
* [SemVer Compatibility](reference/semver.md)
41+
* [Future incompat report](reference/future-incompat-report.md)
4142
* [Unstable Features](reference/unstable.md)
4243

4344
* [Cargo Commands](commands/index.md)
@@ -57,6 +58,7 @@
5758
* [cargo rustc](commands/cargo-rustc.md)
5859
* [cargo rustdoc](commands/cargo-rustdoc.md)
5960
* [cargo test](commands/cargo-test.md)
61+
* [cargo report](commands/cargo-report.md)
6062
* [Manifest Commands](commands/manifest-commands.md)
6163
* [cargo generate-lockfile](commands/cargo-generate-lockfile.md)
6264
* [cargo locate-project](commands/cargo-locate-project.md)

‎src/doc/src/commands/build-commands.md

+1
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,4 @@
1010
* [cargo rustc](cargo-rustc.md)
1111
* [cargo rustdoc](cargo-rustdoc.md)
1212
* [cargo test](cargo-test.md)
13+
* [cargo report](cargo-report.md)

‎src/doc/src/commands/cargo-build.md

+6
Original file line numberDiff line numberDiff line change
@@ -354,6 +354,12 @@ for more information about how toolchain overrides work.</dd>
354354
the number of CPUs.</dd>
355355

356356

357+
<dt class="option-term" id="option-cargo-build---future-incompat-report"><a class="option-anchor" href="#option-cargo-build---future-incompat-report"></a><code>--future-incompat-report</code></dt>
358+
<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings
359+
produced during execution of this command</p>
360+
<p>See <a href="cargo-report.html">cargo-report(1)</a></dd>
361+
362+
357363
</dl>
358364

359365
## ENVIRONMENT

‎src/doc/src/commands/cargo-check.md

+6
Original file line numberDiff line numberDiff line change
@@ -345,6 +345,12 @@ for more information about how toolchain overrides work.</dd>
345345
the number of CPUs.</dd>
346346

347347

348+
<dt class="option-term" id="option-cargo-check---future-incompat-report"><a class="option-anchor" href="#option-cargo-check---future-incompat-report"></a><code>--future-incompat-report</code></dt>
349+
<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings
350+
produced during execution of this command</p>
351+
<p>See <a href="cargo-report.html">cargo-report(1)</a></dd>
352+
353+
348354
</dl>
349355

350356
## ENVIRONMENT

‎src/doc/src/commands/cargo-report.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# cargo-report(1)
2+
3+
## NAME
4+
5+
cargo-report - Generate and display various kinds of reports
6+
7+
## SYNOPSIS
8+
9+
`cargo report` _type_ [_options_]
10+
11+
### DESCRIPTION
12+
13+
Displays a report of the given _type_ - currently, only `future-incompat` is supported
14+
15+
## OPTIONS
16+
17+
<dl>
18+
19+
<dt class="option-term" id="option-cargo-report---id"><a class="option-anchor" href="#option-cargo-report---id"></a><code>--id</code> <em>id</em></dt>
20+
<dd class="option-desc">Show the report with the specified Cargo-generated id</dd>
21+
22+
23+
<dt class="option-term" id="option-cargo-report--p"><a class="option-anchor" href="#option-cargo-report--p"></a><code>-p</code> <em>spec</em>...</dt>
24+
<dt class="option-term" id="option-cargo-report---package"><a class="option-anchor" href="#option-cargo-report---package"></a><code>--package</code> <em>spec</em>...</dt>
25+
<dd class="option-desc">Only display a report for the specified package</dd>
26+
27+
28+
</dl>
29+
30+
## EXAMPLES
31+
32+
1. Display the latest future-incompat report:
33+
34+
cargo report future-incompat
35+
36+
2. Display the latest future-incompat report for a specific package:
37+
38+
cargo report future-incompat --package my-dep:0.0.1
39+
40+
## SEE ALSO
41+
[cargo(1)](cargo.html)

‎src/doc/src/commands/cargo-rustc.md

+6
Original file line numberDiff line numberDiff line change
@@ -337,6 +337,12 @@ for more information about how toolchain overrides work.</dd>
337337
the number of CPUs.</dd>
338338

339339

340+
<dt class="option-term" id="option-cargo-rustc---future-incompat-report"><a class="option-anchor" href="#option-cargo-rustc---future-incompat-report"></a><code>--future-incompat-report</code></dt>
341+
<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings
342+
produced during execution of this command</p>
343+
<p>See <a href="cargo-report.html">cargo-report(1)</a></dd>
344+
345+
340346
</dl>
341347

342348
## ENVIRONMENT

‎src/doc/src/commands/cargo-test.md

+6
Original file line numberDiff line numberDiff line change
@@ -434,6 +434,12 @@ includes an option to control the number of threads used:
434434
the number of CPUs.</dd>
435435

436436

437+
<dt class="option-term" id="option-cargo-test---future-incompat-report"><a class="option-anchor" href="#option-cargo-test---future-incompat-report"></a><code>--future-incompat-report</code></dt>
438+
<dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings
439+
produced during execution of this command</p>
440+
<p>See <a href="cargo-report.html">cargo-report(1)</a></dd>
441+
442+
437443

438444
</dl>
439445

‎src/doc/src/reference/future-incompat-report.md

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
### Future incompat report
2+
3+
Cargo checks for future-incompatible warnings in all dependencies. These are warnings for
4+
changes that may become hard errors in the future, causing the dependency to
5+
stop building in a future version of rustc. If any warnings are found, a small
6+
notice is displayed indicating that the warnings were found, and provides
7+
instructions on how to display a full report.
8+
9+
A full report can be displayed with the `cargo report future-incompatibilities
10+
--id ID` command, or by running the build again with
11+
the `--future-incompat-report` flag. The developer should then update their
12+
dependencies to a version where the issue is fixed, or work with the
13+
developers of the dependencies to help resolve the issue.
14+
15+
This feature can be configured through a `[future-incompat-report]`
16+
section in `.cargo/config`. Currently, the supported options are:
17+
18+
```
19+
[future-incompat-report]
20+
frequency = FREQUENCY
21+
```
22+
23+
The supported values for `FREQUENCY` are 'always` and 'never', which control
24+
whether or not a message is printed out at the end of `cargo build` / `cargo check`.

‎src/doc/src/reference/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,5 @@ The reference covers the details of various areas of Cargo.
2121
* [Registries](registries.md)
2222
* [Dependency Resolution](resolver.md)
2323
* [SemVer Compatibility](semver.md)
24+
* [Future incompat report](future-incompat-report.md)
2425
* [Unstable Features](unstable.md)

‎src/doc/src/reference/unstable.md

+5-30
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,6 @@ Each new feature described below should explain how to use it.
9494
* [Build-plan](#build-plan) — Emits JSON information on which commands will be run.
9595
* [timings](#timings) — Generates a report on how long individual dependencies took to run.
9696
* [unit-graph](#unit-graph) — Emits JSON for Cargo's internal graph structure.
97-
* [future incompat report](#future-incompat-report) — Displays a report for future incompatibilities that may error in the future.
9897
* [`cargo rustc --print`](#rustc---print) — Calls rustc with `--print` to display information from rustc.
9998
* Configuration
10099
* [config-cli](#config-cli) — Adds the ability to pass configuration options on the command-line.
@@ -1143,35 +1142,6 @@ cargo logout -Z credential-process
11431142
[crates.io]: https://crates.io/
11441143
[config file]: config.md
11451144

1146-
### future incompat report
1147-
* RFC: [#2834](https://github.com/rust-lang/rfcs/blob/master/text/2834-cargo-report-future-incompat.md)
1148-
* rustc Tracking Issue: [#71249](https://github.com/rust-lang/rust/issues/71249)
1149-
1150-
The `-Z future-incompat-report` flag causes Cargo to check for
1151-
future-incompatible warnings in all dependencies. These are warnings for
1152-
changes that may become hard errors in the future, causing the dependency to
1153-
stop building in a future version of rustc. If any warnings are found, a small
1154-
notice is displayed indicating that the warnings were found, and provides
1155-
instructions on how to display a full report.
1156-
1157-
A full report can be displayed with the `cargo report future-incompatibilities
1158-
-Z future-incompat-report --id ID` command, or by running the build again with
1159-
the `--future-incompat-report` flag. The developer should then update their
1160-
dependencies to a version where the issue is fixed, or work with the
1161-
developers of the dependencies to help resolve the issue.
1162-
1163-
This feature can be configured through a `[future-incompat-report]`
1164-
section in `.cargo/config`. Currently, the supported options are:
1165-
1166-
```
1167-
[future-incompat-report]
1168-
frequency = FREQUENCY
1169-
```
1170-
1171-
The supported values for `FREQUENCY` are 'always` and 'never', which control
1172-
whether or not a message is printed out at the end of `cargo build` / `cargo check`.
1173-
1174-
11751145
### `cargo config`
11761146

11771147
* Original Issue: [#2362](https://github.com/rust-lang/cargo/issues/2362)
@@ -1403,6 +1373,11 @@ See [`cargo fix --edition`](../commands/cargo-fix.md) and [The Edition Guide](..
14031373
Custom named profiles have been stabilized in the 1.57 release. See the
14041374
[profiles chapter](profiles.md#custom-profiles) for more information.
14051375

1376+
### Future incompat report
1377+
1378+
Support for generating a future-incompat report has been stabilized
1379+
in the 1.59 release. See the [future incompat report chapter](future-incompat-report.md)
1380+
for more information.
14061381

14071382
### scrape-examples
14081383

‎src/etc/man/cargo-build.1

+8
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,14 @@ Number of parallel jobs to run. May also be specified with the
359359
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
360360
the number of CPUs.
361361
.RE
362+
.sp
363+
\fB\-\-future\-incompat\-report\fR
364+
.RS 4
365+
Displays a future\-incompat report for any future\-incompatible warnings
366+
produced during execution of this command
367+
.sp
368+
See \fBcargo\-report\fR(1)
369+
.RE
362370
.SH "ENVIRONMENT"
363371
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
364372
details on environment variables that Cargo reads.

‎src/etc/man/cargo-check.1

+8
Original file line numberDiff line numberDiff line change
@@ -349,6 +349,14 @@ Number of parallel jobs to run. May also be specified with the
349349
\fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
350350
the number of CPUs.
351351
.RE
352+
.sp
353+
\fB\-\-future\-incompat\-report\fR
354+
.RS 4
355+
Displays a future\-incompat report for any future\-incompatible warnings
356+
produced during execution of this command
357+
.sp
358+
See \fBcargo\-report\fR(1)
359+
.RE
352360
.SH "ENVIRONMENT"
353361
See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for
354362
details on environment variables that Cargo reads.

0 commit comments

Comments
 (0)