Stabilize --config

FCP
#7722 (comment)

Closes #7722.

Author: Jon Gjengset

src/cargo/util/config/mod.rs

@@ -892,7 +892,6 @@ impl Config {
             self.unstable_flags_cli = Some(unstable_flags.to_vec());
         }
         if !cli_config.is_empty() {
-            self.unstable_flags.fail_if_stable_opt("--config", 6699)?;
             self.cli_config = Some(cli_config.iter().map(|s| s.to_string()).collect());
             self.merge_cli_args()?;
         }

src/doc/src/reference/config.md

@@ -195,6 +195,46 @@ support environment variables.
 In addition to the system above, Cargo recognizes a few other specific
 [environment variables][env].
 
+### Command-line overrides
+
+Cargo also accepts arbitrary configuration overrides through the
+`--config` command-line option. The argument should be in TOML syntax of
+`KEY=VALUE`:
+
+```console
+cargo --config net.git-fetch-with-cli=true fetch
+```
+
+The `--config` option may be specified multiple times, in which case the
+values are merged in left-to-right order, using the same merging logic
+that is used when multiple configuration files apply. Configuration
+values specified this way take precedence over environment variables,
+which take precedence over configuration files.
+
+Some examples of what it looks like using Bourne shell syntax:
+
+```console
+# Most shells will require escaping.
+cargo --config http.proxy=\"http://example.com\" …
+
+# Spaces may be used.
+cargo --config "net.git-fetch-with-cli = true" …
+
+# TOML array example. Single quotes make it easier to read and write.
+cargo --config 'build.rustdocflags = ["--html-in-header", "header.html"]' …
+
+# Example of a complex TOML key.
+cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.runner = 'my-runner'" …
+
+# Example of overriding a profile setting.
+cargo --config profile.dev.package.image.opt-level=3 …
+```
+
+The `--config` option can also be used to pass paths to extra
+configuration files that Cargo should use for a specific invocation.
+Options from configuration files loaded this way follow the same
+precedence rules as other options specified directly with `--config`.
+
 ### Config-relative paths
 
 Paths in config files may be absolute, relative, or a bare name without any

src/doc/src/reference/unstable.md

