#
cargo/core/
features.rs

    1//! Support for nightly features in Cargo itself.
    2//!
    3//! This file is the version of `feature_gate.rs` in upstream Rust for Cargo
    4//! itself and is intended to be the avenue for which new features in Cargo are
    5//! gated by default and then eventually stabilized. All known stable and
    6//! unstable features are tracked in this file.
    7//!
    8//! If you're reading this then you're likely interested in adding a feature to
    9//! Cargo, and the good news is that it shouldn't be too hard! First determine
    10//! how the feature should be gated:
    11//!
    12//! * Error when the feature is used without the gate
    13//!   * Required if ignoring the feature violates the users intent in non-superficial ways
    14//!   * A low-effort / safe way to protect the user from being broken if the format of the feature changes in
    15//!     incompatible was (can be worked around)
    16//!   * Good for: CLI (gate: `-Zunstable-options` or `-Z` if combined with other changes), `Cargo.toml` (gate: `cargo-features`)
    17//! * Warn that the feature is ignored due to lack of the gate
    18//!   * For if you could opt-in to the unimplemented feature on Cargo today and Cargo would
    19//!     operate just fine
    20//!   * If gate is not enabled, prefer to warn if the format of the feature is incompatible
    21//!     (instead of error or ignore)
    22//!   * Good for: `Cargo.toml`, `.cargo/config.toml`, `config.json` index file (gate: `-Z`)
    23//! * Ignore the feature that is used without a gate
    24//!   * For when ignoring the feature has so little impact that annoying the user is not worth it
    25//!     (e.g. a config field that changes Cargo's terminal output)
    26//!   * For behavior changes without an interface (e.g. the resolver)
    27//!   * Good for: `.cargo/config.toml`, `config.json` index file (gate: `-Z`)
    28//!
    29//! For features that touch multiple parts of Cargo, multiple feature gating strategies (error,
    30//! warn, ignore) and mechanisms (`-Z`, `cargo-features`) may be used.
    31//!
    32//! When adding new tests for your feature, usually the tests should go into a
    33//! new module of the testsuite named after the feature. See
    34//! <https://doc.crates.io/contrib/tests/writing.html> for more information on
    35//! writing tests. Particularly, check out the "Testing Nightly Features"
    36//! section for testing unstable features. Be sure to test the feature gate itself.
    37//!
    38//! After you have added your feature, be sure to update the unstable
    39//! documentation at `src/doc/src/reference/unstable.md` to include a short
    40//! description of how to use your new feature.
    41//!
    42//! And hopefully that's it!
    43//!
    44//! ## `cargo-features`
    45//!
    46//! The steps for adding new Cargo.toml syntax are:
    47//!
    48//! 1. Add the cargo-features unstable gate. Search the code below for "look here" to
    49//!    find the [`features!`] macro invocation and add your feature to the list.
    50//!
    51//! 2. Update the Cargo.toml parsing code to handle your new feature.
    52//!
    53//! 3. Wherever you added the new parsing code, call
    54//!    `features.require(Feature::my_feature_name())?` if the new syntax is
    55//!    used. This will return an error if the user hasn't listed the feature
    56//!    in `cargo-features` or this is not the nightly channel.
    57//!
    58//! ## `-Z unstable-options`
    59//!
    60//! `-Z unstable-options` is intended to force the user to opt-in to new CLI
    61//! flags, options, and new subcommands.
    62//!
    63//! The steps to add a new command-line option are:
    64//!
    65//! 1. Add the option to the CLI parsing code. In the help text, be sure to
    66//!    include `(unstable)` to note that this is an unstable option.
    67//! 2. Where the CLI option is loaded, be sure to call
    68//!    [`CliUnstable::fail_if_stable_opt`]. This will return an error if `-Z
    69//!    unstable options` was not passed.
    70//!
    71//! ## `-Z` options
    72//!
    73//! New `-Z` options cover all other functionality that isn't covered with
    74//! `cargo-features` or `-Z unstable-options`.
    75//!
    76//! The steps to add a new `-Z` option are:
    77//!
    78//! 1. Add the option to the [`CliUnstable`] struct in the macro invocation of
    79//!    [`unstable_cli_options!`]. Flags can take an optional value if you want.
    80//! 2. Update the [`CliUnstable::add`] function to parse the flag.
    81//! 3. Wherever the new functionality is implemented, call
    82//!    [`GlobalContext::cli_unstable`] to get an instance of [`CliUnstable`]
    83//!    and check if the option has been enabled on the [`CliUnstable`] instance.
    84//!    Nightly gating is already handled, so no need to worry about that.
    85//!    If warning when feature is used without the gate, be sure to gracefully degrade (with a
    86//!    warning) when the `Cargo.toml` / `.cargo/config.toml` field usage doesn't match the
    87//!    schema.
    88//! 4. For any `Cargo.toml` fields, strip them in [`prepare_for_publish`] if the gate isn't set
    89//!
    90//! ## Stabilization
    91//!
    92//! For the stabilization process, see
    93//! <https://doc.crates.io/contrib/process/unstable.html#stabilization>.
    94//!
    95//! The steps for stabilizing are roughly:
    96//!
    97//! 1. Update the feature to be stable, based on the kind of feature:
    98//!   1. `cargo-features`: Change the feature to `stable` in the [`features!`]
    99//!      macro invocation below, and include the version and a URL for the
    100//!      documentation.
    101//!   2. `-Z unstable-options`: Find the call to [`fail_if_stable_opt`] and
    102//!      remove it. Be sure to update the man pages if necessary.
    103//!   3. `-Z` flag: Change the parsing code in [`CliUnstable::add`] to call
    104//!      `stabilized_warn` or `stabilized_err` and remove the field from
    105//!      [`CliUnstable`]. Remove the `(unstable)` note in the clap help text if
    106//!      necessary.
    107//! 2. Remove `masquerade_as_nightly_cargo` from any tests, and remove
    108//!    `cargo-features` from `Cargo.toml` test files if any. You can
    109//!     quickly find what needs to be removed by searching for the name
    110//!     of the feature, e.g. `print_im_a_teapot`
    111//! 3. Update the docs in unstable.md to move the section to the bottom
    112//!    and summarize it similar to the other entries. Update the rest of the
    113//!    documentation to add the new feature.
    114//!
    115//! [`GlobalContext::cli_unstable`]: crate::util::context::GlobalContext::cli_unstable
    116//! [`fail_if_stable_opt`]: CliUnstable::fail_if_stable_opt
    117//! [`features!`]: macro.features.html
    118//! [`unstable_cli_options!`]: macro.unstable_cli_options.html
    119//! [`prepare_for_publish`]: crate::util::toml::prepare_for_publish
    120
    121use std::collections::BTreeSet;
    122use std::env;
    123use std::fmt::{self, Write};
    124use std::path::PathBuf;
    125use std::str::FromStr;
    126
    127use anyhow::{bail, Error};
    128use cargo_util::ProcessBuilder;
    129use serde::{Deserialize, Serialize};
    130
    131use crate::core::resolver::ResolveBehavior;
    132use crate::util::errors::CargoResult;
    133use crate::util::indented_lines;
    134use crate::GlobalContext;
    135
    136pub const SEE_CHANNELS: &str =
    137    "See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more information \
    138     about Rust release channels.";
    139
    140/// Value of [`allow-features`](CliUnstable::allow_features)
    141pub type AllowFeatures = BTreeSet<String>;
    142
    143/// The edition of the compiler ([RFC 2052])
    144///
    145/// The following sections will guide you how to add and stabilize an edition.
    146///
    147/// ## Adding a new edition
    148///
    149/// - Add the next edition to the enum.
    150/// - Update every match expression that now fails to compile.
    151/// - Update the [`FromStr`] impl.
    152/// - Update [`CLI_VALUES`] to include the new edition.
    153/// - Set [`LATEST_UNSTABLE`] to Some with the new edition.
    154/// - Update the shell completion files.
    155/// - Update any failing tests (hopefully there are very few).
    156///
    157/// ## Stabilization instructions
    158///
    159/// - Set [`LATEST_UNSTABLE`] to None.
    160/// - Set [`LATEST_STABLE`] to the new version.
    161/// - Update [`is_stable`] to `true`.
    162/// - Set [`first_version`] to the version it will be released.
    163/// - Update any tests that are affected.
    164/// - Update the man page for the `--edition` flag.
    165/// - Update the documentation:
    166///   - Update any features impacted by the edition.
    167///   - Update manifest.md#the-edition-field.
    168///   - Update the `--edition` flag (options-new.md).
    169///   - Rebuild man pages.
    170///
    171/// [RFC 2052]: https://rust-lang.github.io/rfcs/2052-epochs.html
    172/// [`FromStr`]: Edition::from_str
    173/// [`CLI_VALUES`]: Edition::CLI_VALUES
    174/// [`LATEST_UNSTABLE`]: Edition::LATEST_UNSTABLE
    175/// [`LATEST_STABLE`]: Edition::LATEST_STABLE
    176/// [`first_version`]: Edition::first_version
    177/// [`is_stable`]: Edition::is_stable
    178/// [`toml`]: crate::util::toml
    179/// [`features!`]: macro.features.html
    180#[derive(
    181    Default, Clone, Copy, Debug, Hash, PartialOrd, Ord, Eq, PartialEq, Serialize, Deserialize,
    182)]
    183pub enum Edition {
    184    /// The 2015 edition
    185    #[default]
    186    Edition2015,
    187    /// The 2018 edition
    188    Edition2018,
    189    /// The 2021 edition
    190    Edition2021,
    191    /// The 2024 edition
    192    Edition2024,
    193    /// The future edition (permanently unstable)
    194    EditionFuture,
    195}
    196
    197impl Edition {
    198    /// The latest edition that is unstable.
    199    ///
    200    /// This is `None` if there is no next unstable edition.
    201    ///
    202    /// Note that this does *not* include "future" since this is primarily
    203    /// used for tests that need to step between stable and unstable.
    204    pub const LATEST_UNSTABLE: Option<Edition> = None;
    205    /// The latest stable edition.
    206    pub const LATEST_STABLE: Edition = Edition::Edition2024;
    207    pub const ALL: &'static [Edition] = &[
    208        Self::Edition2015,
    209        Self::Edition2018,
    210        Self::Edition2021,
    211        Self::Edition2024,
    212        Self::EditionFuture,
    213    ];
    214    /// Possible values allowed for the `--edition` CLI flag.
    215    ///
    216    /// This requires a static value due to the way clap works, otherwise I
    217    /// would have built this dynamically.
    218    ///
    219    /// This does not include `future` since we don't need to create new
    220    /// packages with it.
    221    pub const CLI_VALUES: [&'static str; 4] = ["2015", "2018", "2021", "2024"];
    222
    223    /// Returns the first version that a particular edition was released on
    224    /// stable.
    225    pub(crate) fn first_version(&self) -> Option<semver::Version> {
    226        use Edition::*;
    227        match self {
    228            Edition2015 => None,
    229            Edition2018 => Some(semver::Version::new(1, 31, 0)),
    230            Edition2021 => Some(semver::Version::new(1, 56, 0)),
    231            Edition2024 => Some(semver::Version::new(1, 85, 0)),
    232            EditionFuture => None,
    233        }
    234    }
    235
    236    /// Returns `true` if this edition is stable in this release.
    237    pub fn is_stable(&self) -> bool {
    238        use Edition::*;
    239        match self {
    240            Edition2015 => true,
    241            Edition2018 => true,
    242            Edition2021 => true,
    243            Edition2024 => true,
    244            EditionFuture => false,
    245        }
    246    }
    247
    248    /// Returns the previous edition from this edition.
    249    ///
    250    /// Returns `None` for 2015.
    251    pub fn previous(&self) -> Option<Edition> {
    252        use Edition::*;
    253        match self {
    254            Edition2015 => None,
    255            Edition2018 => Some(Edition2015),
    256            Edition2021 => Some(Edition2018),
    257            Edition2024 => Some(Edition2021),
    258            EditionFuture => panic!("future does not have a previous edition"),
    259        }
    260    }
    261
    262    /// Returns the next edition from this edition, returning the last edition
    263    /// if this is already the last one.
    264    pub fn saturating_next(&self) -> Edition {
    265        use Edition::*;
    266        // Nothing should treat "future" as being next.
    267        match self {
    268            Edition2015 => Edition2018,
    269            Edition2018 => Edition2021,
    270            Edition2021 => Edition2024,
    271            Edition2024 => Edition2024,
    272            EditionFuture => EditionFuture,
    273        }
    274    }
    275
    276    /// Updates the given [`ProcessBuilder`] to include the appropriate flags
    277    /// for setting the edition.
    278    pub(crate) fn cmd_edition_arg(&self, cmd: &mut ProcessBuilder) {
    279        cmd.arg(format!("--edition={}", self));
    280        if !self.is_stable() {
    281            cmd.arg("-Z").arg("unstable-options");
    282        }
    283    }
    284
    285    /// Adds the appropriate argument to generate warnings for this edition.
    286    pub(crate) fn force_warn_arg(&self, cmd: &mut ProcessBuilder) {
    287        use Edition::*;
    288        match self {
    289            Edition2015 => {}
    290            EditionFuture => {
    291                cmd.arg("--force-warn=edition_future_compatibility");
    292            }
    293            e => {
    294                // Note that cargo always passes this even if the
    295                // compatibility lint group does not exist. When a new edition
    296                // is introduced, but there are no migration lints, rustc does
    297                // not create the lint group. That's OK because rustc will
    298                // just generate a warning about an unknown lint which will be
    299                // suppressed due to cap-lints.
    300                cmd.arg(format!("--force-warn=rust-{e}-compatibility"));
    301            }
    302        }
    303    }
    304
    305    /// Whether or not this edition supports the `rust_*_idioms` lint.
    306    ///
    307    /// Ideally this would not be necessary...
    308    pub(crate) fn supports_idiom_lint(&self) -> bool {
    309        use Edition::*;
    310        match self {
    311            Edition2015 => false,
    312            Edition2018 => true,
    313            Edition2021 => false,
    314            Edition2024 => false,
    315            EditionFuture => false,
    316        }
    317    }
    318
    319    pub(crate) fn default_resolve_behavior(&self) -> ResolveBehavior {
    320        if *self >= Edition::Edition2024 {
    321            ResolveBehavior::V3
    322        } else if *self >= Edition::Edition2021 {
    323            ResolveBehavior::V2
    324        } else {
    325            ResolveBehavior::V1
    326        }
    327    }
    328}
    329
    330impl fmt::Display for Edition {
    331    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    332        match *self {
    333            Edition::Edition2015 => f.write_str("2015"),
    334            Edition::Edition2018 => f.write_str("2018"),
    335            Edition::Edition2021 => f.write_str("2021"),
    336            Edition::Edition2024 => f.write_str("2024"),
    337            Edition::EditionFuture => f.write_str("future"),
    338        }
    339    }
    340}
    341
    342impl FromStr for Edition {
    343    type Err = Error;
    344    fn from_str(s: &str) -> Result<Self, Error> {
    345        match s {
    346            "2015" => Ok(Edition::Edition2015),
    347            "2018" => Ok(Edition::Edition2018),
    348            "2021" => Ok(Edition::Edition2021),
    349            "2024" => Ok(Edition::Edition2024),
    350            "future" => Ok(Edition::EditionFuture),
    351            s if s.parse().map_or(false, |y: u16| y > 2024 && y < 2050) => bail!(
    352                "this version of Cargo is older than the `{}` edition, \
    353                 and only supports `2015`, `2018`, `2021`, and `2024` editions.",
    354                s
    355            ),
    356            s => bail!(
    357                "supported edition values are `2015`, `2018`, `2021`, or `2024`, \
    358                 but `{}` is unknown",
    359                s
    360            ),
    361        }
    362    }
    363}
    364
    365/// The value for `-Zfix-edition`.
    366#[derive(Debug, Deserialize)]
    367pub enum FixEdition {
    368    /// `-Zfix-edition=start=$INITIAL`
    369    ///
    370    /// This mode for `cargo fix` will just run `cargo check` if the current
    371    /// edition is equal to this edition. If it is a different edition, then
    372    /// it just exits with success. This is used for crater integration which
    373    /// needs to set a baseline for the "before" toolchain.
    374    Start(Edition),
    375    /// `-Zfix-edition=end=$INITIAL,$NEXT`
    376    ///
    377    /// This mode for `cargo fix` will migrate to the `next` edition if the
    378    /// current edition is `initial`. After migration, it will update
    379    /// `Cargo.toml` and verify that that it works on the new edition. If the
    380    /// current edition is not `initial`, then it immediately exits with
    381    /// success since we just want to ignore those packages.
    382    End { initial: Edition, next: Edition },
    383}
    384
    385impl FromStr for FixEdition {
    386    type Err = anyhow::Error;
    387    fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
    388        if let Some(start) = s.strip_prefix("start=") {
    389            Ok(FixEdition::Start(start.parse()?))
    390        } else if let Some(end) = s.strip_prefix("end=") {
    391            let (initial, next) = end
    392                .split_once(',')
    393                .ok_or_else(|| anyhow::format_err!("expected `initial,next`"))?;
    394            Ok(FixEdition::End {
    395                initial: initial.parse()?,
    396                next: next.parse()?,
    397            })
    398        } else {
    399            bail!("invalid `-Zfix-edition, expected start= or end=, got `{s}`");
    400        }
    401    }
    402}
    403
    404#[derive(Debug, PartialEq)]
    405enum Status {
    406    Stable,
    407    Unstable,
    408    Removed,
    409}
    410
    411/// A listing of stable and unstable new syntax in Cargo.toml.
    412///
    413/// This generates definitions and impls for [`Features`] and [`Feature`]
    414/// for each new syntax.
    415///
    416/// Note that all feature names in the macro invocation are valid Rust
    417/// identifiers, but the `_` character is translated to `-` when specified in
    418/// the `cargo-features` manifest entry in `Cargo.toml`.
    419///
    420/// See the [module-level documentation](self#new-cargotoml-syntax)
    421/// for the process of adding a new syntax.
    422macro_rules! features {
    423    (
    424        $(
    425            $(#[$attr:meta])*
    426            ($stab:ident, $feature:ident, $version:expr, $docs:expr),
    427        )*
    428    ) => (
    429        /// Unstable feature context for querying if a new Cargo.toml syntax
    430        /// is allowed to use.
    431        ///
    432        /// See the [module-level documentation](self#new-cargotoml-syntax) for the usage.
    433        #[derive(Default, Clone, Debug)]
    434        pub struct Features {
    435            $($feature: bool,)*
    436            /// The current activated features.
    437            activated: Vec<String>,
    438            /// Whether is allowed to use any unstable features.
    439            nightly_features_allowed: bool,
    440            /// Whether the source manifest is from a local package.
    441            is_local: bool,
    442        }
    443
    444        impl Feature {
    445            $(
    446                $(#[$attr])*
    447                #[doc = concat!("\n\n\nSee <https://doc.rust-lang.org/nightly/cargo/", $docs, ">.")]
    448                pub const fn $feature() -> &'static Feature {
    449                    fn get(features: &Features) -> bool {
    450                        stab!($stab) == Status::Stable || features.$feature
    451                    }
    452                    const FEAT: Feature = Feature {
    453                        name: stringify!($feature),
    454                        stability: stab!($stab),
    455                        version: $version,
    456                        docs: $docs,
    457                        get,
    458                    };
    459                    &FEAT
    460                }
    461            )*
    462
    463            /// Whether this feature is allowed to use in the given [`Features`] context.
    464            fn is_enabled(&self, features: &Features) -> bool {
    465                (self.get)(features)
    466            }
    467
    468            pub(crate) fn name(&self) -> &str {
    469                self.name
    470            }
    471        }
    472
    473        impl Features {
    474            fn status(&mut self, feature: &str) -> Option<(&mut bool, &'static Feature)> {
    475                if feature.contains("_") {
    476                    return None;
    477                }
    478                let feature = feature.replace("-", "_");
    479                $(
    480                    if feature == stringify!($feature) {
    481                        return Some((&mut self.$feature, Feature::$feature()));
    482                    }
    483                )*
    484                None
    485            }
    486        }
    487    )
    488}
    489
    490macro_rules! stab {
    491    (stable) => {
    492        Status::Stable
    493    };
    494    (unstable) => {
    495        Status::Unstable
    496    };
    497    (removed) => {
    498        Status::Removed
    499    };
    500}
    501
    502// "look here"
    503features! {
    504    /// A dummy feature that doesn't actually gate anything, but it's used in
    505    /// testing to ensure that we can enable stable features.
    506    (stable, test_dummy_stable, "1.0", ""),
    507
    508    /// A dummy feature that gates the usage of the `im-a-teapot` manifest
    509    /// entry. This is basically just intended for tests.
    510    (unstable, test_dummy_unstable, "", "reference/unstable.html"),
    511
    512    /// Downloading packages from alternative registry indexes.
    513    (stable, alternative_registries, "1.34", "reference/registries.html"),
    514
    515    /// Using editions
    516    (stable, edition, "1.31", "reference/manifest.html#the-edition-field"),
    517
    518    /// Renaming a package in the manifest via the `package` key.
    519    (stable, rename_dependency, "1.31", "reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml"),
    520
    521    /// Whether a lock file is published with this crate.
    522    (removed, publish_lockfile, "1.37", "reference/unstable.html#publish-lockfile"),
    523
    524    /// Overriding profiles for dependencies.
    525    (stable, profile_overrides, "1.41", "reference/profiles.html#overrides"),
    526
    527    /// "default-run" manifest option.
    528    (stable, default_run, "1.37", "reference/manifest.html#the-default-run-field"),
    529
    530    /// Declarative build scripts.
    531    (unstable, metabuild, "", "reference/unstable.html#metabuild"),
    532
    533    /// Specifying the 'public' attribute on dependencies.
    534    (unstable, public_dependency, "", "reference/unstable.html#public-dependency"),
    535
    536    /// Allow to specify profiles other than 'dev', 'release', 'test', etc.
    537    (stable, named_profiles, "1.57", "reference/profiles.html#custom-profiles"),
    538
    539    /// Opt-in new-resolver behavior.
    540    (stable, resolver, "1.51", "reference/resolver.html#resolver-versions"),
    541
    542    /// Allow to specify whether binaries should be stripped.
    543    (stable, strip, "1.58", "reference/profiles.html#strip-option"),
    544
    545    /// Specifying a minimal 'rust-version' attribute for crates.
    546    (stable, rust_version, "1.56", "reference/manifest.html#the-rust-version-field"),
    547
    548    /// Support for 2021 edition.
    549    (stable, edition2021, "1.56", "reference/manifest.html#the-edition-field"),
    550
    551    /// Allow to specify per-package targets (compile kinds).
    552    (unstable, per_package_target, "", "reference/unstable.html#per-package-target"),
    553
    554    /// Allow to specify which codegen backend should be used.
    555    (unstable, codegen_backend, "", "reference/unstable.html#codegen-backend"),
    556
    557    /// Allow specifying different binary name apart from the crate name.
    558    (unstable, different_binary_name, "", "reference/unstable.html#different-binary-name"),
    559
    560    /// Allow specifying rustflags directly in a profile.
    561    (unstable, profile_rustflags, "", "reference/unstable.html#profile-rustflags-option"),
    562
    563    /// Allow workspace members to inherit fields and dependencies from a workspace.
    564    (stable, workspace_inheritance, "1.64", "reference/unstable.html#workspace-inheritance"),
    565
    566    /// Support for 2024 edition.
    567    (stable, edition2024, "1.85", "reference/manifest.html#the-edition-field"),
    568
    569    /// Allow setting trim-paths in a profile to control the sanitisation of file paths in build outputs.
    570    (unstable, trim_paths, "", "reference/unstable.html#profile-trim-paths-option"),
    571
    572    /// Allow multiple packages to participate in the same API namespace
    573    (unstable, open_namespaces, "", "reference/unstable.html#open-namespaces"),
    574
    575    /// Allow paths that resolve relatively to a base specified in the config.
    576    (unstable, path_bases, "", "reference/unstable.html#path-bases"),
    577
    578    /// Allows use of editions that are not yet stable.
    579    (unstable, unstable_editions, "", "reference/unstable.html#unstable-editions"),
    580}
    581
    582/// Status and metadata for a single unstable feature.
    583#[derive(Debug)]
    584pub struct Feature {
    585    /// Feature name. This is valid Rust identifier so no dash only underscore.
    586    name: &'static str,
    587    stability: Status,
    588    /// Version that this feature was stabilized or removed.
    589    version: &'static str,
    590    /// Link to the unstable documentation.
    591    docs: &'static str,
    592    get: fn(&Features) -> bool,
    593}
    594
    595impl Features {
    596    /// Creates a new unstable features context.
    597    pub fn new(
    598        features: &[String],
    599        gctx: &GlobalContext,
    600        warnings: &mut Vec<String>,
    601        is_local: bool,
    602    ) -> CargoResult<Features> {
    603        let mut ret = Features::default();
    604        ret.nightly_features_allowed = gctx.nightly_features_allowed;
    605        ret.is_local = is_local;
    606        for feature in features {
    607            ret.add(feature, gctx, warnings)?;
    608            ret.activated.push(feature.to_string());
    609        }
    610        Ok(ret)
    611    }
    612
    613    fn add(
    614        &mut self,
    615        feature_name: &str,
    616        gctx: &GlobalContext,
    617        warnings: &mut Vec<String>,
    618    ) -> CargoResult<()> {
    619        let nightly_features_allowed = self.nightly_features_allowed;
    620        let Some((slot, feature)) = self.status(feature_name) else {
    621            bail!("unknown cargo feature `{}`", feature_name)
    622        };
    623
    624        if *slot {
    625            bail!(
    626                "the cargo feature `{}` has already been activated",
    627                feature_name
    628            );
    629        }
    630
    631        let see_docs = || {
    632            format!(
    633                "See {} for more information about using this feature.",
    634                cargo_docs_link(feature.docs)
    635            )
    636        };
    637
    638        match feature.stability {
    639            Status::Stable => {
    640                let warning = format!(
    641                    "the cargo feature `{}` has been stabilized in the {} \
    642                         release and is no longer necessary to be listed in the \
    643                         manifest\n  {}",
    644                    feature_name,
    645                    feature.version,
    646                    see_docs()
    647                );
    648                warnings.push(warning);
    649            }
    650            Status::Unstable if !nightly_features_allowed => bail!(
    651                "the cargo feature `{}` requires a nightly version of \
    652                 Cargo, but this is the `{}` channel\n\
    653                 {}\n{}",
    654                feature_name,
    655                channel(),
    656                SEE_CHANNELS,
    657                see_docs()
    658            ),
    659            Status::Unstable => {
    660                if let Some(allow) = &gctx.cli_unstable().allow_features {
    661                    if !allow.contains(feature_name) {
    662                        bail!(
    663                            "the feature `{}` is not in the list of allowed features: [{}]",
    664                            feature_name,
    665                            itertools::join(allow, ", "),
    666                        );
    667                    }
    668                }
    669            }
    670            Status::Removed => {
    671                let mut msg = format!(
    672                    "the cargo feature `{}` has been removed in the {} release\n\n",
    673                    feature_name, feature.version
    674                );
    675                if self.is_local {
    676                    let _ = writeln!(
    677                        msg,
    678                        "Remove the feature from Cargo.toml to remove this error."
    679                    );
    680                } else {
    681                    let _ = writeln!(
    682                        msg,
    683                        "This package cannot be used with this version of Cargo, \
    684                         as the unstable feature `{}` is no longer supported.",
    685                        feature_name
    686                    );
    687                }
    688                let _ = writeln!(msg, "{}", see_docs());
    689                bail!(msg);
    690            }
    691        }
    692
    693        *slot = true;
    694
    695        Ok(())
    696    }
    697
    698    /// Gets the current activated features.
    699    pub fn activated(&self) -> &[String] {
    700        &self.activated
    701    }
    702
    703    /// Checks if the given feature is enabled.
    704    pub fn require(&self, feature: &Feature) -> CargoResult<()> {
    705        if feature.is_enabled(self) {
    706            return Ok(());
    707        }
    708        let feature_name = feature.name.replace("_", "-");
    709        let mut msg = format!(
    710            "feature `{}` is required\n\
    711             \n\
    712             The package requires the Cargo feature called `{}`, but \
    713             that feature is not stabilized in this version of Cargo ({}).\n\
    714            ",
    715            feature_name,
    716            feature_name,
    717            crate::version(),
    718        );
    719
    720        if self.nightly_features_allowed {
    721            if self.is_local {
    722                let _ = writeln!(
    723                    msg,
    724                    "Consider adding `cargo-features = [\"{}\"]` \
    725                     to the top of Cargo.toml (above the [package] table) \
    726                     to tell Cargo you are opting in to use this unstable feature.",
    727                    feature_name
    728                );
    729            } else {
    730                let _ = writeln!(msg, "Consider trying a more recent nightly release.");
    731            }
    732        } else {
    733            let _ = writeln!(
    734                msg,
    735                "Consider trying a newer version of Cargo \
    736                 (this may require the nightly release)."
    737            );
    738        }
    739        let _ = writeln!(
    740            msg,
    741            "See https://doc.rust-lang.org/nightly/cargo/{} for more information \
    742             about the status of this feature.",
    743            feature.docs
    744        );
    745
    746        bail!("{}", msg);
    747    }
    748
    749    /// Whether the given feature is allowed to use in this context.
    750    pub fn is_enabled(&self, feature: &Feature) -> bool {
    751        feature.is_enabled(self)
    752    }
    753}
    754
    755/// Generates `-Z` flags as fields of [`CliUnstable`].
    756///
    757/// See the [module-level documentation](self#-z-options) for details.
    758macro_rules! unstable_cli_options {
    759    (
    760        $(
    761            $(#[$meta:meta])?
    762            $element: ident: $ty: ty$( = ($help:literal))?,
    763        )*
    764    ) => {
    765        /// A parsed representation of all unstable flags that Cargo accepts.
    766        ///
    767        /// Cargo, like `rustc`, accepts a suite of `-Z` flags which are intended for
    768        /// gating unstable functionality to Cargo. These flags are only available on
    769        /// the nightly channel of Cargo.
    770        #[derive(Default, Debug, Deserialize)]
    771        #[serde(default, rename_all = "kebab-case")]
    772        pub struct CliUnstable {
    773            $(
    774                $(#[doc = $help])?
    775                $(#[$meta])?
    776                pub $element: $ty
    777            ),*
    778        }
    779        impl CliUnstable {
    780            /// Returns a list of `(<option-name>, <help-text>)`.
    781            pub fn help() -> Vec<(&'static str, Option<&'static str>)> {
    782                let fields = vec![$((stringify!($element), None$(.or(Some($help)))?)),*];
    783                fields
    784            }
    785        }
    786
    787        #[cfg(test)]
    788        mod test {
    789            #[test]
    790            fn ensure_sorted() {
    791                // This will be printed out if the fields are not sorted.
    792                let location = std::panic::Location::caller();
    793                println!(
    794                    "\nTo fix this test, sort the features inside the macro at {}:{}\n",
    795                    location.file(),
    796                    location.line()
    797                );
    798                let mut expected = vec![$(stringify!($element)),*];
    799                expected[2..].sort();
    800                let expected = format!("{:#?}", expected);
    801                let actual = format!("{:#?}", vec![$(stringify!($element)),*]);
    802                snapbox::assert_data_eq!(actual, expected);
    803            }
    804        }
    805    }
    806}
    807
    808unstable_cli_options!(
    809    // Permanently unstable features:
    810    allow_features: Option<AllowFeatures> = ("Allow *only* the listed unstable features"),
    811    print_im_a_teapot: bool,
    812
    813    // All other unstable features.
    814    // Please keep this list lexicographically ordered.
    815    advanced_env: bool,
    816    asymmetric_token: bool = ("Allows authenticating with asymmetric tokens"),
    817    avoid_dev_deps: bool = ("Avoid installing dev-dependencies if possible"),
    818    binary_dep_depinfo: bool = ("Track changes to dependency artifacts"),
    819    bindeps: bool = ("Allow Cargo packages to depend on bin, cdylib, and staticlib crates, and use the artifacts built by those crates"),
    820    build_dir: bool = ("Enable the `build.build-dir` option in .cargo/config.toml file"),
    821    #[serde(deserialize_with = "deserialize_comma_separated_list")]
    822    build_std: Option<Vec<String>>  = ("Enable Cargo to compile the standard library itself as part of a crate graph compilation"),
    823    #[serde(deserialize_with = "deserialize_comma_separated_list")]
    824    build_std_features: Option<Vec<String>>  = ("Configure features enabled for the standard library itself when building the standard library"),
    825    cargo_lints: bool = ("Enable the `[lints.cargo]` table"),
    826    checksum_freshness: bool = ("Use a checksum to determine if output is fresh rather than filesystem mtime"),
    827    codegen_backend: bool = ("Enable the `codegen-backend` option in profiles in .cargo/config.toml file"),
    828    config_include: bool = ("Enable the `include` key in config files"),
    829    direct_minimal_versions: bool = ("Resolve minimal dependency versions instead of maximum (direct dependencies only)"),
    830    dual_proc_macros: bool = ("Build proc-macros for both the host and the target"),
    831    feature_unification: bool = ("Enable new feature unification modes in workspaces"),
    832    features: Option<Vec<String>>,
    833    fix_edition: Option<FixEdition> = ("Permanently unstable edition migration helper"),
    834    gc: bool = ("Track cache usage and \"garbage collect\" unused files"),
    835    #[serde(deserialize_with = "deserialize_git_features")]
    836    git: Option<GitFeatures> = ("Enable support for shallow git fetch operations"),
    837    #[serde(deserialize_with = "deserialize_gitoxide_features")]
    838    gitoxide: Option<GitoxideFeatures> = ("Use gitoxide for the given git interactions, or all of them if no argument is given"),
    839    host_config: bool = ("Enable the `[host]` section in the .cargo/config.toml file"),
    840    minimal_versions: bool = ("Resolve minimal dependency versions instead of maximum"),
    841    msrv_policy: bool = ("Enable rust-version aware policy within cargo"),
    842    mtime_on_use: bool = ("Configure Cargo to update the mtime of used files"),
    843    next_lockfile_bump: bool,
    844    no_embed_metadata: bool = ("Avoid embedding metadata in library artifacts"),
    845    no_index_update: bool = ("Do not update the registry index even if the cache is outdated"),
    846    package_workspace: bool = ("Handle intra-workspace dependencies when packaging"),
    847    panic_abort_tests: bool = ("Enable support to run tests with -Cpanic=abort"),
    848    profile_hint_mostly_unused: bool = ("Enable the `hint-mostly-unused` setting in profiles to mark a crate as mostly unused."),
    849    profile_rustflags: bool = ("Enable the `rustflags` option in profiles in .cargo/config.toml file"),
    850    public_dependency: bool = ("Respect a dependency's `public` field in Cargo.toml to control public/private dependencies"),
    851    publish_timeout: bool = ("Enable the `publish.timeout` key in .cargo/config.toml file"),
    852    root_dir: Option<PathBuf> = ("Set the root directory relative to which paths are printed (defaults to workspace root)"),
    853    rustdoc_depinfo: bool = ("Use dep-info files in rustdoc rebuild detection"),
    854    rustdoc_map: bool = ("Allow passing external documentation mappings to rustdoc"),
    855    rustdoc_scrape_examples: bool = ("Allows Rustdoc to scrape code examples from reverse-dependencies"),
    856    sbom: bool = ("Enable the `sbom` option in build config in .cargo/config.toml file"),
    857    script: bool = ("Enable support for single-file, `.rs` packages"),
    858    separate_nightlies: bool,
    859    skip_rustdoc_fingerprint: bool,
    860    target_applies_to_host: bool = ("Enable the `target-applies-to-host` key in the .cargo/config.toml file"),
    861    trim_paths: bool = ("Enable the `trim-paths` option in profiles"),
    862    unstable_options: bool = ("Allow the usage of unstable options"),
    863    warnings: bool = ("Allow use of the build.warnings config key"),
    864);
    865
    866const STABILIZED_COMPILE_PROGRESS: &str = "The progress bar is now always \
    867    enabled when used on an interactive console.\n\
    868    See https://doc.rust-lang.org/cargo/reference/config.html#termprogresswhen \
    869    for information on controlling the progress bar.";
    870
    871const STABILIZED_OFFLINE: &str = "Offline mode is now available via the \
    872    --offline CLI option";
    873
    874const STABILIZED_CACHE_MESSAGES: &str = "Message caching is now always enabled.";
    875
    876const STABILIZED_INSTALL_UPGRADE: &str = "Packages are now always upgraded if \
    877    they appear out of date.\n\
    878    See https://doc.rust-lang.org/cargo/commands/cargo-install.html for more \
    879    information on how upgrading works.";
    880
    881const STABILIZED_CONFIG_PROFILE: &str = "See \
    882    https://doc.rust-lang.org/cargo/reference/config.html#profile for more \
    883    information about specifying profiles in config.";
    884
    885const STABILIZED_CRATE_VERSIONS: &str = "The crate version is now \
    886    automatically added to the documentation.";
    887
    888const STABILIZED_PACKAGE_FEATURES: &str = "Enhanced feature flag behavior is now \
    889    available in virtual workspaces, and `member/feature-name` syntax is also \
    890    always available. Other extensions require setting `resolver = \"2\"` in \
    891    Cargo.toml.\n\
    892    See https://doc.rust-lang.org/nightly/cargo/reference/features.html#resolver-version-2-command-line-flags \
    893    for more information.";
    894
    895const STABILIZED_FEATURES: &str = "The new feature resolver is now available \
    896    by specifying `resolver = \"2\"` in Cargo.toml.\n\
    897    See https://doc.rust-lang.org/nightly/cargo/reference/features.html#feature-resolver-version-2 \
    898    for more information.";
    899
    900const STABILIZED_EXTRA_LINK_ARG: &str = "Additional linker arguments are now \
    901    supported without passing this flag.";
    902
    903const STABILIZED_CONFIGURABLE_ENV: &str = "The [env] section is now always enabled.";
    904
    905const STABILIZED_PATCH_IN_CONFIG: &str = "The patch-in-config feature is now always enabled.";
    906
    907const STABILIZED_NAMED_PROFILES: &str = "The named-profiles feature is now always enabled.\n\
    908    See https://doc.rust-lang.org/nightly/cargo/reference/profiles.html#custom-profiles \
    909    for more information";
    910
    911const STABILIZED_DOCTEST_IN_WORKSPACE: &str =
    912    "The doctest-in-workspace feature is now always enabled.";
    913
    914const STABILIZED_FUTURE_INCOMPAT_REPORT: &str =
    915    "The future-incompat-report feature is now always enabled.";
    916
    917const STABILIZED_WEAK_DEP_FEATURES: &str = "Weak dependency features are now always available.";
    918
    919const STABILISED_NAMESPACED_FEATURES: &str = "Namespaced features are now always available.";
    920
    921const STABILIZED_TIMINGS: &str = "The -Ztimings option has been stabilized as --timings.";
    922
    923const STABILISED_MULTITARGET: &str = "Multiple `--target` options are now always available.";
    924
    925const STABILIZED_TERMINAL_WIDTH: &str =
    926    "The -Zterminal-width option is now always enabled for terminal output.";
    927
    928const STABILISED_SPARSE_REGISTRY: &str = "The sparse protocol is now the default for crates.io";
    929
    930const STABILIZED_CREDENTIAL_PROCESS: &str =
    931    "Authentication with a credential provider is always available.";
    932
    933const STABILIZED_REGISTRY_AUTH: &str =
    934    "Authenticated registries are available if a credential provider is configured.";
    935
    936const STABILIZED_LINTS: &str = "The `[lints]` table is now always available.";
    937
    938const STABILIZED_CHECK_CFG: &str =
    939    "Compile-time checking of conditional (a.k.a. `-Zcheck-cfg`) is now always enabled.";
    940
    941const STABILIZED_DOCTEST_XCOMPILE: &str = "Doctest cross-compiling is now always enabled.";
    942
    943fn deserialize_comma_separated_list<'de, D>(
    944    deserializer: D,
    945) -> Result<Option<Vec<String>>, D::Error>
    946where
    947    D: serde::Deserializer<'de>,
    948{
    949    let Some(list) = <Option<Vec<String>>>::deserialize(deserializer)? else {
    950        return Ok(None);
    951    };
    952    let v = list
    953        .iter()
    954        .flat_map(|s| s.split(','))
    955        .filter(|s| !s.is_empty())
    956        .map(String::from)
    957        .collect();
    958    Ok(Some(v))
    959}
    960
    961#[derive(Debug, Copy, Clone, Default, Deserialize, Ord, PartialOrd, Eq, PartialEq)]
    962#[serde(default)]
    963pub struct GitFeatures {
    964    /// When cloning the index, perform a shallow clone. Maintain shallowness upon subsequent fetches.
    965    pub shallow_index: bool,
    966    /// When cloning git dependencies, perform a shallow clone and maintain shallowness on subsequent fetches.
    967    pub shallow_deps: bool,
    968}
    969
    970impl GitFeatures {
    971    pub fn all() -> Self {
    972        GitFeatures {
    973            shallow_index: true,
    974            shallow_deps: true,
    975        }
    976    }
    977
    978    fn expecting() -> String {
    979        let fields = ["`shallow-index`", "`shallow-deps`"];
    980        format!(
    981            "unstable 'git' only takes {} as valid inputs",
    982            fields.join(" and ")
    983        )
    984    }
    985}
    986
    987fn deserialize_git_features<'de, D>(deserializer: D) -> Result<Option<GitFeatures>, D::Error>
    988where
    989    D: serde::de::Deserializer<'de>,
    990{
    991    struct GitFeaturesVisitor;
    992
    993    impl<'de> serde::de::Visitor<'de> for GitFeaturesVisitor {
    994        type Value = Option<GitFeatures>;
    995
    996        fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    997            formatter.write_str(&GitFeatures::expecting())
    998        }
    999
    1000        fn visit_bool<E>(self, v: bool) -> Result<Self::Value, E>
    1001        where
    1002            E: serde::de::Error,
    1003        {
    1004            if v {
    1005                Ok(Some(GitFeatures::all()))
    1006            } else {
    1007                Ok(None)
    1008            }
    1009        }
    1010
    1011        fn visit_str<E>(self, s: &str) -> Result<Self::Value, E>
    1012        where
    1013            E: serde::de::Error,
    1014        {
    1015            Ok(parse_git(s.split(",")).map_err(serde::de::Error::custom)?)
    1016        }
    1017
    1018        fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    1019        where
    1020            D: serde::de::Deserializer<'de>,
    1021        {
    1022            let git = GitFeatures::deserialize(deserializer)?;
    1023            Ok(Some(git))
    1024        }
    1025
    1026        fn visit_map<V>(self, map: V) -> Result<Self::Value, V::Error>
    1027        where
    1028            V: serde::de::MapAccess<'de>,
    1029        {
    1030            let mvd = serde::de::value::MapAccessDeserializer::new(map);
    1031            Ok(Some(GitFeatures::deserialize(mvd)?))
    1032        }
    1033    }
    1034
    1035    deserializer.deserialize_any(GitFeaturesVisitor)
    1036}
    1037
    1038fn parse_git(it: impl Iterator<Item = impl AsRef<str>>) -> CargoResult<Option<GitFeatures>> {
    1039    let mut out = GitFeatures::default();
    1040    let GitFeatures {
    1041        shallow_index,
    1042        shallow_deps,
    1043    } = &mut out;
    1044
    1045    for e in it {
    1046        match e.as_ref() {
    1047            "shallow-index" => *shallow_index = true,
    1048            "shallow-deps" => *shallow_deps = true,
    1049            _ => {
    1050                bail!(GitFeatures::expecting())
    1051            }
    1052        }
    1053    }
    1054    Ok(Some(out))
    1055}
    1056
    1057#[derive(Debug, Copy, Clone, Default, Deserialize, Ord, PartialOrd, Eq, PartialEq)]
    1058#[serde(default)]
    1059pub struct GitoxideFeatures {
    1060    /// All fetches are done with `gitoxide`, which includes git dependencies as well as the crates index.
    1061    pub fetch: bool,
    1062    /// Checkout git dependencies using `gitoxide` (submodules are still handled by git2 ATM, and filters
    1063    /// like linefeed conversions are unsupported).
    1064    pub checkout: bool,
    1065    /// A feature flag which doesn't have any meaning except for preventing
    1066    /// `__CARGO_USE_GITOXIDE_INSTEAD_OF_GIT2=1` builds to enable all safe `gitoxide` features.
    1067    /// That way, `gitoxide` isn't actually used even though it's enabled.
    1068    pub internal_use_git2: bool,
    1069}
    1070
    1071impl GitoxideFeatures {
    1072    pub fn all() -> Self {
    1073        GitoxideFeatures {
    1074            fetch: true,
    1075            checkout: true,
    1076            internal_use_git2: false,
    1077        }
    1078    }
    1079
    1080    /// Features we deem safe for everyday use - typically true when all tests pass with them
    1081    /// AND they are backwards compatible.
    1082    fn safe() -> Self {
    1083        GitoxideFeatures {
    1084            fetch: true,
    1085            checkout: true,
    1086            internal_use_git2: false,
    1087        }
    1088    }
    1089
    1090    fn expecting() -> String {
    1091        let fields = ["`fetch`", "`checkout`", "`internal-use-git2`"];
    1092        format!(
    1093            "unstable 'gitoxide' only takes {} as valid inputs, for shallow fetches see `-Zgit=shallow-index,shallow-deps`",
    1094            fields.join(" and ")
    1095        )
    1096    }
    1097}
    1098
    1099fn deserialize_gitoxide_features<'de, D>(
    1100    deserializer: D,
    1101) -> Result<Option<GitoxideFeatures>, D::Error>
    1102where
    1103    D: serde::de::Deserializer<'de>,
    1104{
    1105    struct GitoxideFeaturesVisitor;
    1106
    1107    impl<'de> serde::de::Visitor<'de> for GitoxideFeaturesVisitor {
    1108        type Value = Option<GitoxideFeatures>;
    1109
    1110        fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
    1111            formatter.write_str(&GitoxideFeatures::expecting())
    1112        }
    1113
    1114        fn visit_str<E>(self, s: &str) -> Result<Self::Value, E>
    1115        where
    1116            E: serde::de::Error,
    1117        {
    1118            Ok(parse_gitoxide(s.split(",")).map_err(serde::de::Error::custom)?)
    1119        }
    1120
    1121        fn visit_bool<E>(self, v: bool) -> Result<Self::Value, E>
    1122        where
    1123            E: serde::de::Error,
    1124        {
    1125            if v {
    1126                Ok(Some(GitoxideFeatures::all()))
    1127            } else {
    1128                Ok(None)
    1129            }
    1130        }
    1131
    1132        fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
    1133        where
    1134            D: serde::de::Deserializer<'de>,
    1135        {
    1136            let gitoxide = GitoxideFeatures::deserialize(deserializer)?;
    1137            Ok(Some(gitoxide))
    1138        }
    1139
    1140        fn visit_map<V>(self, map: V) -> Result<Self::Value, V::Error>
    1141        where
    1142            V: serde::de::MapAccess<'de>,
    1143        {
    1144            let mvd = serde::de::value::MapAccessDeserializer::new(map);
    1145            Ok(Some(GitoxideFeatures::deserialize(mvd)?))
    1146        }
    1147    }
    1148
    1149    deserializer.deserialize_any(GitoxideFeaturesVisitor)
    1150}
    1151
    1152fn parse_gitoxide(
    1153    it: impl Iterator<Item = impl AsRef<str>>,
    1154) -> CargoResult<Option<GitoxideFeatures>> {
    1155    let mut out = GitoxideFeatures::default();
    1156    let GitoxideFeatures {
    1157        fetch,
    1158        checkout,
    1159        internal_use_git2,
    1160    } = &mut out;
    1161
    1162    for e in it {
    1163        match e.as_ref() {
    1164            "fetch" => *fetch = true,
    1165            "checkout" => *checkout = true,
    1166            "internal-use-git2" => *internal_use_git2 = true,
    1167            _ => {
    1168                bail!(GitoxideFeatures::expecting())
    1169            }
    1170        }
    1171    }
    1172    Ok(Some(out))
    1173}
    1174
    1175impl CliUnstable {
    1176    /// Parses `-Z` flags from the command line, and returns messages that warn
    1177    /// if any flag has alreardy been stabilized.
    1178    pub fn parse(
    1179        &mut self,
    1180        flags: &[String],
    1181        nightly_features_allowed: bool,
    1182    ) -> CargoResult<Vec<String>> {
    1183        if !flags.is_empty() && !nightly_features_allowed {
    1184            bail!(
    1185                "the `-Z` flag is only accepted on the nightly channel of Cargo, \
    1186                 but this is the `{}` channel\n\
    1187                 {}",
    1188                channel(),
    1189                SEE_CHANNELS
    1190            );
    1191        }
    1192        let mut warnings = Vec::new();
    1193        // We read flags twice, first to get allowed-features (if specified),
    1194        // and then to read the remaining unstable flags.
    1195        for flag in flags {
    1196            if flag.starts_with("allow-features=") {
    1197                self.add(flag, &mut warnings)?;
    1198            }
    1199        }
    1200        for flag in flags {
    1201            self.add(flag, &mut warnings)?;
    1202        }
    1203
    1204        if self.gitoxide.is_none() && cargo_use_gitoxide_instead_of_git2() {
    1205            self.gitoxide = GitoxideFeatures::safe().into();
    1206        }
    1207        Ok(warnings)
    1208    }
    1209
    1210    fn add(&mut self, flag: &str, warnings: &mut Vec<String>) -> CargoResult<()> {
    1211        let mut parts = flag.splitn(2, '=');
    1212        let k = parts.next().unwrap();
    1213        let v = parts.next();
    1214
    1215        fn parse_bool(key: &str, value: Option<&str>) -> CargoResult<bool> {
    1216            match value {
    1217                None | Some("yes") => Ok(true),
    1218                Some("no") => Ok(false),
    1219                Some(s) => bail!("flag -Z{} expected `no` or `yes`, found: `{}`", key, s),
    1220            }
    1221        }
    1222
    1223        /// Parse a comma-separated list
    1224        fn parse_list(value: Option<&str>) -> Vec<String> {
    1225            match value {
    1226                None => Vec::new(),
    1227                Some("") => Vec::new(),
    1228                Some(v) => v.split(',').map(|s| s.to_string()).collect(),
    1229            }
    1230        }
    1231
    1232        // Asserts that there is no argument to the flag.
    1233        fn parse_empty(key: &str, value: Option<&str>) -> CargoResult<bool> {
    1234            if let Some(v) = value {
    1235                bail!("flag -Z{} does not take a value, found: `{}`", key, v);
    1236            }
    1237            Ok(true)
    1238        }
    1239
    1240        let mut stabilized_warn = |key: &str, version: &str, message: &str| {
    1241            warnings.push(format!(
    1242                "flag `-Z {}` has been stabilized in the {} release, \
    1243                 and is no longer necessary\n{}",
    1244                key,
    1245                version,
    1246                indented_lines(message)
    1247            ));
    1248        };
    1249
    1250        // Use this if the behavior now requires another mechanism to enable.
    1251        let stabilized_err = |key: &str, version: &str, message: &str| {
    1252            Err(anyhow::format_err!(
    1253                "flag `-Z {}` has been stabilized in the {} release\n{}",
    1254                key,
    1255                version,
    1256                indented_lines(message)
    1257            ))
    1258        };
    1259
    1260        if let Some(allowed) = &self.allow_features {
    1261            if k != "allow-features" && !allowed.contains(k) {
    1262                bail!(
    1263                    "the feature `{}` is not in the list of allowed features: [{}]",
    1264                    k,
    1265                    itertools::join(allowed, ", ")
    1266                );
    1267            }
    1268        }
    1269
    1270        match k {
    1271            // Permanently unstable features
    1272            // Sorted alphabetically:
    1273            "allow-features" => self.allow_features = Some(parse_list(v).into_iter().collect()),
    1274            "print-im-a-teapot" => self.print_im_a_teapot = parse_bool(k, v)?,
    1275
    1276            // Stabilized features
    1277            // Sorted by version, then alphabetically:
    1278            "compile-progress" => stabilized_warn(k, "1.30", STABILIZED_COMPILE_PROGRESS),
    1279            "offline" => stabilized_err(k, "1.36", STABILIZED_OFFLINE)?,
    1280            "cache-messages" => stabilized_warn(k, "1.40", STABILIZED_CACHE_MESSAGES),
    1281            "install-upgrade" => stabilized_warn(k, "1.41", STABILIZED_INSTALL_UPGRADE),
    1282            "config-profile" => stabilized_warn(k, "1.43", STABILIZED_CONFIG_PROFILE),
    1283            "crate-versions" => stabilized_warn(k, "1.47", STABILIZED_CRATE_VERSIONS),
    1284            "features" => {
    1285                // `-Z features` has been stabilized since 1.51,
    1286                // but `-Z features=compare` is still allowed for convenience
    1287                // to validate that the feature resolver resolves features
    1288                // in the same way as the dependency resolver,
    1289                // until we feel confident to remove entirely.
    1290                //
    1291                // See rust-lang/cargo#11168
    1292                let feats = parse_list(v);
    1293                let stab_is_not_empty = feats.iter().any(|feat| {
    1294                    matches!(
    1295                        feat.as_str(),
    1296                        "build_dep" | "host_dep" | "dev_dep" | "itarget" | "all"
    1297                    )
    1298                });
    1299                if stab_is_not_empty || feats.is_empty() {
    1300                    // Make this stabilized_err once -Zfeature support is removed.
    1301                    stabilized_warn(k, "1.51", STABILIZED_FEATURES);
    1302                }
    1303                self.features = Some(feats);
    1304            }
    1305            "package-features" => stabilized_warn(k, "1.51", STABILIZED_PACKAGE_FEATURES),
    1306            "configurable-env" => stabilized_warn(k, "1.56", STABILIZED_CONFIGURABLE_ENV),
    1307            "extra-link-arg" => stabilized_warn(k, "1.56", STABILIZED_EXTRA_LINK_ARG),
    1308            "patch-in-config" => stabilized_warn(k, "1.56", STABILIZED_PATCH_IN_CONFIG),
    1309            "named-profiles" => stabilized_warn(k, "1.57", STABILIZED_NAMED_PROFILES),
    1310            "future-incompat-report" => {
    1311                stabilized_warn(k, "1.59.0", STABILIZED_FUTURE_INCOMPAT_REPORT)
    1312            }
    1313            "namespaced-features" => stabilized_warn(k, "1.60", STABILISED_NAMESPACED_FEATURES),
    1314            "timings" => stabilized_warn(k, "1.60", STABILIZED_TIMINGS),
    1315            "weak-dep-features" => stabilized_warn(k, "1.60", STABILIZED_WEAK_DEP_FEATURES),
    1316            "multitarget" => stabilized_warn(k, "1.64", STABILISED_MULTITARGET),
    1317            "sparse-registry" => stabilized_warn(k, "1.68", STABILISED_SPARSE_REGISTRY),
    1318            "terminal-width" => stabilized_warn(k, "1.68", STABILIZED_TERMINAL_WIDTH),
    1319            "doctest-in-workspace" => stabilized_warn(k, "1.72", STABILIZED_DOCTEST_IN_WORKSPACE),
    1320            "credential-process" => stabilized_warn(k, "1.74", STABILIZED_CREDENTIAL_PROCESS),
    1321            "lints" => stabilized_warn(k, "1.74", STABILIZED_LINTS),
    1322            "registry-auth" => stabilized_warn(k, "1.74", STABILIZED_REGISTRY_AUTH),
    1323            "check-cfg" => stabilized_warn(k, "1.80", STABILIZED_CHECK_CFG),
    1324
    1325            // Unstable features
    1326            // Sorted alphabetically:
    1327            "advanced-env" => self.advanced_env = parse_empty(k, v)?,
    1328            "asymmetric-token" => self.asymmetric_token = parse_empty(k, v)?,
    1329            "avoid-dev-deps" => self.avoid_dev_deps = parse_empty(k, v)?,
    1330            "binary-dep-depinfo" => self.binary_dep_depinfo = parse_empty(k, v)?,
    1331            "bindeps" => self.bindeps = parse_empty(k, v)?,
    1332            "build-dir" => self.build_dir = parse_empty(k, v)?,
    1333            "build-std" => self.build_std = Some(parse_list(v)),
    1334            "build-std-features" => self.build_std_features = Some(parse_list(v)),
    1335            "cargo-lints" => self.cargo_lints = parse_empty(k, v)?,
    1336            "codegen-backend" => self.codegen_backend = parse_empty(k, v)?,
    1337            "config-include" => self.config_include = parse_empty(k, v)?,
    1338            "direct-minimal-versions" => self.direct_minimal_versions = parse_empty(k, v)?,
    1339            "doctest-xcompile" => stabilized_warn(k, "1.89", STABILIZED_DOCTEST_XCOMPILE),
    1340            "dual-proc-macros" => self.dual_proc_macros = parse_empty(k, v)?,
    1341            "feature-unification" => self.feature_unification = parse_empty(k, v)?,
    1342            "fix-edition" => {
    1343                let fe = v
    1344                    .ok_or_else(|| anyhow::anyhow!("-Zfix-edition expected a value"))?
    1345                    .parse()?;
    1346                self.fix_edition = Some(fe);
    1347            }
    1348            "gc" => self.gc = parse_empty(k, v)?,
    1349            "git" => {
    1350                self.git =
    1351                    v.map_or_else(|| Ok(Some(GitFeatures::all())), |v| parse_git(v.split(',')))?
    1352            }
    1353            "gitoxide" => {
    1354                self.gitoxide = v.map_or_else(
    1355                    || Ok(Some(GitoxideFeatures::all())),
    1356                    |v| parse_gitoxide(v.split(',')),
    1357                )?
    1358            }
    1359            "host-config" => self.host_config = parse_empty(k, v)?,
    1360            "next-lockfile-bump" => self.next_lockfile_bump = parse_empty(k, v)?,
    1361            "minimal-versions" => self.minimal_versions = parse_empty(k, v)?,
    1362            "msrv-policy" => self.msrv_policy = parse_empty(k, v)?,
    1363            // can also be set in .cargo/config or with and ENV
    1364            "mtime-on-use" => self.mtime_on_use = parse_empty(k, v)?,
    1365            "no-embed-metadata" => self.no_embed_metadata = parse_empty(k, v)?,
    1366            "no-index-update" => self.no_index_update = parse_empty(k, v)?,
    1367            "package-workspace" => self.package_workspace = parse_empty(k, v)?,
    1368            "panic-abort-tests" => self.panic_abort_tests = parse_empty(k, v)?,
    1369            "public-dependency" => self.public_dependency = parse_empty(k, v)?,
    1370            "profile-hint-mostly-unused" => self.profile_hint_mostly_unused = parse_empty(k, v)?,
    1371            "profile-rustflags" => self.profile_rustflags = parse_empty(k, v)?,
    1372            "trim-paths" => self.trim_paths = parse_empty(k, v)?,
    1373            "publish-timeout" => self.publish_timeout = parse_empty(k, v)?,
    1374            "root-dir" => self.root_dir = v.map(|v| v.into()),
    1375            "rustdoc-depinfo" => self.rustdoc_depinfo = parse_empty(k, v)?,
    1376            "rustdoc-map" => self.rustdoc_map = parse_empty(k, v)?,
    1377            "rustdoc-scrape-examples" => self.rustdoc_scrape_examples = parse_empty(k, v)?,
    1378            "sbom" => self.sbom = parse_empty(k, v)?,
    1379            "separate-nightlies" => self.separate_nightlies = parse_empty(k, v)?,
    1380            "checksum-freshness" => self.checksum_freshness = parse_empty(k, v)?,
    1381            "skip-rustdoc-fingerprint" => self.skip_rustdoc_fingerprint = parse_empty(k, v)?,
    1382            "script" => self.script = parse_empty(k, v)?,
    1383            "target-applies-to-host" => self.target_applies_to_host = parse_empty(k, v)?,
    1384            "unstable-options" => self.unstable_options = parse_empty(k, v)?,
    1385            "warnings" => self.warnings = parse_empty(k, v)?,
    1386            _ => bail!(
    1387                "\
    1388            unknown `-Z` flag specified: {k}\n\n\
    1389            For available unstable features, see \
    1390            https://doc.rust-lang.org/nightly/cargo/reference/unstable.html\n\
    1391            If you intended to use an unstable rustc feature, try setting `RUSTFLAGS=\"-Z{k}\"`"
    1392            ),
    1393        }
    1394
    1395        Ok(())
    1396    }
    1397
    1398    /// Generates an error if `-Z unstable-options` was not used for a new,
    1399    /// unstable command-line flag.
    1400    pub fn fail_if_stable_opt(&self, flag: &str, issue: u32) -> CargoResult<()> {
    1401        self.fail_if_stable_opt_custom_z(flag, issue, "unstable-options", self.unstable_options)
    1402    }
    1403
    1404    pub fn fail_if_stable_opt_custom_z(
    1405        &self,
    1406        flag: &str,
    1407        issue: u32,
    1408        z_name: &str,
    1409        enabled: bool,
    1410    ) -> CargoResult<()> {
    1411        if !enabled {
    1412            let see = format!(
    1413                "See https://github.com/rust-lang/cargo/issues/{issue} for more \
    1414                 information about the `{flag}` flag."
    1415            );
    1416            // NOTE: a `config` isn't available here, check the channel directly
    1417            let channel = channel();
    1418            if channel == "nightly" || channel == "dev" {
    1419                bail!(
    1420                    "the `{flag}` flag is unstable, pass `-Z {z_name}` to enable it\n\
    1421                     {see}"
    1422                );
    1423            } else {
    1424                bail!(
    1425                    "the `{flag}` flag is unstable, and only available on the nightly channel \
    1426                     of Cargo, but this is the `{channel}` channel\n\
    1427                     {SEE_CHANNELS}\n\
    1428                     {see}"
    1429                );
    1430            }
    1431        }
    1432        Ok(())
    1433    }
    1434
    1435    /// Generates an error if `-Z unstable-options` was not used for a new,
    1436    /// unstable subcommand.
    1437    pub fn fail_if_stable_command(
    1438        &self,
    1439        gctx: &GlobalContext,
    1440        command: &str,
    1441        issue: u32,
    1442        z_name: &str,
    1443        enabled: bool,
    1444    ) -> CargoResult<()> {
    1445        if enabled {
    1446            return Ok(());
    1447        }
    1448        let see = format!(
    1449            "See https://github.com/rust-lang/cargo/issues/{} for more \
    1450            information about the `cargo {}` command.",
    1451            issue, command
    1452        );
    1453        if gctx.nightly_features_allowed {
    1454            bail!(
    1455                "the `cargo {command}` command is unstable, pass `-Z {z_name}` \
    1456                 to enable it\n\
    1457                 {see}",
    1458            );
    1459        } else {
    1460            bail!(
    1461                "the `cargo {}` command is unstable, and only available on the \
    1462                 nightly channel of Cargo, but this is the `{}` channel\n\
    1463                 {}\n\
    1464                 {}",
    1465                command,
    1466                channel(),
    1467                SEE_CHANNELS,
    1468                see
    1469            );
    1470        }
    1471    }
    1472}
    1473
    1474/// Returns the current release channel ("stable", "beta", "nightly", "dev").
    1475pub fn channel() -> String {
    1476    // ALLOWED: For testing cargo itself only.
    1477    #[allow(clippy::disallowed_methods)]
    1478    if let Ok(override_channel) = env::var("__CARGO_TEST_CHANNEL_OVERRIDE_DO_NOT_USE_THIS") {
    1479        return override_channel;
    1480    }
    1481    // ALLOWED: the process of rustc bootstrapping reads this through
    1482    // `std::env`. We should make the behavior consistent. Also, we
    1483    // don't advertise this for bypassing nightly.
    1484    #[allow(clippy::disallowed_methods)]
    1485    if let Ok(staging) = env::var("RUSTC_BOOTSTRAP") {
    1486        if staging == "1" {
    1487            return "dev".to_string();
    1488        }
    1489    }
    1490    // Debian: always return dev channel
    1491    String::from("dev")
    1492}
    1493
    1494/// Only for testing and developing. See ["Running with gitoxide as default git backend in tests"][1].
    1495///
    1496/// [1]: https://doc.crates.io/contrib/tests/running.html#running-with-gitoxide-as-default-git-backend-in-tests
    1497// ALLOWED: For testing cargo itself only.
    1498#[allow(clippy::disallowed_methods)]
    1499fn cargo_use_gitoxide_instead_of_git2() -> bool {
    1500    std::env::var_os("__CARGO_USE_GITOXIDE_INSTEAD_OF_GIT2").map_or(false, |value| value == "1")
    1501}
    1502
    1503/// Generate a link to Cargo documentation for the current release channel
    1504/// `path` is the URL component after `https://doc.rust-lang.org/{channel}/cargo/`
    1505pub fn cargo_docs_link(path: &str) -> String {
    1506    let url_channel = match channel().as_str() {
    1507        "dev" | "nightly" => "nightly/",
    1508        "beta" => "beta/",
    1509        _ => "",
    1510    };
    1511    format!("https://doc.rust-lang.org/{url_channel}cargo/{path}")
    1512}