Document the rust-version field

djc · djc · commit db3776cfef58 · 2021-08-02T13:38:58.000+02:00
diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs
@@ -166,8 +166,7 @@ impl Edition {
         match self {
             Edition2015 => None,
             Edition2018 => Some(semver::Version::new(1, 31, 0)),
-            // FIXME: This will likely be 1.56, update when that seems more likely.
-            Edition2021 => Some(semver::Version::new(1, 62, 0)),
+            Edition2021 => Some(semver::Version::new(1, 56, 0)),
         }
     }
 
diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md
@@ -83,6 +83,8 @@ target.
 
 {{> options-target-triple }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md
@@ -35,6 +35,8 @@ they have `required-features` that are missing.
 
 {{> options-release }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/cargo-check.md b/src/doc/man/cargo-check.md
@@ -42,6 +42,8 @@ they have `required-features` that are missing.
 
 {{> options-profile }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/cargo-doc.md b/src/doc/man/cargo-doc.md
@@ -64,6 +64,8 @@ flag and will always document the given target.
 
 {{> options-release }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/cargo-fix.md b/src/doc/man/cargo-fix.md
@@ -122,6 +122,8 @@ When no target selection options are given, `cargo fix` will fix all targets
 
 {{> options-profile }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/cargo-run.md b/src/doc/man/cargo-run.md
@@ -50,6 +50,8 @@ Run the specified example.
 
 {{> options-release }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md
@@ -47,6 +47,8 @@ binary and library targets of the selected package.
 
 {{> options-release }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/cargo-rustdoc.md b/src/doc/man/cargo-rustdoc.md
@@ -62,6 +62,8 @@ if its name is the same as the lib target. Binaries are skipped if they have
 
 {{> options-release }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md
@@ -102,6 +102,8 @@ target options.
 
 {{> options-release }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options
diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt
@@ -202,6 +202,11 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/guide/build-cache.html>
            documentation for more details.
 
+       --ignore-rust-version
+           Benchmark the target even if the selected Rust compiler is older
+           than the required Rust version as configured in the project's
+           rust-version field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt
@@ -146,6 +146,11 @@ OPTIONS
            Build optimized artifacts with the release profile. See the PROFILES
            section for details on how this affects profile selection.
 
+       --ignore-rust-version
+           Build the target even if the selected Rust compiler is older than
+           the required Rust version as configured in the project's
+           rust-version field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt
@@ -158,6 +158,11 @@ OPTIONS
            have it check unit tests which are usually excluded via the cfg
            attribute. This does not change the actual profile used.
 
+       --ignore-rust-version
+           Check the target even if the selected Rust compiler is older than
+           the required Rust version as configured in the project's
+           rust-version field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt
@@ -123,6 +123,11 @@ OPTIONS
            Document optimized artifacts with the release profile. See the
            PROFILES section for details on how this affects profile selection.
 
+       --ignore-rust-version
+           Document the target even if the selected Rust compiler is older than
+           the required Rust version as configured in the project's
+           rust-version field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt
@@ -231,6 +231,11 @@ OPTIONS
            it fix unit tests which are usually excluded via the cfg attribute.
            This does not change the actual profile used.
 
+       --ignore-rust-version
+           Fix the target even if the selected Rust compiler is older than the
+           required Rust version as configured in the project's rust-version
+           field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt
@@ -75,6 +75,11 @@ OPTIONS
            Run optimized artifacts with the release profile. See the PROFILES
            section for details on how this affects profile selection.
 
+       --ignore-rust-version
+           Run the target even if the selected Rust compiler is older than the
+           required Rust version as configured in the project's rust-version
+           field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt
@@ -137,6 +137,11 @@ OPTIONS
            Build optimized artifacts with the release profile. See the PROFILES
            section for details on how this affects profile selection.
 
+       --ignore-rust-version
+           Build the target even if the selected Rust compiler is older than
+           the required Rust version as configured in the project's
+           rust-version field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt
@@ -146,6 +146,11 @@ OPTIONS
            Document optimized artifacts with the release profile. See the
            PROFILES section for details on how this affects profile selection.
 
+       --ignore-rust-version
+           Document the target even if the selected Rust compiler is older than
+           the required Rust version as configured in the project's
+           rust-version field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt
@@ -223,6 +223,11 @@ OPTIONS
            Test optimized artifacts with the release profile. See the PROFILES
            section for details on how this affects profile selection.
 
+       --ignore-rust-version
+           Test the target even if the selected Rust compiler is older than the
+           required Rust version as configured in the project's rust-version
+           field.
+
    Output Options
        --target-dir directory
            Directory for all generated artifacts and intermediate files. May
diff --git a/src/doc/man/includes/options-ignore-rust-version.md b/src/doc/man/includes/options-ignore-rust-version.md
@@ -0,0 +1,4 @@
+{{#option "`--ignore-rust-version`"}}
+{{actionverb}} the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's `rust-version` field.
+{{/option}}
diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md
@@ -245,6 +245,12 @@ target artifacts are placed in a separate directory. See the
 
 
 
+<dt class="option-term" id="option-cargo-bench---ignore-rust-version"><a class="option-anchor" href="#option-cargo-bench---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Benchmark the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md
@@ -188,6 +188,12 @@ selection.</dd>
 
 
 
+<dt class="option-term" id="option-cargo-build---ignore-rust-version"><a class="option-anchor" href="#option-cargo-build---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Build the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md
@@ -202,6 +202,12 @@ used.</dd>
 
 
 
+<dt class="option-term" id="option-cargo-check---ignore-rust-version"><a class="option-anchor" href="#option-cargo-check---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Check the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md
@@ -161,6 +161,12 @@ selection.</dd>
 
 
 
+<dt class="option-term" id="option-cargo-doc---ignore-rust-version"><a class="option-anchor" href="#option-cargo-doc---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Document the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md
@@ -282,6 +282,12 @@ used.</dd>
 
 
 
+<dt class="option-term" id="option-cargo-fix---ignore-rust-version"><a class="option-anchor" href="#option-cargo-fix---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Fix the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md
@@ -106,6 +106,12 @@ selection.</dd>
 
 
 
+<dt class="option-term" id="option-cargo-run---ignore-rust-version"><a class="option-anchor" href="#option-cargo-run---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Run the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md
@@ -175,6 +175,12 @@ selection.</dd>
 
 
 
+<dt class="option-term" id="option-cargo-rustc---ignore-rust-version"><a class="option-anchor" href="#option-cargo-rustc---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Build the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md
@@ -190,6 +190,12 @@ selection.</dd>
 
 
 
+<dt class="option-term" id="option-cargo-rustdoc---ignore-rust-version"><a class="option-anchor" href="#option-cargo-rustdoc---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Document the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md
@@ -269,6 +269,12 @@ selection.</dd>
 
 
 
+<dt class="option-term" id="option-cargo-test---ignore-rust-version"><a class="option-anchor" href="#option-cargo-test---ignore-rust-version"></a><code>--ignore-rust-version</code></dt>
+<dd class="option-desc">Test the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's <code>rust-version</code> field.</dd>
+
+
+
 </dl>
 
 ### Output Options
diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
@@ -9,6 +9,7 @@ in the [TOML] format. Every manifest file consists of the following sections:
   * [`version`](#the-version-field) — The version of the package.
   * [`authors`](#the-authors-field) — The authors of the package.
   * [`edition`](#the-edition-field) — The Rust edition.
+  * [`rust-version`](#the-rust-version-field) — The minimal supported Rust version.
   * [`description`](#the-description-field) — A description of the package.
   * [`documentation`](#the-documentation-field) — URL of the package documentation.
   * [`readme`](#the-readme-field) — Path to the package's README file.
@@ -144,6 +145,33 @@ assumed for backwards compatibility. Note that all manifests
 created with [`cargo new`] will not use this historical fallback because they
 will have `edition` explicitly specified to a newer value.
 
+#### The `rust-version` field
+
+The `rust-version` field is an optional key that tells cargo what version of the
+Rust language and compiler your package can be compiled with. If the currently
+selected version of the Rust compiler is older than the stated version, cargo
+will exit with an error, telling the user what version is required.
+
+The first version of Cargo that supports this field was released with Rust 1.56.0.
+In older releases, the field will be ignored, and Cargo will display a warning.
+
+```toml
+[package]
+# ...
+rust-version = "1.56"
+```
+
+The Rust version must be a bare version number with two or three components; it
+cannot include semver operators or pre-release identifiers. Compiler pre-release
+identifiers such as -nightly will be ignored while checking the Rust version.
+The `rust-version` must be equal to or newer than the version that first
+introduced the configured `edition`.
+
+The `rust-version` may be ignored using the `--ignore-rust-version` option.
+
+Setting the `rust-version` key in `[package]` will affect all targets/crates in
+the package, including test suites, benchmarks, binaries, examples, etc.
+
 #### The `description` field
 
 The description is a short blurb about the package. [crates.io] will display
diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
@@ -1420,3 +1420,9 @@ The `configurable-env` feature to specify environment variables in Cargo
 configuration has been stabilized in the 1.56 release. See the [config
 documentation](config.html#env) for more information about configuring
 environment variables.
+
+### rust-version
+
+The `rust-version` field in `Cargo.toml` has been stabilized in the 1.56 release.
+See the [rust-version field](manifest.html#the-rust-version-field) for more
+information on using the `rust-version` field and the `--ignore-rust-version` option.
diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1
@@ -250,6 +250,12 @@ Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
 \fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
 .RE
+.sp
+\fB\-\-ignore\-rust\-version\fR
+.RS 4
+Benchmark the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's \fBrust\-version\fR field.
+.RE
 .SS "Output Options"
 .sp
 \fB\-\-target\-dir\fR \fIdirectory\fR
diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1
@@ -175,6 +175,12 @@ Build optimized artifacts with the \fBrelease\fR profile. See the
 PROFILES section for details on how this affects profile
 selection.
 .RE
+.sp
+\fB\-\-ignore\-rust\-version\fR
+.RS 4
+Build the target even if the selected Rust compiler is older than the
+required Rust version as configured in the project's \fBrust\-version\fR field.
+.RE
 .SS "Output Options"
 .sp
 \fB\-\-target\-dir\fR \fIdirectory\fR
diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1
diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1
diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1
diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1
diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1
diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1
diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1

Original file line number	Diff line number	Diff line change
`@@ -166,8 +166,7 @@ impl Edition {`
`166`	`166`	`match self {`
`167`	`167`	`Edition2015 => None,`
`168`	`168`	`Edition2018 => Some(semver::Version::new(1, 31, 0)),`
`169`		`- // FIXME: This will likely be 1.56, update when that seems more likely.`
`170`		`- Edition2021 => Some(semver::Version::new(1, 62, 0)),`
	`169`	`+ Edition2021 => Some(semver::Version::new(1, 56, 0)),`
`171`	`170`	`}`
`172`	`171`	`}`
`173`	`172`