refactor: rename bundled_artifact -> materialized_artifact

claude · claude · commit a2d7f8671116 · 2026-04-18T07:48:58.000Z
"Bundled" clashes with `include_bytes!`, which also bundles. The
distinctive feature of this crate is that it gives you a real path
on disk for APIs that need one (`LoadLibrary`, `LD_PRELOAD`, helper
binaries) — the value-add over `include_bytes!` is the
materialization step. The env-var prefix moves to
`MATERIALIZED_ARTIFACT_` accordingly.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -69,8 +69,8 @@ derive_more = "2.0.1"
 diff-struct = "0.5.3"
 directories = "6.0.0"
 elf = { version = "0.8.0", default-features = false }
-bundled_artifact = { path = "crates/bundled_artifact" }
-bundled_artifact_build = { path = "crates/bundled_artifact_build" }
+materialized_artifact = { path = "crates/materialized_artifact" }
+materialized_artifact_build = { path = "crates/materialized_artifact_build" }
 flate2 = "1.0.35"
 fspy = { path = "crates/fspy" }
 fspy_detours_sys = { path = "crates/fspy_detours_sys" }
diff --git a/crates/bundled_artifact/README.md b/crates/bundled_artifact/README.md
diff --git a/crates/bundled_artifact_build/README.md b/crates/bundled_artifact_build/README.md
diff --git a/crates/fspy/Cargo.toml b/crates/fspy/Cargo.toml
@@ -10,7 +10,7 @@ wincode = { workspace = true }
 bstr = { workspace = true, default-features = false }
 bumpalo = { workspace = true }
 derive_more = { workspace = true, features = ["debug"] }
-bundled_artifact = { workspace = true }
+materialized_artifact = { workspace = true }
 fspy_shared = { workspace = true }
 futures-util = { workspace = true }
 libc = { workspace = true }
@@ -60,7 +60,7 @@ fspy_test_bin = { path = "../fspy_test_bin", artifact = "bin", target = "x86_64-
 # builds are cheap.
 [build-dependencies]
 anyhow = { workspace = true }
-bundled_artifact_build = { workspace = true }
+materialized_artifact_build = { workspace = true }
 flate2 = { workspace = true }
 fspy_preload_unix = { workspace = true }
 fspy_preload_windows = { workspace = true }
diff --git a/crates/fspy/build.rs b/crates/fspy/build.rs
@@ -138,7 +138,7 @@ fn fetch_macos_binaries(out_dir: &Path) -> anyhow::Result<()> {
             );
             fs::write(&dest, &data).with_context(|| format!("writing {}", dest.display()))?;
         }
-        bundled_artifact_build::register(name, &dest);
+        materialized_artifact_build::register(name, &dest);
     }
     Ok(())
 }
@@ -153,7 +153,7 @@ fn register_preload_cdylib() -> anyhow::Result<()> {
     // the path changes. Track it so we re-publish the hash on update.
     println!("cargo:rerun-if-env-changed={env_name}");
     let dylib_path = env::var_os(env_name).with_context(|| format!("{env_name} not set"))?;
-    bundled_artifact_build::register("fspy_preload", Path::new(&dylib_path));
+    materialized_artifact_build::register("fspy_preload", Path::new(&dylib_path));
     Ok(())
 }
 
diff --git a/crates/fspy/src/unix/macos_artifacts.rs b/crates/fspy/src/unix/macos_artifacts.rs
@@ -1,4 +1,4 @@
-use bundled_artifact::{Artifact, artifact};
+use materialized_artifact::{Artifact, artifact};
 
 pub const COREUTILS_BINARY: Artifact = artifact!("coreutils");
 pub const OILS_BINARY: Artifact = artifact!("oils_for_unix");
