Auto merge of rust-lang#9732 - djc:rust-version-docs, r=ehuss

Stabilize the rust-version field

I've tried to make the documentation here fairly comprehensive. I've also updated the first version for the 2021 edition, which should now be stable pending substantial unforeseen changes.

See rust-lang#8072.

CHANGELOG.md

@@ -5,6 +5,8 @@
 
 ### Added
 
+- Added support for the [`rust-version`](https://doc.rust-lang.org/nightly/cargo/reference/manifest.html#the-rust-version-field)
+  field in a crate's metadata and the `--ignore-rust-version` command line option.
 - Build scripts can now pass additional linker arguments for binaries or all
   linkable targets. [docs](https://doc.rust-lang.org/nightly/cargo/reference/build-scripts.html#outputs-of-the-build-script)
   [#9557](https://github.com/rust-lang/cargo/pull/9557)

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)),
         }
     }
 
@@ -396,7 +395,7 @@ features! {
     (unstable, strip, "", "reference/unstable.html#profile-strip-option"),
 
     // Specifying a minimal 'rust-version' attribute for crates
-    (unstable, rust_version, "", "reference/unstable.html#rust-version"),
+    (stable, rust_version, "1.56", "reference/manifest.html#the-rust-version-field"),
 
     // Support for 2021 edition.
     (unstable, edition2021, "", "reference/unstable.html#edition-2021"),

src/cargo/util/command_prelude.rs

@@ -218,7 +218,7 @@ pub trait AppExt: Sized {
     fn arg_ignore_rust_version(self) -> Self {
         self._arg(opt(
             "ignore-rust-version",
-            "Ignore `rust-version` specification in packages (unstable)",
+            "Ignore `rust-version` specification in packages",
         ))
     }
 
@@ -533,12 +533,6 @@ pub trait ArgMatchesExt {
             honor_rust_version: !self._is_present("ignore-rust-version"),
         };
 
-        if !opts.honor_rust_version {
-            config
-                .cli_unstable()
-                .fail_if_stable_opt("--ignore-rust-version", 8072)?;
-        }
-
         if let Some(ws) = workspace {
             self.check_optional_opts(ws, &opts)?;
         } else if self.is_present_with_zero_values("package") {

src/cargo/util/toml/mod.rs

@@ -1122,46 +1122,25 @@ impl TomlManifest {
         }
 
         let rust_version = if let Some(rust_version) = &project.rust_version {
-            if features.require(Feature::rust_version()).is_err() {
-                let mut msg =
-                    "`rust-version` is not supported on this version of Cargo and will be ignored"
-                        .to_string();
-                if config.nightly_features_allowed {
-                    msg.push_str(
-                        "\n\n\
-                        consider adding `cargo-features = [\"rust-version\"]` to the manifest",
-                    );
-                } else {
-                    msg.push_str(
-                        "\n\n\
-                        this Cargo does not support nightly features, but if you\n\
-                        switch to nightly channel you can add\n\
-                        `cargo-features = [\"rust-version\"]` to enable this feature",
-                    );
-                }
-                warnings.push(msg);
-                None
-            } else {
-                let req = match semver::VersionReq::parse(rust_version) {
-                    // Exclude semver operators like `^` and pre-release identifiers
-                    Ok(req) if rust_version.chars().all(|c| c.is_ascii_digit() || c == '.') => req,
-                    _ => bail!("`rust-version` must be a value like \"1.32\""),
-                };
-                if let Some(first_version) = edition.first_version() {
-                    let unsupported =
-                        semver::Version::new(first_version.major, first_version.minor - 1, 9999);
-                    if req.matches(&unsupported) {
-                        bail!(
-                            "rust-version {} is older than first version ({}) required by \
-                                the specified edition ({})",
-                            rust_version,
-                            first_version,
-                            edition,
-                        )
-                    }
+            let req = match semver::VersionReq::parse(rust_version) {
+                // Exclude semver operators like `^` and pre-release identifiers
+                Ok(req) if rust_version.chars().all(|c| c.is_ascii_digit() || c == '.') => req,
+                _ => bail!("`rust-version` must be a value like \"1.32\""),
+            };
+            if let Some(first_version) = edition.first_version() {
+                let unsupported =
+                    semver::Version::new(first_version.major, first_version.minor - 1, 9999);
+                if req.matches(&unsupported) {
+                    bail!(
+                        "rust-version {} is older than first version ({}) required by \
+                            the specified edition ({})",
+                        rust_version,
+                        first_version,
+                        edition,
+                    )
                 }
-                Some(rust_version.clone())
             }
+            Some(rust_version.clone())
         } else {
             None
         };

src/doc/man/cargo-bench.md

@@ -83,6 +83,8 @@ target.
 
 {{> options-target-triple }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options

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

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

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

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

src/doc/man/cargo-run.md

@@ -50,6 +50,8 @@ Run the specified example.
 
 {{> options-release }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options

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

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

src/doc/man/cargo-test.md

@@ -102,6 +102,8 @@ target options.
 
 {{> options-release }}
 
+{{> options-ignore-rust-version }}
+
 {{/options}}
 
 ### Output Options

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

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

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

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

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

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

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

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

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

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}}

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

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

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

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

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

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

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