From 39c3173619ecb5878d064e8bdc0b134efe59c25e Mon Sep 17 00:00:00 2001 From: Jon Gjengset Date: Mon, 13 Jun 2022 21:52:18 +0000 Subject: [PATCH] Stabilize --config FCP https://github.com/rust-lang/cargo/issues/7722#issuecomment-1114369809 Closes #7722. --- src/cargo/util/config/mod.rs | 1 - src/doc/src/reference/config.md | 40 +++++++++++++++++++++++++++ src/doc/src/reference/unstable.md | 41 ++++----------------------- tests/testsuite/config.rs | 4 --- tests/testsuite/config_cli.rs | 46 +++++++++++++++++++------------ tests/testsuite/config_include.rs | 34 +---------------------- 6 files changed, 75 insertions(+), 91 deletions(-) diff --git a/src/cargo/util/config/mod.rs b/src/cargo/util/config/mod.rs index 09e78b6d16c..83eff3cbf57 100644 --- a/src/cargo/util/config/mod.rs +++ b/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()?; } diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index c2d8e665ef9..f4749457e7a 100644 --- a/src/doc/src/reference/config.md +++ b/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 diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index bbdc15719b3..6ac1d738b2e 100644 --- a/src/doc/src/reference/unstable.md +++ b/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. diff --git a/tests/testsuite/config.rs b/tests/testsuite/config.rs index 4353ffcecd2..601d58af6ae 100644 --- a/tests/testsuite/config.rs +++ b/tests/testsuite/config.rs @@ -55,10 +55,6 @@ impl ConfigBuilder { /// Passes a `--config` flag. pub fn config_arg(&mut self, arg: impl Into) -> &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 } diff --git a/tests/testsuite/config_cli.rs b/tests/testsuite/config_cli.rs index dd08e13d103..e4c593443e7 100644 --- a/tests/testsuite/config_cli.rs +++ b/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::("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 `=` +", + ); +} diff --git a/tests/testsuite/config_include.rs b/tests/testsuite/config_include.rs index ac210b777cb..464467aa6eb 100644 --- a/tests/testsuite/config_include.rs +++ b/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::("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 `=` -", - ); -}