@@ -96,7 +96,6 @@ Each new feature described below should explain how to use it.
     * [unit-graph](#unit-graph) — Emits JSON for Cargo's internal graph structure.
     * [`cargo rustc --print`](#rustc---print) — Calls rustc with `--print` to display information from rustc.
 * Configuration
-    * [config-cli](#config-cli) — Adds the ability to pass configuration options on the command-line.
     * [config-include](#config-include) — Adds the ability for config files to include other files.
     * [`cargo config`](#cargo-config) — Adds a new subcommand for viewing config files.
 * Registries
@@ -475,40 +474,6 @@ The `-Z unstable-options` command-line option must be used in order to use
 cargo check --keep-going -Z unstable-options
 ```
 
-### config-cli
-* Tracking Issue: [#7722](https://github.com/rust-lang/cargo/issues/7722)
-
-The `--config` CLI option allows arbitrary config values to be passed
-in via the command-line. The argument should be in TOML syntax of KEY=VALUE:
-
-```console
-cargo +nightly -Zunstable-options --config net.git-fetch-with-cli=true fetch
-```
-
-The `--config` option may be specified multiple times, in which case the
-values are merged in left-to-right order, using the same merging logic that
-multiple config files use. CLI values take precedence over environment
-variables, which take precedence over config files.
-
-Some examples of what it looks like using Bourne shell syntax:
-
-```console
-# Most shells will require escaping.
-cargo --config http.proxy=\"http://example.com\" …
-
-# Spaces may be used.
-cargo --config "net.git-fetch-with-cli = true" …
-
-# TOML array example. Single quotes make it easier to read and write.
-cargo --config 'build.rustdocflags = ["--html-in-header", "header.html"]' …
-
-# Example of a complex TOML key.
-cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.runner = 'my-runner'" …
-
-# Example of overriding a profile setting.
-cargo --config profile.dev.package.image.opt-level=3 …
-```
-
 ### config-include
 * Tracking Issue: [#7723](https://github.com/rust-lang/cargo/issues/7723)
 
@@ -1598,3 +1563,9 @@ See the [Features chapter](features.md#dependency-features) for more information
 The `-Ztimings` option has been stabilized as `--timings` in the 1.60 release.
 (`--timings=html` and the machine-readable `--timings=json` output remain
 unstable and require `-Zunstable-options`.)
+
+### config-cli
+
+The `--config` CLI option has been stabilized in the 1.63 release. See
+the [config documentation](config.html#command-line-overrides) for more
+information.

tests/testsuite/config.rs

@@ -55,10 +55,6 @@ impl ConfigBuilder {
 
     /// Passes a `--config` flag.
     pub fn config_arg(&mut self, arg: impl Into<String>) -> &mut Self {
-        if !self.unstable.iter().any(|s| s == "unstable-options") {
-            // --config is current unstable
-            self.unstable_flag("unstable-options");
-        }
         self.config_args.push(arg.into());
         self
     }

tests/testsuite/config_cli.rs

@@ -2,26 +2,9 @@
 
 use super::config::{assert_error, assert_match, read_output, write_config, ConfigBuilder};
 use cargo::util::config::Definition;
-use cargo_test_support::{paths, project};
+use cargo_test_support::paths;
 use std::{collections::HashMap, fs};
 
-#[cargo_test]
-fn config_gated() {
-    // Requires -Zunstable-options
-    let p = project().file("src/lib.rs", "").build();
-
-    p.cargo("build --config --config build.jobs=1")
-        .with_status(101)
-        .with_stderr(
-            "\
-[ERROR] the `--config` flag is unstable, [..]
-See [..]
-See [..]
-",
-        )
-        .run();
-}
-
 #[cargo_test]
 fn basic() {
     // Simple example.
@@ -472,3 +455,30 @@ Caused by:
   expected string, but found array",
     );
 }
+
+#[cargo_test]
+fn cli_path() {
+    // --config path_to_file
+    fs::write(paths::root().join("myconfig.toml"), "key = 123").unwrap();
+    let config = ConfigBuilder::new()
+        .cwd(paths::root())
+        .config_arg("myconfig.toml")
+        .build();
+    assert_eq!(config.get::<u32>("key").unwrap(), 123);
+
+    let config = ConfigBuilder::new().config_arg("missing.toml").build_err();
+    assert_error(
+        config.unwrap_err(),
+        "\
+failed to parse value from --config argument `missing.toml` as a dotted key expression
+
+Caused by:
+  TOML parse error at line 1, column 13
+  |
+1 | missing.toml
+  |             ^
+Unexpected end of input
+Expected `.` or `=`
+",
+    );
+}

tests/testsuite/config_include.rs

@@ -1,8 +1,7 @@
 //! Tests for `include` config field.
 
 use super::config::{assert_error, write_config, write_config_at, ConfigBuilder};
-use cargo_test_support::{no_such_file_err_msg, paths, project};
-use std::fs;
+use cargo_test_support::{no_such_file_err_msg, project};
 
 #[cargo_test]
 fn gated() {
@@ -255,34 +254,3 @@ Caused by:
   expected array, but found string",
     );
 }
-
-#[cargo_test]
-fn cli_path() {
-    // --config path_to_file
-    fs::write(paths::root().join("myconfig.toml"), "key = 123").unwrap();
-    let config = ConfigBuilder::new()
-        .cwd(paths::root())
-        .unstable_flag("config-include")
-        .config_arg("myconfig.toml")
-        .build();
-    assert_eq!(config.get::<u32>("key").unwrap(), 123);
-
-    let config = ConfigBuilder::new()
-        .unstable_flag("config-include")
-        .config_arg("missing.toml")
-        .build_err();
-    assert_error(
-        config.unwrap_err(),
-        "\
-failed to parse value from --config argument `missing.toml` as a dotted key expression
-
-Caused by:
-  TOML parse error at line 1, column 13
-  |
-1 | missing.toml
-  |             ^
-Unexpected end of input
-Expected `.` or `=`
-",
-    );
-}