fix(trim-paths)!: limit options to none|object|all (#17432)

### What does this PR try to resolve?

This limits profile `trim-paths` options to only `none`, `object`, and
`all`.
For other scopes and boolean values, we can add it in the future when
needed.

This is a stabilization preparation for `-Ztrim-paths`.
See
<#12137 (comment)>.

### How to test and review this PR?

Also rewrote the profile trim-paths doc a bit but not extremely
satisfied.
Please help proofread.

Author: epage

Cargo.lock

@@ -36,7 +36,7 @@ cargo-platform = { path = "crates/cargo-platform", version = "0.3.3" }
 cargo-test-macro = { version = "0.4.15", path = "crates/cargo-test-macro" }
 cargo-test-support = { version = "0.12.0", path = "crates/cargo-test-support" }
 cargo-util = { version = "0.2.33", path = "crates/cargo-util" }
-cargo-util-schemas = { version = "0.14.4", path = "crates/cargo-util-schemas" }
+cargo-util-schemas = { version = "0.15.0", path = "crates/cargo-util-schemas" }
 cargo-util-terminal = { version = "0.1.3", path = "crates/cargo-util-terminal" }
 cargo_metadata = "0.23.1"
 clap = "4.6.0"

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cargo-util-schemas"
-version = "0.14.4"
+version = "0.15.0"
 rust-version = "1.98"  # MSRV:1
 edition.workspace = true
 license.workspace = true

crates/cargo-util-schemas/Cargo.toml

@@ -1473,7 +1473,11 @@
       "type": "string"
     },
     "TomlDebugInfo": {
-      "type": ["string", "integer", "boolean"],
+      "type": [
+        "string",
+        "integer",
+        "boolean"
+      ],
       "enum": [
         "none",
         "line-directives-only",
@@ -1491,24 +1495,11 @@
       "type": "string"
     },
     "TomlTrimPaths": {
-      "anyOf": [
-        {
-          "type": "array",
-          "items": {
-            "$ref": "#/$defs/TomlTrimPathsValue"
-          }
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "TomlTrimPathsValue": {
       "type": "string",
       "enum": [
-        "diagnostics",
-        "macro",
-        "object"
+        "none",
+        "object",
+        "all"
       ]
     }
   }

crates/cargo-util-schemas/manifest.schema.json

@@ -1233,119 +1233,30 @@ impl<'de> de::Deserialize<'de> for TomlDebugInfo {
     }
 }
 
-#[derive(Clone, Debug, PartialEq, Eq, Ord, PartialOrd, Hash, Serialize)]
-#[serde(untagged, rename_all = "kebab-case")]
+#[derive(Clone, Debug, PartialEq, Eq, Ord, PartialOrd, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
 #[cfg_attr(feature = "unstable-schema", derive(schemars::JsonSchema))]
 pub enum TomlTrimPaths {
-    Values(Vec<TomlTrimPathsValue>),
+    None,
+    Object,
     All,
 }
 
 impl TomlTrimPaths {
-    pub fn none() -> Self {
-        TomlTrimPaths::Values(Vec::new())
-    }
-
     pub fn is_none(&self) -> bool {
-        match self {
-            TomlTrimPaths::Values(v) => v.is_empty(),
-            TomlTrimPaths::All => false,
-        }
+        matches!(self, TomlTrimPaths::None)
     }
-}
 
-impl<'de> de::Deserialize<'de> for TomlTrimPaths {
-    fn deserialize<D>(d: D) -> Result<TomlTrimPaths, D::Error>
-    where
-        D: de::Deserializer<'de>,
-    {
-        use serde::de::Error as _;
-        let expecting = r#"a boolean, "none", "diagnostics", "macro", "object", "all", or an array with these options"#;
-        UntaggedEnumVisitor::new()
-            .expecting(expecting)
-            .bool(|value| {
-                Ok(if value {
-                    TomlTrimPaths::All
-                } else {
-                    TomlTrimPaths::none()
-                })
-            })
-            .string(|v| match v {
-                "none" => Ok(TomlTrimPaths::none()),
-                "all" => Ok(TomlTrimPaths::All),
-                v => {
-                    let d = v.into_deserializer();
-                    let err = |_: D::Error| {
-                        serde_untagged::de::Error::custom(format!("expected {expecting}"))
-                    };
-                    TomlTrimPathsValue::deserialize(d)
-                        .map_err(err)
-                        .map(|v| v.into())
-                }
-            })
-            .seq(|seq| {
-                let seq: Vec<String> = seq.deserialize()?;
-                let seq: Vec<_> = seq
-                    .into_iter()
-                    .map(|s| TomlTrimPathsValue::deserialize(s.into_deserializer()))
-                    .collect::<Result<_, _>>()?;
-                Ok(seq.into())
-            })
-            .deserialize(d)
-    }
-}
-
-impl fmt::Display for TomlTrimPaths {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    fn as_str(&self) -> &'static str {
         match self {
-            TomlTrimPaths::All => write!(f, "all"),
-            TomlTrimPaths::Values(v) if v.is_empty() => write!(f, "none"),
-            TomlTrimPaths::Values(v) => {
-                let mut iter = v.iter();
-                if let Some(value) = iter.next() {
-                    write!(f, "{value}")?;
-                }
-                for value in iter {
-                    write!(f, ",{value}")?;
-                }
-                Ok(())
-            }
+            TomlTrimPaths::None => "none",
+            TomlTrimPaths::Object => "object",
+            TomlTrimPaths::All => "all",
         }
     }
 }
 
-impl From<TomlTrimPathsValue> for TomlTrimPaths {
-    fn from(value: TomlTrimPathsValue) -> Self {
-        TomlTrimPaths::Values(vec![value])
-    }
-}
-
-impl From<Vec<TomlTrimPathsValue>> for TomlTrimPaths {
-    fn from(value: Vec<TomlTrimPathsValue>) -> Self {
-        TomlTrimPaths::Values(value)
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq, Ord, PartialOrd, Hash, Serialize, Deserialize)]
-#[serde(rename_all = "kebab-case")]
-#[cfg_attr(feature = "unstable-schema", derive(schemars::JsonSchema))]
-pub enum TomlTrimPathsValue {
-    Diagnostics,
-    Macro,
-    Object,
-}
-
-impl TomlTrimPathsValue {
-    pub fn as_str(&self) -> &'static str {
-        match self {
-            TomlTrimPathsValue::Diagnostics => "diagnostics",
-            TomlTrimPathsValue::Macro => "macro",
-            TomlTrimPathsValue::Object => "object",
-        }
-    }
-}
-
-impl fmt::Display for TomlTrimPathsValue {
+impl fmt::Display for TomlTrimPaths {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{}", self.as_str())
     }

crates/cargo-util-schemas/src/manifest/mod.rs

@@ -1494,7 +1494,7 @@ cargo-features = ["trim-paths"]
 # ...
 
 [profile.release]
-trim-paths = ["diagnostics", "object"]
+trim-paths = "object"
 ```
 
 To set this in a profile in Cargo configuration,
@@ -1507,7 +1507,7 @@ For example,
 trim-paths = true
 
 [profile.release]
-trim-paths = ["diagnostics", "object"]
+trim-paths = "object"
 ```
 
 ### Documentation updates
@@ -1516,17 +1516,27 @@ trim-paths = ["diagnostics", "object"]
 
 *as a new ["Profiles settings" entry](./profiles.html#profile-settings)*
 
-`trim-paths` is a profile setting which enables and controls the sanitization of file paths in build outputs.
-It takes the following values:
+The `trim-paths` option controls the scope of path sanitization in build outputs
+Paths are sanitized according to these [remapping rules].
 
-- `"none"` and `false` --- disable path sanitization
-- `"macro"` --- sanitize paths in the expansion of `std::file!()` macro.
-    This is where paths in embedded panic messages come from
-- `"diagnostics"` --- sanitize paths in printed compiler diagnostics
-- `"object"` --- sanitize paths in compiled executables or libraries
-- `"all"` and `true` --- sanitize paths in all possible locations
+The valid options are:
 
-It also takes an array with the combinations of `"macro"`, `"diagnostics"`, and `"object"`.
+- `"none"` --- disables path sanitization.
+- `"object"` --- sanitizes paths embedded in compiled executables and libraries.
+  Useful for improving artifact reproducibility
+  with less impact on local development.
+- `"all"` --- sanitizes paths in all supported locations.
+  Useful for hermetic or remote builds that need artifacts and diagnostics
+  to be independent of the build environment.
+
+> [!WARNING]
+> The `"all"` option remaps compiler diagnostics,
+> including [compiler JSON messages](./external-tools.md#json-messages).
+> Some remapped paths may not resolve to files on the local filesystem,
+> which can affect editors and other tools that consume the diagnostic output.
+
+For details about each scope,
+see rustc's [`--remap-path-scope`] documentation.
 
 By default, `trim-paths` is not set and path sanitization is disabled for all profiles.
 You can enable it by specifying this option in `Cargo.toml`:
@@ -1536,13 +1546,11 @@ You can enable it by specifying this option in `Cargo.toml`:
 trim-paths = "all"
 
 [profile.release]
-trim-paths = ["object", "diagnostics"]
+trim-paths = "object"
 ```
 
-For more information about each scope,
-see rustc's documentation on [`--remap-path-scope`].
-
 [`--remap-path-scope`]: ../../rustc/remap-source-paths.html#--remap-path-scope
+[remapping rules]: #remapping-rules
 
 ##### Remapping rules
 
@@ -1552,7 +1560,7 @@ should consume [unremap files] instead of interpreting these prefixes.
 
 [unremap files]: #unremap-files
 
-If `trim-paths` is not `"none"` or `false`,
+If `trim-paths` is not `"none"`,
 then the following paths are sanitized if they appear in a selected scope:
 
 1. Path to the source files of the standard and core library (sysroot) will begin with `/rustc/<rustc commit hash>`,
@@ -1657,13 +1665,13 @@ but it still contains absolute paths.
 *as a new entry of ["Environment variables Cargo sets for build scripts"](./environment-variables.md#environment-variables-cargo-sets-for-crates)*
 
 * `CARGO_TRIM_PATHS_SCOPE` --- The value of `trim-paths` profile option.
-    `false`, `"none"`, and empty arrays would be converted to `none`.
-    `true` and `"all"` become `all`.
-    Values in a non-empty array would be joined into a comma-separated list.
     If the build script introduces absolute paths to built artifacts (such as by invoking a compiler),
     the user may request them to be sanitized in different types of artifacts.
     Common paths requiring sanitization include `OUT_DIR`, `CARGO_MANIFEST_DIR` and `CARGO_MANIFEST_PATH`,
     plus any other introduced by the build script, such as include directories.
+    > [!NOTE]
+    > For forward compatibility,
+    > build scripts should accept a comma-separated list of scopes.
 * `CARGO_TRIM_PATHS_REMAP` --- The `<from>=<to>` path remap pairs Cargo passes to the compiler,
     joined by the platform path separator.
     Only set when `trim-paths` profile is active.

doc/book/src/reference/unstable.md

@@ -11,7 +11,6 @@ use std::path::PathBuf;
 
 use cargo_util::ProcessBuilder;
 use cargo_util_schemas::manifest::TomlTrimPaths;
-use cargo_util_schemas::manifest::TomlTrimPathsValue;
 use serde::Serialize;
 use tracing::debug;
 
@@ -44,12 +43,9 @@ pub(crate) fn trim_paths_args_rustdoc(
     unit: &Unit,
     trim_paths: &TomlTrimPaths,
 ) -> CargoResult<()> {
-    match trim_paths {
-        // rustdoc supports diagnostics trimming only.
-        TomlTrimPaths::Values(values) if !values.contains(&TomlTrimPathsValue::Diagnostics) => {
-            return Ok(());
-        }
-        _ => {}
+    // rustdoc supports diagnostics trimming only.
+    if !matches!(trim_paths, TomlTrimPaths::All) {
+        return Ok(());
     }
 
     for pair in trim_paths_remap(build_runner, unit) {
@@ -298,8 +294,8 @@ pub(crate) fn should_emit_unremap_file(unit: &Unit) -> bool {
 
     match unit.profile.trim_paths.as_ref() {
         None => false,
-        Some(TomlTrimPaths::All) => true,
-        Some(TomlTrimPaths::Values(values)) => values.contains(&TomlTrimPathsValue::Object),
+        Some(TomlTrimPaths::None) => false,
+        Some(TomlTrimPaths::Object | TomlTrimPaths::All) => true,
     }
 }
 

src/compiler/trim_paths.rs

@@ -3268,7 +3268,7 @@ fn bad_trim_paths() {
         .masquerade_as_nightly_cargo(&["trim-paths"])
         .with_status(101)
         .with_stderr_data(str![[r#"
-[ERROR] expected a boolean, "none", "diagnostics", "macro", "object", "all", or an array with these options
+[ERROR] unknown variant `split-debuginfo`, expected one of `none`, `object`, `all`
  --> Cargo.toml:8:30
   |
 8 |                 trim-paths = "split-debuginfo"

tests/testsuite/bad_config.rs

@@ -19,7 +19,6 @@ use cargo_test_support::compare::assert_e2e;
 use cargo_test_support::str;
 use cargo_test_support::{paths, project, project_in_home, symlink_supported, t};
 use cargo_util_schemas::manifest::TomlTrimPaths;
-use cargo_util_schemas::manifest::TomlTrimPathsValue;
 use cargo_util_schemas::manifest::{self as cargo_toml, TomlDebugInfo, VecStringOrBool as VSOB};
 use cargo_util_terminal::Shell;
 use serde::Deserialize;
@@ -1872,9 +1871,9 @@ fn trim_paths_parsing() {
     assert_eq!(p.trim_paths, None);
 
     let test_cases = [
-        (TomlTrimPathsValue::Diagnostics.into(), "diagnostics"),
-        (TomlTrimPathsValue::Macro.into(), "macro"),
-        (TomlTrimPathsValue::Object.into(), "object"),
+        (TomlTrimPaths::None, "none"),
+        (TomlTrimPaths::Object, "object"),
+        (TomlTrimPaths::All, "all"),
     ];
     for (expected, val) in test_cases {
         // env
@@ -1891,38 +1890,6 @@ fn trim_paths_parsing() {
         let trim_paths: TomlTrimPaths = gctx.get("profile.dev.trim-paths").unwrap();
         assert_eq!(trim_paths, expected, "failed to parse {val}");
     }
-
-    let test_cases = [(TomlTrimPaths::none(), false), (TomlTrimPaths::All, true)];
-
-    for (expected, val) in test_cases {
-        // env
-        let gctx = GlobalContextBuilder::new()
-            .env("CARGO_PROFILE_DEV_TRIM_PATHS", format!("{val}"))
-            .build();
-        let trim_paths: TomlTrimPaths = gctx.get("profile.dev.trim-paths").unwrap();
-        assert_eq!(trim_paths, expected, "failed to parse {val}");
-
-        // config.toml
-        let gctx = GlobalContextBuilder::new()
-            .config_arg(format!("profile.dev.trim-paths={val}"))
-            .build();
-        let trim_paths: TomlTrimPaths = gctx.get("profile.dev.trim-paths").unwrap();
-        assert_eq!(trim_paths, expected, "failed to parse {val}");
-    }
-
-    let expected = vec![
-        TomlTrimPathsValue::Diagnostics,
-        TomlTrimPathsValue::Macro,
-        TomlTrimPathsValue::Object,
-    ]
-    .into();
-    let val = r#"["diagnostics", "macro", "object"]"#;
-    // config.toml
-    let gctx = GlobalContextBuilder::new()
-        .config_arg(format!("profile.dev.trim-paths={val}"))
-        .build();
-    let trim_paths: TomlTrimPaths = gctx.get("profile.dev.trim-paths").unwrap();
-    assert_eq!(trim_paths, expected, "failed to parse {val}");
 }
 
 #[cargo_test]