diff --git a/crates/fspy/src/unix/mod.rs b/crates/fspy/src/unix/mod.rs
@@ -45,7 +45,7 @@ impl SpyImpl {
     pub fn init_in(#[cfg_attr(target_env = "musl", allow(unused))] dir: &Path) -> io::Result<Self> {
         #[cfg(not(target_env = "musl"))]
         let preload_path = {
-            use bundled_artifact::{Artifact, artifact};
+            use materialized_artifact::{Artifact, artifact};
 
             const PRELOAD_CDYLIB: Artifact = artifact!("fspy_preload");
 
diff --git a/crates/fspy/src/windows/mod.rs b/crates/fspy/src/windows/mod.rs
@@ -6,13 +6,13 @@ use std::{
     sync::Arc,
 };
 
-use bundled_artifact::{Artifact, artifact};
 use fspy_detours_sys::{DetourCopyPayloadToProcess, DetourUpdateProcessWithDll};
 use fspy_shared::{
     ipc::{PathAccess, channel::channel},
     windows::{PAYLOAD_ID, Payload},
 };
 use futures_util::FutureExt;
+use materialized_artifact::{Artifact, artifact};
 use tokio_util::sync::CancellationToken;
 use winapi::{
     shared::minwindef::TRUE,
diff --git a/crates/materialized_artifact/.clippy.toml b/crates/materialized_artifact/.clippy.toml
diff --git a/crates/materialized_artifact/Cargo.toml b/crates/materialized_artifact/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "bundled_artifact"
+name = "materialized_artifact"
 version = "0.0.0"
 edition.workspace = true
 license.workspace = true
diff --git a/crates/materialized_artifact/README.md b/crates/materialized_artifact/README.md
@@ -0,0 +1,8 @@
+# materialized_artifact
+
+Materialize a compile-time–embedded file to disk on demand, for APIs that
+need a filesystem path (`LoadLibrary`, `LD_PRELOAD`, helper binaries) rather
+than the bytes you'd get from `include_bytes!`. The on-disk filename is
+content-addressed so repeated calls skip writing, multiple versions coexist,
+and stale files are never mistaken for current ones. See crate-level docs
+for details.
diff --git a/crates/materialized_artifact/src/lib.rs b/crates/materialized_artifact/src/lib.rs
@@ -1,23 +1,24 @@
-//! Bundle a file into the executable and materialize it to disk on demand.
+//! Materialize a compile-time–embedded file to disk on demand.
 //!
 //! Some APIs need a file on disk — `LoadLibrary` and `LD_PRELOAD` take a
 //! path, and helper binaries have to exist as actual files to be spawned —
-//! but we want to ship a single executable. `bundled_artifact` embeds the
-//! file content as a `&'static [u8]` at compile time via the [`artifact!`]
-//! macro, and [`Artifact::ensure_in`] writes it out to disk when first
-//! needed.
+//! but we want to ship a single executable. `materialized_artifact` embeds
+//! the file content as a `&'static [u8]` at compile time via the
+//! [`artifact!`] macro (same as `include_bytes!`), and
+//! [`Artifact::ensure_in`] writes it out to disk when first needed — that
+//! materialization step is the value-add over a bare `include_bytes!`.
 //!
 //! Materialized files are named `{name}_{hash}{suffix}` in the caller-chosen
 //! directory. The hash (computed at build time by
-//! `bundled_artifact_build::register`) gives three properties without any
-//! coordination between processes:
+//! `materialized_artifact_build::register`) gives three properties without
+//! any coordination between processes:
 //!
 //! - **No repeated writes.** [`Artifact::ensure_in`] returns the existing
 //!   path if the file is already there; repeated calls and re-runs skip I/O.
 //! - **Correctness.** Two binaries with different embedded content produce
 //!   different filenames, so a stale file from an older build is never
 //!   mistaken for the current one.
-//! - **Coexistence.** Multiple versions of a bundled artifact (e.g. from
+//! - **Coexistence.** Multiple versions of a materialized artifact (e.g. from
 //!   different builds of the host program on the same machine) share `dir`
 //!   without overwriting each other.
 
@@ -27,9 +28,9 @@ use std::{
     path::{Path, PathBuf},
 };
 
-/// A file bundled into the executable. Construct with [`artifact!`];
-/// materialize to disk with [`Artifact::ensure_in`]. See the [crate docs]
-/// for the design rationale.
+/// A file embedded into the executable at compile time. Construct with
+/// [`artifact!`]; materialize to disk with [`Artifact::ensure_in`]. See the
+/// [crate docs] for the design rationale.
 ///
 /// [crate docs]: crate
 pub struct Artifact {
@@ -39,19 +40,19 @@ pub struct Artifact {
 }
 
 /// Construct an [`Artifact`] from the env vars published by a build script
-/// via `bundled_artifact_build::register`. Must match the `ENV_PREFIX`
-/// constant in `bundled_artifact_build`.
+/// via `materialized_artifact_build::register`. Must match the `ENV_PREFIX`
+/// constant in `materialized_artifact_build`.
 #[macro_export]
 macro_rules! artifact {
     ($name:literal) => {
         $crate::Artifact::__new(
             $name,
             ::core::include_bytes!(::core::env!(::core::concat!(
-                "BUNDLED_ARTIFACT_",
+                "MATERIALIZED_ARTIFACT_",
                 $name,
                 "_PATH"
             ))),
-            ::core::env!(::core::concat!("BUNDLED_ARTIFACT_", $name, "_HASH")),
+            ::core::env!(::core::concat!("MATERIALIZED_ARTIFACT_", $name, "_HASH")),
         )
     };
 }
diff --git a/crates/materialized_artifact_build/.clippy.toml b/crates/materialized_artifact_build/.clippy.toml
diff --git a/crates/materialized_artifact_build/Cargo.toml b/crates/materialized_artifact_build/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "bundled_artifact_build"
+name = "materialized_artifact_build"
 version = "0.0.0"
 edition.workspace = true
 license.workspace = true
diff --git a/crates/materialized_artifact_build/README.md b/crates/materialized_artifact_build/README.md
@@ -0,0 +1,4 @@
+# materialized_artifact_build
+
+Build-script helper for publishing artifacts consumed by
+`materialized_artifact`'s `artifact!` macro.
diff --git a/crates/materialized_artifact_build/src/lib.rs b/crates/materialized_artifact_build/src/lib.rs
@@ -1,18 +1,18 @@
 use std::{fs, path::Path};
 
 /// Namespace prefix for the env vars set by [`register`] and consumed by
-/// `bundled_artifact`'s `artifact!` macro. Exported so both crates agree on
-/// the same prefix.
-pub const ENV_PREFIX: &str = "BUNDLED_ARTIFACT_";
+/// `materialized_artifact`'s `artifact!` macro. Exported so both crates agree
+/// on the same prefix.
+pub const ENV_PREFIX: &str = "MATERIALIZED_ARTIFACT_";
 
-/// Publish an artifact at `path` so `bundled_artifact`'s `artifact!($name)`
+/// Publish an artifact at `path` so `materialized_artifact`'s `artifact!($name)`
 /// macro can embed it.
 ///
 /// Emits three `cargo:…` directives:
 /// `rerun-if-changed={path}`,
-/// `rustc-env=BUNDLED_ARTIFACT_{name}_PATH={path}`, and
-/// `rustc-env=BUNDLED_ARTIFACT_{name}_HASH={hex}`. The runtime resolves these
-/// at compile time via `include_bytes!(env!(…))` and `env!(…)`.
+/// `rustc-env=MATERIALIZED_ARTIFACT_{name}_PATH={path}`, and
+/// `rustc-env=MATERIALIZED_ARTIFACT_{name}_HASH={hex}`. The runtime resolves
+/// these at compile time via `include_bytes!(env!(…))` and `env!(…)`.
 ///
 /// `name` is used both as the env-var key and as the on-disk filename prefix
 /// (in `Artifact::ensure_in`), so it must be a valid identifier-like string

Original file line number	Diff line number	Diff line change
`@@ -138,7 +138,7 @@ fn fetch_macos_binaries(out_dir: &Path) -> anyhow::Result<()> {`
`138`	`138`	`);`
`139`	`139`	`fs::write(&dest, &data).with_context(\|\| format!("writing {}", dest.display()))?;`
`140`	`140`	`}`
`141`		`- bundled_artifact_build::register(name, &dest);`
	`141`	`+ materialized_artifact_build::register(name, &dest);`
`142`	`142`	`}`
`143`	`143`	`Ok(())`
`144`	`144`	`}`
`@@ -153,7 +153,7 @@ fn register_preload_cdylib() -> anyhow::Result<()> {`
`153`	`153`	`// the path changes. Track it so we re-publish the hash on update.`
`154`	`154`	`println!("cargo:rerun-if-env-changed={env_name}");`
`155`	`155`	`let dylib_path = env::var_os(env_name).with_context(\|\| format!("{env_name} not set"))?;`
`156`		`- bundled_artifact_build::register("fspy_preload", Path::new(&dylib_path));`
	`156`	`+ materialized_artifact_build::register("fspy_preload", Path::new(&dylib_path));`
`157`	`157`	`Ok(())`
`158`	`158`	`}`
`159`	`159`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-use bundled_artifact::{Artifact, artifact};`
	`1`	`+use materialized_artifact::{Artifact, artifact};`
`2`	`2`
`3`	`3`	`pub const COREUTILS_BINARY: Artifact = artifact!("coreutils");`
`4`	`4`	`pub const OILS_BINARY: Artifact = artifact!("oils_for_unix");`