feat(config-include): add optional field support (#16180)

### What does this PR try to resolve? When `optional=true` Cargo silently skip missing config-include files. Example config: ```toml [[include]] path = 'optional-config.toml' optional = true ``` Part of <#7723 (comment)>. ### How to test and review this PR? CI passes. In the updated doc, I am a bit not sure whether we should have standalone sections like `include.path` and `include.optional`, as we cannot really set `include.path = "config.toml"` directly. Or maybe `include[].path` is good for heading?Capture current behavior where optional field is not yet supported.

Author: epage

src/cargo/util/context/mod.rs

@@ -1258,8 +1258,12 @@ impl GlobalContext {
  ) -> CargoResult<()> {
  let includes = self.include_paths(cv, false)?;
  for include in includes {
+ let Some(abs_path) = include.resolve_path(self) else {
+ continue;
+ };
+
  let mut cv = self
- ._load_file(&include.abs_path(self), seen, false, WhyLoad::FileDiscovery)
+ ._load_file(&abs_path, seen, false, WhyLoad::FileDiscovery)
  .with_context(|| {
  format!(
  "failed to load config include `{}` from `{}`",
@@ -1369,7 +1373,11 @@ impl GlobalContext {
  // Accumulate all values here.
  let mut root = CV::Table(HashMap::new(), value.definition().clone());
  for include in includes {
- self._load_file(&include.abs_path(self), seen, true, why_load)
+ let Some(abs_path) = include.resolve_path(self) else {
+ continue;
+ };
+
+ self._load_file(&abs_path, seen, true, why_load)
  .and_then(|include| root.merge(include, true))
  .with_context(|| {
  format!(
@@ -1410,7 +1418,20 @@ impl GlobalContext {
  ),
  None => bail!("missing field `path` at `include[{idx}]` in `{def}`"),
  };
- Ok(ConfigInclude::new(s, def))
+
+ // Extract optional `include.optional` field
+ let optional = match table.remove("optional") {
+ Some(CV::Boolean(b, _)) => b,
+ Some(other) => bail!(
+ "expected a boolean, but found {} at `include[{idx}].optional` in `{def}`",
+ other.desc()
+ ),
+ None => false,
+ };
+
+ let mut include = ConfigInclude::new(s, def);
+ include.optional = optional;
+ Ok(include)
  }
  other => bail!(
  "expected a string or table, but found {} at `include[{idx}]` in {}",
@@ -2495,17 +2516,20 @@ struct ConfigInclude {
  /// Could be either relative or absolute.
  path: PathBuf,
  def: Definition,
+ /// Whether this include is optional (missing files are silently ignored)
+ optional: bool,
 }
 
 impl ConfigInclude {
  fn new(p: impl Into<PathBuf>, def: Definition) -> Self {
  Self {
  path: p.into(),
  def,
+ optional: false,
  }
  }
 
- /// Gets the absolute path of the config-include config file.
+ /// Resolves the absolute path for this include.
  ///
  /// For file based include,
  /// it is relative to parent directory of the config file includes it.
@@ -2514,12 +2538,27 @@ impl ConfigInclude {
  ///
  /// For CLI based include (e.g., `--config 'include = "foo.toml"'`),
  /// it is relative to the current working directory.
- fn abs_path(&self, gctx: &GlobalContext) -> PathBuf {
- match &self.def {
+ ///
+ /// Returns `None` if this is an optional include and the file doesn't exist.
+ /// Otherwise returns `Some(PathBuf)` with the absolute path.
+ fn resolve_path(&self, gctx: &GlobalContext) -> Option<PathBuf> {
+ let abs_path = match &self.def {
  Definition::Path(p) | Definition::Cli(Some(p)) => p.parent().unwrap(),
  Definition::Environment(_) | Definition::Cli(None) | Definition::BuiltIn => gctx.cwd(),
  }
- .join(&self.path)
+ .join(&self.path);
+
+ if self.optional && !abs_path.exists() {
+ tracing::info!(
+ "skipping optional include `{}` in `{}`: file not found at `{}`",
+ self.path.display(),
+ self.def,
+ abs_path.display(),
+ );
+ None
+ } else {
+ Some(abs_path)
+ }
  }
 }
 

src/doc/src/reference/unstable.md

@@ -658,28 +658,71 @@ like to stabilize it somehow!
 
 This feature requires the `-Zconfig-include` command-line option.
 
-The `include` key in a config file can be used to load another config file. It
-takes a string for a path to another file relative to the config file, or an
-array of config file paths. Only path ending with `.toml` is accepted.
+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
+
+#### `include`
+
+* Type: string, array of strings, or array of tables
+* Default: none
+
+Loads additional config files. Paths are relative to the config file that
+includes them. Only paths ending with `.toml` are accepted.
+
+Supports the following formats:
 
 ```toml
-# a path ending with `.toml`
+# single path
 include = "path/to/mordor.toml"
 
-# or an array of paths
+# array of paths
 include = ["frodo.toml", "samwise.toml"]
+
+# inline tables
+include = [
+ "simple.toml",
+ { path = "optional.toml", optional = true }
+]
+
+# array of tables
+[[include]]
+path = "required.toml"
+
+[[include]]
+path = "optional.toml"
+optional = true
 ```
 
-Unlike other config values, the merge behavior of the `include` key is
-different. When a config file contains an `include` key:
+When using table syntax (inline tables or array of tables), 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. The config values are first loaded from the `include` path.
- * If the value of the `include` key is an array of paths, the config values
- are loaded and merged from left to right for each path.
- * Recurse this step if the config values from the `include` path also
- contain an `include` key.
-2. Then, the config file's own values are merged on top of the config
- from the `include` path.
+1. Config values are first loaded from the `include` path.
+ * If `include` is an array, config values are loaded and merged from left
+ to right for each path.
+ * 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.
 
 ## target-applies-to-host
 * Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322)

tests/testsuite/config_include.rs

@@ -621,3 +621,66 @@ Caused by:
 "#]],
  );
 }
+
+#[cargo_test]
+fn optional_include_missing_and_existing() {
+ write_config_at(
+ ".cargo/config.toml",
+ "
+ key1 = 1
+
+ [[include]]
+ path = 'missing.toml'
+ optional = true
+
+ [[include]]
+ path = 'other.toml'
+ optional = true
+ ",
+ );
+ write_config_at(
+ ".cargo/other.toml",
+ "
+ key2 = 2
+ ",
+ );
+
+ let gctx = GlobalContextBuilder::new()
+ .unstable_flag("config-include")
+ .build();
+ assert_eq!(gctx.get::<i32>("key1").unwrap(), 1);
+ assert_eq!(gctx.get::<i32>("key2").unwrap(), 2);
+}
+
+#[cargo_test]
+fn optional_false_missing_file() {
+ write_config_at(
+ ".cargo/config.toml",
+ "
+ key1 = 1
+
+ [[include]]
+ path = 'missing.toml'
+ optional = false
+ ",
+ );
+
+ let gctx = GlobalContextBuilder::new()
+ .unstable_flag("config-include")
+ .build_err();
+ assert_error(
+ gctx.unwrap_err(),
+ str![[r#"
+could not load Cargo configuration
+
+Caused by:
+ failed to load config include `missing.toml` from `[ROOT]/.cargo/config.toml`
+
+Caused by:
+ failed to read configuration file `[ROOT]/.cargo/missing.toml`
+
+Caused by:
+ [NOT_FOUND]
+"#]],
+ );
+}