diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index 36bb8414296..82b4ce78356 100644 --- a/src/cargo/core/features.rs +++ b/src/cargo/core/features.rs @@ -856,7 +856,6 @@ unstable_cli_options!( cargo_lints: bool = ("Enable the `[lints.cargo]` table"), checksum_freshness: bool = ("Use a checksum to determine if output is fresh rather than filesystem mtime"), codegen_backend: bool = ("Enable the `codegen-backend` option in profiles in .cargo/config.toml file"), - config_include: bool = ("Enable the `include` key in config files"), direct_minimal_versions: bool = ("Resolve minimal dependency versions instead of maximum (direct dependencies only)"), dual_proc_macros: bool = ("Build proc-macros for both the host and the target"), feature_unification: bool = ("Enable new feature unification modes in workspaces"), @@ -979,6 +978,8 @@ const STABILIZED_PACKAGE_WORKSPACE: &str = const STABILIZED_BUILD_DIR: &str = "build.build-dir is now always enabled."; +const STABILIZED_CONFIG_INCLUDE: &str = "The `include` config key is now always available"; + fn deserialize_comma_separated_list<'de, D>( deserializer: D, ) -> Result>, D::Error> @@ -1363,6 +1364,7 @@ impl CliUnstable { "doctest-xcompile" => stabilized_warn(k, "1.89", STABILIZED_DOCTEST_XCOMPILE), "package-workspace" => stabilized_warn(k, "1.89", STABILIZED_PACKAGE_WORKSPACE), "build-dir" => stabilized_warn(k, "1.91", STABILIZED_BUILD_DIR), + "config-include" => stabilized_warn(k, "1.93", STABILIZED_CONFIG_INCLUDE), // Unstable features // Sorted alphabetically: @@ -1377,7 +1379,6 @@ impl CliUnstable { "build-std-features" => self.build_std_features = Some(parse_list(v)), "cargo-lints" => self.cargo_lints = parse_empty(k, v)?, "codegen-backend" => self.codegen_backend = parse_empty(k, v)?, - "config-include" => self.config_include = parse_empty(k, v)?, "direct-minimal-versions" => self.direct_minimal_versions = parse_empty(k, v)?, "dual-proc-macros" => self.dual_proc_macros = parse_empty(k, v)?, "feature-unification" => self.feature_unification = parse_empty(k, v)?, diff --git a/src/cargo/util/context/mod.rs b/src/cargo/util/context/mod.rs index a3f2e470553..d6d9a9e9f05 100644 --- a/src/cargo/util/context/mod.rs +++ b/src/cargo/util/context/mod.rs @@ -187,10 +187,8 @@ pub const TOP_LEVEL_CONFIG_KEYS: &[&str] = &[ enum WhyLoad { /// Loaded due to a request from the global cli arg `--config` /// - /// Indirect configs loaded via [`config-include`] are also seen as from cli args, + /// Indirect configs loaded via [`ConfigInclude`] are also seen as from cli args, /// if the initial config is being loaded from cli. - /// - /// [`config-include`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#config-include Cli, /// Loaded due to config file discovery. FileDiscovery, @@ -1139,19 +1137,7 @@ impl GlobalContext { self.merge_cli_args()?; } - // Load the unstable flags from config file here first, as the config - // file itself may enable inclusion of other configs. In that case, we - // want to re-load configs with includes enabled: self.load_unstable_flags_from_config()?; - if self.unstable_flags.config_include { - // If the config was already loaded (like when fetching the - // `[alias]` table), it was loaded with includes disabled because - // the `unstable_flags` hadn't been set up, yet. Any values - // fetched before this step will not process includes, but that - // should be fine (`[alias]` is one of the only things loaded - // before configure). This can be removed when stabilized. - self.reload_rooted_at(self.cwd.clone())?; - } // Ignore errors in the configuration files. We don't want basic // commands like `cargo version` to error out due to config file @@ -1278,9 +1264,7 @@ impl GlobalContext { let home = self.home_path.clone().into_path_unlocked(); self.walk_tree(&self.cwd, &home, |path| { let mut cv = self._load_file(path, &mut seen, false, WhyLoad::FileDiscovery)?; - if self.cli_unstable().config_include { - self.load_unmerged_include(&mut cv, &mut seen, &mut result)?; - } + self.load_unmerged_include(&mut cv, &mut seen, &mut result)?; result.push(cv); Ok(()) }) @@ -1351,11 +1335,9 @@ impl GlobalContext { /// /// This is actual implementation of loading a config value from a path. /// - /// * `includes` determines whether to load configs from [`config-include`]. + /// * `includes` determines whether to load configs from [`ConfigInclude`]. /// * `seen` is used to check for cyclic includes. /// * `why_load` tells why a config is being loaded. - /// - /// [`config-include`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#config-include fn _load_file( &self, path: &Path, @@ -1407,10 +1389,7 @@ impl GlobalContext { ) -> CargoResult { // Get the list of files to load. let includes = self.include_paths(&mut value, true)?; - // Check unstable. - if !self.cli_unstable().config_include { - return Ok(value); - } + // Accumulate all values here. let mut root = CV::Table(HashMap::new(), value.definition().clone()); for include in includes { diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index 71d5d3a65d0..716d13beef7 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -269,6 +269,58 @@ cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.r cargo --config profile.dev.package.image.opt-level=3 … ``` +## Including extra configuration files + +Configuration can include other configuration files using the top-level `include` key. +This allows sharing configuration across multiple projects +or splitting complex configurations into multiple files. + +### `include` + +* Type: array of strings or tables +* Default: none +* Environment: not supported + +Loads additional configuration files. +Paths are relative to the configuration file that includes them. +Only paths ending with `.toml` are accepted. + +Supports the following formats: + +```toml +# array of paths +include = [ + "frodo.toml", + "samwise.toml", +] + +# inline tables for more control +include = [ + { path = "required.toml" }, + { path = "optional.toml", optional = true }, +] +``` + +> **Note:** For better readability and to avoid confusion, it is recommended to: +> - Place `include` at the top of the configuration file +> - Put one include per line for clearer version control diffs +> - Use inline table syntax when optional includes are needed + +When using table syntax, the following fields are supported: + +* `path` (string, required): Path to the config file to include. +* `optional` (boolean, default: false): If `true`, missing files are silently + skipped instead of causing an error. + +The merge behavior of `include` is different from other config values: + +1. Config values are first loaded from the `include` paths. + * Included files are loaded left to right, + with values from later files taking precedence over earlier ones. + * This step recurses if included config files also contain `include` keys. +2. Then, the config file's own values are merged on top of the included config, + taking highest precedence. + ## Config-relative paths Paths in config files may be absolute, relative, or a bare name without any path separators. diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 9e684dc1d9d..71d674b0975 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -120,7 +120,6 @@ Each new feature described below should explain how to use it. * [Build analysis](#build-analysis) --- Record and persist detailed build metrics across runs, with new commands to query past builds. * [`rustc-unicode`](#rustc-unicode) --- Enables `rustc`'s unicode error format in Cargo's error messages * Configuration - * [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 * [publish-timeout](#publish-timeout) --- Controls the timeout between uploading the crate and being available in the index @@ -637,85 +636,6 @@ like to stabilize it somehow! [rust-lang/rust#64158]: https://github.com/rust-lang/rust/pull/64158 -## config-include -* Tracking Issue: [#7723](https://github.com/rust-lang/cargo/issues/7723) - -This feature requires the `-Zconfig-include` command-line option. - -The `include` key in a config file can be used to load another config file. -For example: - -```toml -# .cargo/config.toml -include = ["other-config.toml"] - -[build] -jobs = 4 -``` - -```toml -# .cargo/other-config.toml -[build] -rustflags = ["-W", "unsafe-code"] -``` - -### Documentation updates - -> put this after `## Command-line overrides` before `## Config-relative paths` -> to emphasize its special nature than other config keys. - -#### Including extra configuration files - -Configuration can include other configuration files using the top-level `include` key. -This allows sharing configuration across multiple projects -or splitting complex configurations into multiple files. - -##### `include` - -* Type: array of strings or tables -* Default: none -* Environment: not supported - -Loads additional configuration files. -Paths are relative to the configuration file that includes them. -Only paths ending with `.toml` are accepted. - -Supports the following formats: - -```toml -# array of paths -include = [ - "frodo.toml", - "samwise.toml", -] - -# inline tables for more control -include = [ - { path = "required.toml" }, - { path = "optional.toml", optional = true }, -] -``` - -> **Note:** For better readability and to avoid confusion, it is recommended to: -> - Place `include` at the top of the configuration file -> - Put one include per line for clearer version control diffs -> - Use inline table syntax when optional includes are needed - -When using table syntax, the following fields are supported: - -* `path` (string, required): Path to the config file to include. -* `optional` (boolean, default: false): If `true`, missing files are silently - skipped instead of causing an error. - -The merge behavior of `include` is different from other config values: - -1. Config values are first loaded from the `include` paths. - * Included files are loaded left to right, - with values from later files taking precedence over earlier ones. - * This step recurses if included config files also contain `include` keys. -2. Then, the config file's own values are merged on top of the included config, - taking highest precedence. - ## target-applies-to-host * Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322) * Tracking Issue: [#9453](https://github.com/rust-lang/cargo/issues/9453) @@ -2347,3 +2267,9 @@ See the [config documentation](config.md#buildbuild-dir) for information about c The `--build-plan` argument for the `build` command has been removed in 1.93.0-nightly. See for the reason for its removal. + +## config-include + +Support for including extra configuration files via the `include` config key +has been stabilized in 1.93.0. +See the [`include` config documentation](config.md#include) for more. diff --git a/tests/testsuite/cargo/z_help/stdout.term.svg b/tests/testsuite/cargo/z_help/stdout.term.svg index e1dddbc6cec..e3f325335e6 100644 --- a/tests/testsuite/cargo/z_help/stdout.term.svg +++ b/tests/testsuite/cargo/z_help/stdout.term.svg @@ -1,4 +1,4 @@ - +