hydro_lang/compile/trybuild/

generate.rs

use std::fs::{self, File};
use std::io::{Read, Seek, SeekFrom, Write};
use std::path::{Path, PathBuf};

#[cfg(any(feature = "deploy", feature = "maelstrom"))]
use dfir_lang::diagnostic::Diagnostics;
#[cfg(any(feature = "deploy", feature = "maelstrom"))]
use dfir_lang::graph::DfirGraph;
use sha2::{Digest, Sha256};
#[cfg(any(feature = "deploy", feature = "maelstrom"))]
use stageleft::internal::quote;
use trybuild_internals_api::cargo::{self, Metadata};
use trybuild_internals_api::env::Update;
use trybuild_internals_api::run::{PathDependency, Project};
use trybuild_internals_api::{Runner, dependencies, features, path};

pub const HYDRO_RUNTIME_FEATURES: &[&str] = &[
    "deploy_integration",
    "runtime_measure",
    "docker_runtime",
    "ecs_runtime",
    "maelstrom_runtime",
    "sim_runtime",
];

#[cfg(any(feature = "deploy", feature = "maelstrom"))]
/// Whether to use dynamic linking for the generated binary.
/// - `Static`: Place in base crate examples (for remote/containerized deploys)
/// - `Dynamic`: Place in dylib crate examples (for sim and localhost deploys)
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LinkingMode {
    // `Static` is only constructed by the deploy backends; Maelstrom-only builds
    // always use `Dynamic`.
    #[cfg_attr(
        not(feature = "deploy"),
        expect(
            dead_code,
            reason = "only constructed by the deploy backends; Maelstrom-only builds use Dynamic"
        )
    )]
    Static,
    #[cfg(any(feature = "deploy", feature = "maelstrom"))]
    Dynamic,
}

#[cfg(any(feature = "deploy", feature = "maelstrom"))]
/// The deployment mode for code generation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DeployMode {
    #[cfg(feature = "deploy")]
    /// Standard HydroDeploy
    HydroDeploy,
    #[cfg(any(feature = "docker_deploy", feature = "ecs_deploy"))]
    /// Containerized deployment (Docker/ECS)
    Containerized,
    #[cfg(feature = "maelstrom")]
    /// Maelstrom deployment with stdin/stdout JSON protocol
    Maelstrom,
}

pub(crate) static IS_TEST: std::sync::atomic::AtomicBool =
    std::sync::atomic::AtomicBool::new(false);

pub(crate) static CONCURRENT_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

/// Enables "test mode" for Hydro, which makes it possible to compile Hydro programs written
/// inside a `#[cfg(test)]` module. This should be enabled in a global [`ctor`] hook.
///
/// # Example
/// ```ignore
/// #[cfg(test)]
/// mod test_init {
///    #[ctor::ctor]
///    fn init() {
///        hydro_lang::compile::init_test();
///    }
/// }
/// ```
pub fn init_test() {
    IS_TEST.store(true, std::sync::atomic::Ordering::Relaxed);
}

#[cfg(any(feature = "deploy", feature = "maelstrom"))]
fn clean_bin_name_prefix(bin_name_prefix: &str) -> String {
    bin_name_prefix
        .replace("::", "__")
        .replace(" ", "_")
        .replace(",", "_")
        .replace("<", "_")
        .replace(">", "")
        .replace("(", "")
        .replace(")", "")
        .replace("{", "_")
        .replace("}", "_")
}

#[derive(Debug, Clone)]
pub struct TrybuildConfig {
    pub project_dir: PathBuf,
    pub target_dir: PathBuf,
    pub features: Option<Vec<String>>,
    #[cfg(any(feature = "deploy", feature = "maelstrom"))]
    // Only the deploy backends read this field; Maelstrom-only builds derive the
    // linking behavior directly.
    #[cfg_attr(
        not(feature = "deploy"),
        expect(dead_code, reason = "only read by the deploy backends")
    )]
    /// Which crate within the workspace to use for examples.
    /// - `Static`: base crate (for remote/containerized deploys)
    /// - `Dynamic`: dylib-examples crate (for sim and localhost deploys)
    pub linking_mode: LinkingMode,
}

#[cfg(any(feature = "deploy", feature = "maelstrom"))]
pub fn create_graph_trybuild(
    graph: DfirGraph,
    extra_stmts: &[syn::Stmt],
    sidecars: &[syn::Expr],
    bin_name_prefix: Option<&str>,
    deploy_mode: DeployMode,
    linking_mode: LinkingMode,
) -> (String, TrybuildConfig) {
    let source_dir = cargo::manifest_dir().unwrap();
    let source_manifest = dependencies::get_manifest(&source_dir).unwrap();
    let crate_name = source_manifest.package.name.replace("-", "_");

    let is_test = IS_TEST.load(std::sync::atomic::Ordering::Relaxed);

    let generated_code = {
        let _span = tracing::debug_span!(target: "hydro_build", "graph_codegen").entered();
        compile_graph_trybuild(graph, extra_stmts, sidecars, &crate_name, deploy_mode)
    };

    let source = {
        let _span = tracing::debug_span!(target: "hydro_build", "unparse_source").entered();
        prettyplease::unparse(&generated_code)
    };

    let hash = format!("{:X}", Sha256::digest(&source))
        .chars()
        .take(8)
        .collect::<String>();

    let bin_name = if let Some(bin_name_prefix) = bin_name_prefix {
        format!("{}_{}", clean_bin_name_prefix(bin_name_prefix), hash)
    } else {
        hash
    };

    let (project_dir, target_dir, mut cur_bin_enabled_features) = create_trybuild().unwrap();

    // Determine which crate's examples folder to use based on linking mode
    let examples_dir = match linking_mode {
        LinkingMode::Static => path!(project_dir / "examples"),
        #[cfg(any(feature = "deploy", feature = "maelstrom"))]
        LinkingMode::Dynamic => path!(project_dir / "dylib-examples" / "examples"),
    };

    // TODO(shadaj): garbage collect this directory occasionally
    fs::create_dir_all(&examples_dir).unwrap();

    let out_path = path!(examples_dir / format!("{bin_name}.rs"));
    {
        let _span =
            tracing::debug_span!(target: "hydro_build", "write_generated_sources").entered();
        let _concurrent_test_lock = CONCURRENT_TEST_LOCK.lock().unwrap();
        write_atomic(source.as_ref(), &out_path).unwrap();
    }

    if is_test {
        write_staged_source_cached(source_dir.as_ref(), &crate_name, &project_dir);
    }

    if is_test {
        if cur_bin_enabled_features.is_none() {
            cur_bin_enabled_features = Some(vec![]);
        }

        cur_bin_enabled_features
            .as_mut()
            .unwrap()
            .push("hydro___test".to_owned());
    }

    (
        bin_name,
        TrybuildConfig {
            project_dir,
            target_dir,
            features: cur_bin_enabled_features,
            #[cfg(any(feature = "deploy", feature = "maelstrom"))]
            linking_mode,
        },
    )
}

#[cfg(any(feature = "deploy", feature = "maelstrom"))]
pub fn compile_graph_trybuild(
    partitioned_graph: DfirGraph,
    extra_stmts: &[syn::Stmt],
    sidecars: &[syn::Expr],
    crate_name: &str,
    deploy_mode: DeployMode,
) -> syn::File {
    use crate::staging_util::get_this_crate;

    let mut diagnostics = Diagnostics::new();
    let dfir_expr: syn::Expr = syn::parse2(
        partitioned_graph
            .as_code(&quote! { __root_dfir_rs }, true, quote!(), &mut diagnostics)
            .expect("DFIR code generation failed with diagnostics."),
    )
    .unwrap();

    let orig_crate_name = quote::format_ident!("{}", crate_name);
    let trybuild_crate_name_ident = quote::format_ident!("{}_hydro_trybuild", crate_name);
    let root = get_this_crate();
    let tokio_main_ident = format!("{}::runtime_support::tokio", root);
    let dfir_ident = quote::format_ident!("{}", crate::compile::DFIR_IDENT);

    let source_ast: syn::File = match deploy_mode {
        #[cfg(any(feature = "docker_deploy", feature = "ecs_deploy"))]
        DeployMode::Containerized => {
            syn::parse_quote! {
                #![allow(unused_imports, unused_crate_dependencies, missing_docs, non_snake_case, unexpected_cfgs, unfulfilled_lint_expectations)]
                use #trybuild_crate_name_ident::__root as #orig_crate_name;
                use #orig_crate_name::*;
                use #orig_crate_name::__staged::__deps::*;
                use #root::prelude::*;
                use #root::runtime_support::dfir_rs as __root_dfir_rs;
                pub use #orig_crate_name::__staged;

                #[#root::runtime_support::tokio::main(crate = #tokio_main_ident, flavor = "current_thread")]
                async fn main() {
                    #root::telemetry::initialize_tracing();

                    #( #extra_stmts )*

                    let mut #dfir_ident = #dfir_expr;

                    let local_set = #root::runtime_support::tokio::task::LocalSet::new();
                    #(
                        let _ = local_set.spawn_local( #sidecars ); // Uses #dfir_ident
                    )*

                    let _ = local_set.run_until(#dfir_ident.run()).await;
                }
            }
        }
        #[cfg(feature = "deploy")]
        DeployMode::HydroDeploy => {
            syn::parse_quote! {
                #![allow(unused_imports, unused_crate_dependencies, missing_docs, non_snake_case, unexpected_cfgs, unfulfilled_lint_expectations)]
                use #trybuild_crate_name_ident::__root as #orig_crate_name;
                use #orig_crate_name::*;
                use #orig_crate_name::__staged::__deps::*;
                use #root::prelude::*;
                use #root::runtime_support::dfir_rs as __root_dfir_rs;
                pub use #orig_crate_name::__staged;

                #[#root::runtime_support::tokio::main(crate = #tokio_main_ident, flavor = "current_thread")]
                async fn main() {
                    let __hydro_lang_trybuild_cli_owned: #root::runtime_support::hydro_deploy_integration::DeployPorts<#root::__staged::deploy::deploy_runtime::HydroMeta> = #root::runtime_support::launch::init_no_ack_start().await;
                    let __hydro_lang_trybuild_cli = &__hydro_lang_trybuild_cli_owned;

                    #( #extra_stmts )*

                    let mut #dfir_ident = #dfir_expr;
                    println!("ack start");

                    // TODO(mingwei): initialize `tracing` at this point in execution.
                    // After "ack start" is when we can print whatever we want.

                    let local_set = #root::runtime_support::tokio::task::LocalSet::new();
                    #(
                        let _ = local_set.spawn_local( #sidecars ); // Uses #dfir_ident
                    )*

                    let _ = local_set.run_until(#root::runtime_support::launch::run_stdin_commands(
                        async move {
                            #dfir_ident.run().await
                        }
                    )).await;
                }
            }
        }
        #[cfg(feature = "maelstrom")]
        DeployMode::Maelstrom => {
            syn::parse_quote! {
                #![allow(unused_imports, unused_crate_dependencies, missing_docs, non_snake_case, unexpected_cfgs, unfulfilled_lint_expectations)]
                use #trybuild_crate_name_ident::__root as #orig_crate_name;
                use #orig_crate_name::*;
                use #orig_crate_name::__staged::__deps::*;
                use #root::prelude::*;
                use #root::runtime_support::dfir_rs as __root_dfir_rs;
                pub use #orig_crate_name::__staged;

                #[allow(unused)]
                fn __hydro_runtime<'a>(
                    __hydro_lang_maelstrom_meta: &'a #root::__staged::deploy::maelstrom::deploy_runtime_maelstrom::MaelstromMeta
                )
                    -> #root::runtime_support::dfir_rs::scheduled::context::Dfir<impl #root::runtime_support::dfir_rs::scheduled::context::TickClosure + 'a>
                {
                    #( #extra_stmts )*

                    #dfir_expr
                }

                #[#root::runtime_support::tokio::main(crate = #tokio_main_ident, flavor = "current_thread")]
                async fn main() {
                    #root::telemetry::initialize_tracing();

                    // Initialize Maelstrom protocol - read init message and send init_ok
                    let __hydro_lang_maelstrom_meta = #root::__staged::deploy::maelstrom::deploy_runtime_maelstrom::maelstrom_init();

                    let mut #dfir_ident = __hydro_runtime(&__hydro_lang_maelstrom_meta);

                    __hydro_lang_maelstrom_meta.start_receiving(); // start receiving messages after initializing subscribers

                    let local_set = #root::runtime_support::tokio::task::LocalSet::new();
                    #(
                        let _ = local_set.spawn_local( #sidecars ); // Uses #dfir_ident
                    )*

                    let _ = local_set.run_until(#dfir_ident.run()).await;
                }
            }
        }
    };
    source_ast
}

/// Configuration for [`compile_trybuild_example`], the shared concurrent-build
/// entrypoint used by both the simulator and the Maelstrom deployment target.
#[cfg(any(feature = "sim", feature = "maelstrom"))]
pub struct ExampleBuildConfig<'a> {
    /// The trybuild project + target directories and enabled features.
    pub trybuild: TrybuildConfig,
    /// The generated example base name (a content hash). Used as the per-job
    /// directory name and, when [`Self::set_trybuild_lib_name`] is set, as the
    /// value of the `TRYBUILD_LIB_NAME` environment variable.
    pub bin_name: String,
    /// A runtime feature to enable in addition to [`TrybuildConfig::features`]
    /// (e.g. `hydro___feature_sim_runtime` or `hydro___feature_maelstrom_runtime`).
    pub runtime_feature: &'a str,
    /// The cargo `--example` target to build. For the simulator this is the
    /// fixed `sim-dylib` wrapper; for Maelstrom it is the generated `bin_name`.
    pub example_name: String,
    /// If `Some`, override the crate type on the command line (e.g. `cdylib`
    /// for the simulator). `None` builds a normal executable example.
    pub crate_type: Option<&'a str>,
    /// Whether to set `TRYBUILD_LIB_NAME` to `bin_name` (the simulator uses this
    /// for its `include!`-based indirection).
    pub set_trybuild_lib_name: bool,
    /// Whether to honor the `BOLERO_FUZZER` environment variable. Only the
    /// simulator supports fuzzing; other targets should set this to `false`.
    pub allow_fuzz: bool,
}

/// Returns the toolchain's target libdir (where the shared `libstd` lives), memoized.
#[cfg(any(feature = "sim", feature = "maelstrom"))]
fn rustc_target_libdir() -> Option<String> {
    static LIBDIR: std::sync::OnceLock<Option<String>> = std::sync::OnceLock::new();
    LIBDIR
        .get_or_init(|| {
            let rustc = std::env::var("RUSTC").unwrap_or_else(|_| "rustc".to_owned());
            std::process::Command::new(rustc)
                .args(["--print", "target-libdir"])
                .output()
                .ok()
                .filter(|out| out.status.success())
                .map(|out| String::from_utf8(out.stdout).unwrap().trim().to_owned())
        })
        .clone()
}

/// The built artifact returned by [`compile_trybuild_example`].
///
/// Outside coverage runs this is a delete-on-drop temporary copy: every build
/// reuses the same example artifact path in the shared target dir (e.g. the
/// simulator always builds `sim-dylib`, varying only `TRYBUILD_LIB_NAME`), so
/// the caller gets a private copy that a later build cannot clobber.
///
/// In coverage runs the copy is instead persisted (keyed by the generated
/// source's hash, which `bin_name` embeds) under the main target dir's
/// `debug/deps`, and must outlive the process: the coverage mapping needed to
/// resolve profile data lives in the artifact itself, and report-time tools
/// (e.g. `grcov --binary-path target/debug` or `target/debug/deps`, both
/// scanned recursively) run only after all test processes have exited.
pub enum BuiltArtifact {
    /// A delete-on-drop temporary copy of the artifact.
    Temp(tempfile::TempPath),
    /// A persistent copy that survives process exit, for coverage reporters.
    Persisted(PathBuf),
}

impl std::ops::Deref for BuiltArtifact {
    type Target = Path;

    fn deref(&self) -> &Path {
        match self {
            BuiltArtifact::Temp(path) => path,
            BuiltArtifact::Persisted(path) => path,
        }
    }
}

impl BuiltArtifact {
    /// Persist the artifact at its current path, returning that path (the
    /// temporary copy is kept rather than deleted on drop).
    pub fn keep(self) -> Result<PathBuf, std::io::Error> {
        match self {
            BuiltArtifact::Temp(path) => path.keep().map_err(|e| e.error),
            BuiltArtifact::Persisted(path) => Ok(path),
        }
    }
}

/// Compiles a generated trybuild example against the prebuilt dylib crate,
/// using the shared parallel-compilation machinery (per-job target dirs with
/// symlinked shared artifacts, plus a prebuild of the dylib dependencies).
///
/// Returns a [`BuiltArtifact`] handle to a copy of the built artifact (a
/// `cdylib` for the simulator, or an executable for Maelstrom), which the
/// caller can hold onto independently of the shared target directory.
#[cfg(any(feature = "sim", feature = "maelstrom"))]
pub fn compile_trybuild_example(config: ExampleBuildConfig<'_>) -> Result<BuiltArtifact, ()> {
    use std::process::{Command, Stdio};

    let ExampleBuildConfig {
        trybuild,
        bin_name,
        runtime_feature,
        example_name,
        crate_type,
        set_trybuild_lib_name,
        allow_fuzz,
    } = config;

    let is_fuzz = allow_fuzz && std::env::var("BOLERO_FUZZER").is_ok();
    // When RUSTFLAGS is set, our prebuild fingerprint doesn't account for it, so skip the
    // parallel build machinery entirely and build directly into the shared target dir.
    //
    // Coverage instrumentation needs the same treatment, but the host's
    // `-C instrument-coverage` often never reaches this child build: pipelines that inject
    // it via cargo CLI config (`--config build.rustflags=[...]`) or a
    // `RUSTC_WORKSPACE_WRAPPER` leave the test process's environment untouched, so code
    // exercised only through the compiled dylib would silently report zero coverage. The
    // coverage *runtime* does leave a reliable footprint, though: `LLVM_PROFILE_FILE` is
    // set for the test process and inherited here. When present, synthesize
    // `-C instrument-coverage` into the child build's RUSTFLAGS (unless the inherited
    // RUSTFLAGS already carries an instrument-coverage flag, as with `cargo llvm-cov`).
    // Skipping the prebuild machinery keeps this simple, but coverage builds must also
    // be isolated from the shared target dir (see below), and the covmap-bearing
    // artifact is copied to a stable location where coverage reporters can find it.
    // See https://github.com/hydro-project/hydro/issues/3160.
    let mut custom_rustflags = std::env::var("RUSTFLAGS").ok();
    if std::env::var_os("LLVM_PROFILE_FILE").is_some()
        && !custom_rustflags
            .as_deref()
            .is_some_and(|flags| flags.contains("instrument-coverage"))
    {
        let flags = custom_rustflags.get_or_insert_default();
        if !flags.is_empty() {
            flags.push(' ');
        }
        flags.push_str("-Cinstrument-coverage");
    }
    let has_custom_rustflags = custom_rustflags.is_some();
    let coverage_enabled = custom_rustflags
        .as_deref()
        .is_some_and(|flags| flags.contains("instrument-coverage"));

    // Run from dylib-examples crate which has the dylib as a dev-dependency (only if not fuzzing)
    let crate_to_compile = if is_fuzz {
        trybuild.project_dir.clone()
    } else {
        path!(trybuild.project_dir / "dylib-examples")
    };

    let (final_target_dir, _prebuild_guard, _cargo_lock) = if !has_custom_rustflags {
        let prebuild_span =
            tracing::debug_span!(target: "hydro_build", "prebuild", bin_name = %bin_name).entered();
        let shared_debug = trybuild.target_dir.join("debug");
        let jobs_dir = trybuild.target_dir.join("jobs");
        let per_job = hydro_concurrent_cargo::setup_job_dir(&jobs_dir, &bin_name, &shared_debug);

        let mut features: Vec<String> = trybuild.features.clone().unwrap_or_default();
        features.push(runtime_feature.to_owned());

        let staged_paths = vec![
            path!(trybuild.project_dir / "src" / "__staged.rs"),
            path!(trybuild.project_dir / "Cargo.lock"),
            std::env::current_exe().unwrap(),
        ];

        let project_dir = trybuild.project_dir.clone();
        let features_for_closure = features.clone();
        let is_fuzz_for_closure = is_fuzz;

        let (guard, cargo_lock) = hydro_concurrent_cargo::run_prebuild(
            &trybuild.target_dir,
            trybuild.project_dir.file_name().unwrap().to_str().unwrap(),
            &features,
            &staged_paths,
            |prebuild_target| {
                let features_str = features_for_closure.join(",");

                // Prebuild the lib that final builds will link against, which transitively
                // builds the trybuild dylib *as a dependency*. This matters: cargo passes
                // `-C prefer-dynamic` to dylib crates when they are built as dependencies
                // (linking libstd dynamically), but *not* when they are the primary build
                // target — and the two variants share a cargo fingerprint, so whichever is
                // built first wins. Building the dylib as a primary target would poison the
                // cache with a statically-linked-std variant that later fails to link into
                // examples ("cannot satisfy dependencies so `std` only shows up once").
                //
                // In fuzz mode, examples are compiled from the base trybuild crate directly
                // (no dylib-examples), so prebuild the base crate's lib instead.
                let prebuild_crate = if is_fuzz_for_closure {
                    project_dir.clone()
                } else {
                    path!(project_dir / "dylib-examples")
                };
                let mut lib_cmd = Command::new("cargo");
                lib_cmd.current_dir(&prebuild_crate);
                lib_cmd.args(["build", "--locked", "--lib"]);
                lib_cmd.args(["--target-dir", prebuild_target.to_str().unwrap()]);
                lib_cmd.arg("--no-default-features");
                lib_cmd.args(["--features", &features_str]);
                lib_cmd.args(["--config", "build.incremental = false"]);
                lib_cmd.env("STAGELEFT_TRYBUILD_BUILD_STAGED", "1");
                let status = lib_cmd.stdin(Stdio::null()).status().unwrap();
                if !status.success() {
                    panic!("dep prebuild failed");
                }
            },
        );

        // Close the prebuild span before returning the guards: the guards are held for the
        // entire final build, but the prebuild phase (freshness check + possible dep build)
        // ends here.
        drop(prebuild_span);
        (per_job, Some(guard), Some(cargo_lock))
    } else {
        // Coverage builds get an isolated target dir: flags differ from prebuild-mode
        // builds, so building into the shared target dir would clobber the shared
        // artifacts that prebuild-mode builds symlink against, breaking interleaved
        // non-coverage runs (and forcing full rebuilds in both directions).
        let target_dir = if coverage_enabled {
            path!(trybuild.target_dir / "coverage")
        } else {
            trybuild.target_dir.clone()
        };
        (target_dir, None, None)
    };

    // Populate per-job build/ dir right before final build. Hold guard for entire build.
    let _job_build_guard = if !has_custom_rustflags {
        let populate_span =
            tracing::debug_span!(target: "hydro_build", "populate_job_dir", bin_name = %bin_name)
                .entered();
        let shared_debug = trybuild.target_dir.join("debug");
        let guard = hydro_concurrent_cargo::populate_job_build_dir(
            &final_target_dir.join("debug"),
            &shared_debug,
        );
        // Close the populate span here: the returned guard is held until the final build
        // finishes, but the population work itself ends here.
        drop(populate_span);
        Some(guard)
    } else {
        None
    };

    let final_build_span =
        tracing::debug_span!(target: "hydro_build", "final_build", bin_name = %bin_name).entered();
    let mut command = Command::new("cargo");
    command.current_dir(&crate_to_compile);
    command.args([
        "rustc",
        if has_custom_rustflags {
            "--locked"
        } else {
            "--frozen"
        },
    ]);
    command.args(["--example", &example_name]);
    command.args(["--target-dir", final_target_dir.to_str().unwrap()]);
    // Never enable default features: the generated example gets exactly the
    // features it needs via `--features` (plus the runtime feature). This keeps
    // the feature set minimal and deterministic — matching what the deploy
    // backends and the base trybuild crate (which carries the source crate's
    // `default`) would otherwise pull in — and matters for the `is_fuzz` path
    // that builds from the base crate directly.
    command.arg("--no-default-features");
    command.args([
        "--features",
        &trybuild
            .features
            .clone()
            .into_iter()
            .flatten()
            .chain([runtime_feature.to_owned()])
            .collect::<Vec<_>>()
            .join(","),
    ]);
    command.args(["--config", "build.incremental = false"]);
    if let Some(flags) = &custom_rustflags {
        // Covers both inherited RUSTFLAGS (a no-op re-set) and the synthesized
        // instrument-coverage case, where the flag must apply to the whole child build
        // graph — in particular the crate under test, which the generated project pulls
        // in as a path dependency at its real source location (so coverage regions map
        // back to the original files).
        command.env("RUSTFLAGS", flags);
    }
    if let Some(crate_type) = crate_type {
        command.args(["--crate-type", crate_type]);
    }
    command.arg("--message-format=json-diagnostic-rendered-ansi");
    command.env("STAGELEFT_TRYBUILD_BUILD_STAGED", "1");
    if set_trybuild_lib_name {
        command.env("TRYBUILD_LIB_NAME", &bin_name);
    }

    command.arg("--");

    if cfg!(any(target_os = "linux", target_os = "macos")) {
        let debug_path = if let Ok(target) = std::env::var("CARGO_BUILD_TARGET") {
            path!(final_target_dir / target / "debug")
        } else {
            path!(final_target_dir / "debug")
        };

        // The built example links the trybuild dylib dynamically. Bake rpath entries for
        // where cargo places it (debug/ and debug/deps/) and for the toolchain's shared
        // libstd, so the artifact can be loaded/run without LD_LIBRARY_PATH.
        let mut rpaths = vec![debug_path.clone(), path!(debug_path / "deps")];
        if let Some(libdir) = rustc_target_libdir() {
            rpaths.push(PathBuf::from(libdir));
        }
        for rpath in rpaths {
            if cfg!(target_os = "macos") {
                // On macOS rustc may invoke the linker directly (`rust-lld -flavor darwin`),
                // which rejects `-Wl,`-wrapped arguments. Use raw ld64 syntax (`-rpath <path>`
                // as two arguments), which the clang driver also forwards to the linker.
                command.args([
                    "-Clink-arg=-rpath".to_owned(),
                    format!("-Clink-arg={}", rpath.to_str().unwrap()),
                ]);
            } else {
                command.args([format!("-Clink-arg=-Wl,-rpath,{}", rpath.to_str().unwrap())]);
            }
        }

        if cfg!(all(target_os = "linux", target_env = "gnu")) {
            command.arg(
                // https://github.com/rust-lang/rust/issues/91979
                "-Clink-args=-Wl,-z,nodelete",
            );
        }

        if coverage_enabled && cfg!(target_os = "linux") {
            // The dynamic loader resolves the example's trybuild-dylib dependency by
            // soname, and cargo puts the *host* target dir's deps/ on LD_LIBRARY_PATH
            // when running tests — which outranks DT_RUNPATH and would shadow the
            // isolated coverage build's dylib with the same-soname uninstrumented one.
            // Emit legacy DT_RPATH, which outranks LD_LIBRARY_PATH, so the rpath baked
            // above (pointing into the coverage target dir) wins.
            command.arg("-Clink-arg=-Wl,--disable-new-dtags");
        }
    }

    if allow_fuzz && let Ok(fuzzer) = std::env::var("BOLERO_FUZZER") {
        command.env_remove("BOLERO_FUZZER");

        if fuzzer == "libfuzzer" {
            #[cfg(target_os = "macos")]
            {
                command.args(["-Clink-arg=-undefined", "-Clink-arg=dynamic_lookup"]);
            }

            #[cfg(target_os = "linux")]
            {
                command.args(["-Clink-arg=-Wl,--unresolved-symbols=ignore-all"]);
            }
        }
    }

    tracing::debug!(
        target: "hydro_build",
        "final build command (cwd={}): {:?}",
        crate_to_compile.display(),
        command
    );

    let mut spawned = command
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .stdin(Stdio::null())
        .spawn()
        .unwrap();
    let reader = std::io::BufReader::new(spawned.stdout.take().unwrap());
    let stderr_handle = spawned.stderr.take().unwrap();
    let stderr_thread = std::thread::spawn(move || {
        use std::io::Read;
        let mut buf = String::new();
        std::io::BufReader::new(stderr_handle)
            .read_to_string(&mut buf)
            .unwrap();
        buf
    });

    let mut out = Err(());
    for message in cargo_metadata::Message::parse_stream(reader) {
        match message.unwrap() {
            cargo_metadata::Message::CompilerArtifact(artifact) => {
                // unlike dylib, cdylib only exports the explicitly exported symbols
                let is_output = artifact.target.is_example();

                if is_output {
                    let path = artifact.filenames.first().unwrap();
                    let path_buf: PathBuf = path.clone().into();
                    out = Ok(path_buf);
                }
            }
            cargo_metadata::Message::CompilerMessage(mut msg) => {
                // Update the path displayed to enable clicking in IDE.
                // TODO(mingwei): deduplicate code with hydro_deploy rust_crate/build.rs
                if let Some(rendered) = msg.message.rendered.as_mut() {
                    let file_names = msg
                        .message
                        .spans
                        .iter()
                        .map(|s| &s.file_name)
                        .collect::<std::collections::BTreeSet<_>>();
                    for file_name in file_names {
                        *rendered = rendered.replace(
                            file_name,
                            &format!("(full path) {}/{file_name}", trybuild.project_dir.display()),
                        )
                    }
                }
                eprintln!("{}", msg.message);
            }
            cargo_metadata::Message::TextLine(line) => {
                eprintln!("{}", line);
            }
            cargo_metadata::Message::BuildFinished(_) => {}
            cargo_metadata::Message::BuildScriptExecuted(_) => {}
            msg => panic!("Unexpected message type: {:?}", msg),
        }
    }

    spawned.wait().unwrap();
    let stderr_output = stderr_thread.join().unwrap();
    drop(final_build_span);

    // Check for unexpected recompilations — only dylib-examples should be compiled.
    // (Only relevant when prebuild is active, i.e. no custom RUSTFLAGS.)
    if !has_custom_rustflags {
        for line in stderr_output.lines() {
            if line.contains("Compiling") && !line.contains("dylib-examples") {
                panic!(
                    "unexpected recompilation in final build: {line}\nfull stderr:\n{stderr_output}"
                );
            }
        }
    }

    if out.is_err() {
        panic!("final build failed to produce binary.\nstderr:\n{stderr_output}");
    }

    if coverage_enabled {
        // The coverage mapping needed to resolve profile data at report time lives in
        // the artifact itself, and reporters run only after all test processes have
        // exited — so the copy must be persistent, not a delete-on-drop temp file.
        // Persist it keyed by the generated source's hash (embedded in `bin_name`;
        // the shared artifact path itself is reused by every build and would be
        // clobbered), under the main target dir's `debug/deps` so reporters find
        // every mapping whether they scan `target/debug` or the narrower
        // `target/debug/deps` (both are common `grcov --binary-path` conventions,
        // and both are scanned recursively). This persisted copy doubles as the
        // artifact handed to the caller.
        let coverage_dir = path!(trybuild.target_dir / "debug" / "deps" / "hydro-coverage");
        fs::create_dir_all(&coverage_dir).unwrap();
        let artifact_name = out.as_ref().unwrap().file_name().unwrap().to_str().unwrap();
        let persisted = path!(coverage_dir / format!("{bin_name}-{artifact_name}"));
        // Write via a unique temp file + rename so concurrent test processes
        // building the same flow never observe a partially-copied artifact.
        let staging = tempfile::NamedTempFile::new_in(&coverage_dir).unwrap();
        fs::copy(out.as_ref().unwrap(), staging.path()).unwrap();
        staging.persist(&persisted).unwrap();
        return Ok(BuiltArtifact::Persisted(persisted));
    }

    let out_file = tempfile::NamedTempFile::new().unwrap().into_temp_path();
    fs::copy(out.as_ref().unwrap(), &out_file).unwrap();
    Ok(BuiltArtifact::Temp(out_file))
}

/// Generates the inlined `__staged.rs` source for the source crate and writes it into the
/// trybuild project, caching the (expensive) generation across test processes.
///
/// The staged source is a pure function of the source crate's files, and cargo rebuilds the
/// test executable whenever those change, so the identity (path + mtime) of
/// [`std::env::current_exe`] is a sound freshness proxy. All tests in a run share the same
/// executable, so only the first test per test binary pays the ~1s `syn` parse +
/// `prettyplease` unparse; the rest hit the cache. The stamp holds a single entry — the last
/// executable to write `__staged.rs` — so a different test binary of the same crate
/// regenerates on its first test (a no-op rewrite when sources are unchanged). Keeping old
/// entries around would risk a stale match (e.g. an executable restored with an old mtime
/// after another binary regenerated `__staged.rs` from different sources).
pub(crate) fn write_staged_source_cached(source_dir: &Path, crate_name: &str, project_dir: &Path) {
    let _span = tracing::debug_span!(target: "hydro_build", "gen_staged").entered();

    let staged_path = path!(project_dir / "src" / "__staged.rs");
    let stamp_path = path!(project_dir / ".hydro-staged-stamp");

    let exe_stamp = std::env::current_exe().ok().and_then(|exe| {
        let mtime = fs::metadata(&exe)
            .ok()?
            .modified()
            .ok()?
            .duration_since(std::time::SystemTime::UNIX_EPOCH)
            .ok()?
            .as_nanos();
        Some(format!("{}\t{}", exe.display(), mtime))
    });

    let _concurrent_test_lock = CONCURRENT_TEST_LOCK.lock().unwrap();

    fs::create_dir_all(path!(project_dir / "src")).unwrap();

    // Hold an exclusive lock on the stamp file for the entire check + generate: when many
    // test processes start concurrently with a cold cache, the first one generates while the
    // others block here and then hit the cache, instead of all doing the expensive work.
    let mut stamp_file = File::options()
        .read(true)
        .write(true)
        .create(true)
        .truncate(false)
        .open(&stamp_path)
        .unwrap();
    stamp_file.lock().unwrap();

    let mut existing_stamp = String::new();
    if stamp_file.read_to_string(&mut existing_stamp).is_err() {
        existing_stamp.clear();
    }

    if let Some(stamp) = &exe_stamp
        && existing_stamp == *stamp
        && staged_path.exists()
    {
        return;
    }

    let raw_toml_manifest = toml::from_str::<toml::Value>(
        &fs::read_to_string(path!(source_dir / "Cargo.toml")).unwrap(),
    )
    .unwrap();

    let maybe_custom_lib_path = raw_toml_manifest
        .get("lib")
        .and_then(|lib| lib.get("path"))
        .and_then(|path| path.as_str());

    let mut gen_staged = stageleft_tool::gen_staged_trybuild(
        &maybe_custom_lib_path
            .map(|s| path!(source_dir / s))
            .unwrap_or_else(|| path!(source_dir / "src" / "lib.rs")),
        &path!(source_dir / "Cargo.toml"),
        crate_name,
        Some("hydro___test".to_owned()),
    );

    gen_staged.attrs.insert(
        0,
        syn::parse_quote! {
            #![allow(
                unused,
                ambiguous_glob_reexports,
                clippy::suspicious_else_formatting,
                unexpected_cfgs,
                reason = "generated code"
            )]
        },
    );

    let inlined_staged = prettyplease::unparse(&gen_staged);

    write_atomic(inlined_staged.as_bytes(), &staged_path).unwrap();

    if let Some(stamp) = exe_stamp {
        stamp_file.set_len(0).unwrap();
        stamp_file.seek(SeekFrom::Start(0)).unwrap();
        stamp_file.write_all(stamp.as_bytes()).unwrap();
    }
}

pub fn create_trybuild()
-> Result<(PathBuf, PathBuf, Option<Vec<String>>), trybuild_internals_api::error::Error> {
    let _span = tracing::debug_span!(target: "hydro_build", "create_trybuild").entered();
    let Metadata {
        target_directory: target_dir,
        workspace_root: workspace,
        packages,
    } = {
        let _span = tracing::debug_span!(target: "hydro_build", "cargo_metadata").entered();
        cargo::metadata()?
    };

    let source_dir = cargo::manifest_dir()?;
    let mut source_manifest = dependencies::get_manifest(&source_dir)?;

    let mut dev_dependency_features = vec![];
    source_manifest.dev_dependencies.retain(|k, v| {
        if source_manifest.dependencies.contains_key(k) {
            // already a non-dev dependency, so drop the dep and put the features under the test flag
            for feat in &v.features {
                dev_dependency_features.push(format!("{}/{}", k, feat));
            }

            false
        } else {
            // only enable this in test mode, so make it optional otherwise
            dev_dependency_features.push(format!("dep:{k}"));

            v.optional = true;
            true
        }
    });

    // When the example is re-executed from a test binary by `example_test` (signaled via this
    // env var), skip feature discovery: it would pick up the *test* binary's features (e.g.
    // test-only harness features). A real `cargo run --example` invocation has no fingerprint
    // hash in `argv[0]`, so discovery finds nothing there; emulating that here ensures the test
    // exercises the example the same way it actually runs.
    let mut features = if std::env::var("RUNNING_AS_EXAMPLE_TEST").is_ok_and(|v| v == "1") {
        None
    } else {
        features::find()
    };

    let path_dependencies = source_manifest
        .dependencies
        .iter()
        .filter_map(|(name, dep)| {
            let path = dep.path.as_ref()?;
            if packages.iter().any(|p| &p.name == name) {
                // Skip path dependencies coming from the workspace itself
                None
            } else {
                Some(PathDependency {
                    name: name.clone(),
                    normalized_path: path.canonicalize().ok()?,
                })
            }
        })
        .collect();

    let crate_name = source_manifest.package.name.clone();
    let project_dir = path!(target_dir / "hydro_trybuild" / crate_name /);
    fs::create_dir_all(&project_dir)?;

    let project_name = format!("{}-hydro-trybuild", crate_name);
    let mut manifest = Runner::make_manifest(
        &workspace,
        &project_name,
        &source_dir,
        &packages,
        &[],
        source_manifest,
    )?;

    if let Some(enabled_features) = &mut features {
        enabled_features
            .retain(|feature| manifest.features.contains_key(feature) || feature == "default");
    }

    for runtime_feature in HYDRO_RUNTIME_FEATURES {
        manifest.features.insert(
            format!("hydro___feature_{runtime_feature}"),
            vec![format!("hydro_lang/{runtime_feature}")],
        );
    }

    manifest
        .dependencies
        .get_mut("hydro_lang")
        .unwrap()
        .features
        .push("runtime_support".to_owned());

    manifest
        .features
        .insert("hydro___test".to_owned(), dev_dependency_features);

    if manifest
        .workspace
        .as_ref()
        .is_some_and(|w| w.dependencies.is_empty())
    {
        manifest.workspace = None;
    }

    let project = Project {
        dir: project_dir,
        source_dir,
        target_dir,
        name: project_name.clone(),
        update: Update::env()?,
        has_pass: false,
        has_compile_fail: false,
        features,
        workspace,
        path_dependencies,
        manifest,
        keep_going: false,
    };

    {
        let _span = tracing::debug_span!(target: "hydro_build", "write_project_files").entered();
        let _concurrent_test_lock = CONCURRENT_TEST_LOCK.lock().unwrap();

        let project_lock = File::create(path!(project.dir / ".hydro-trybuild-lock"))?;
        project_lock.lock()?;

        fs::create_dir_all(path!(project.dir / "src"))?;
        fs::create_dir_all(path!(project.dir / "examples"))?;

        let crate_name_ident = syn::Ident::new(
            &crate_name.replace("-", "_"),
            proc_macro2::Span::call_site(),
        );

        write_atomic(
            prettyplease::unparse(&syn::parse_quote! {
                #![allow(unused_imports, unused_crate_dependencies, missing_docs, non_snake_case, unexpected_cfgs, unfulfilled_lint_expectations)]

                pub mod __root {
                    pub use #crate_name_ident::*;
                    #[cfg(feature = "hydro___test")]
                    pub use super::__staged;
                }

                #[cfg(feature = "hydro___test")]
                pub mod __staged;
            })
            .as_bytes(),
            &path!(project.dir / "src" / "lib.rs"),
        )
        .unwrap();

        let base_manifest = toml::to_string(&project.manifest)?;

        // Collect feature names for forwarding to dylib and dylib-examples crates
        let feature_names: Vec<_> = project.manifest.features.keys().cloned().collect();

        // Create dylib crate directory
        let dylib_dir = path!(project.dir / "dylib");
        fs::create_dir_all(path!(dylib_dir / "src"))?;

        let trybuild_crate_name_ident = syn::Ident::new(
            &project_name.replace("-", "_"),
            proc_macro2::Span::call_site(),
        );
        write_atomic(
            // The leading comment busts cargo's fingerprint for caches where the dylib was
            // built as a *primary* target (statically linking libstd); it must be built as a
            // dependency (with `-C prefer-dynamic`) for examples to link against it. The
            // linkage variant is not part of cargo's fingerprint, so a content change is
            // needed to force old caches to rebuild.
            [
                "// v2: dylib must be built as a dependency (prefer-dynamic).\n".as_bytes(),
                prettyplease::unparse(&syn::parse_quote! {
                    #![allow(unused_imports, unused_crate_dependencies, missing_docs, non_snake_case, unexpected_cfgs, unfulfilled_lint_expectations)]
                    pub use #trybuild_crate_name_ident::*;
                })
                .as_bytes(),
            ]
            .concat()
            .as_slice(),
            &path!(dylib_dir / "src" / "lib.rs"),
        )?;

        let serialized_edition = toml::to_string(
            &vec![("edition", &project.manifest.package.edition)]
                .into_iter()
                .collect::<std::collections::HashMap<_, _>>(),
        )
        .unwrap();

        // Dylib crate Cargo.toml - only dylib crate-type, with feature forwarding to base crate
        // On Windows, we currently disable dylib compilation due to https://github.com/bevyengine/bevy/pull/2016
        let dylib_features_section = feature_names
            .iter()
            .map(|f| format!("{f} = [\"{project_name}/{f}\"]"))
            .collect::<Vec<_>>()
            .join("\n");

        let dylib_manifest = format!(
            r#"[package]
name = "{project_name}-dylib"
version = "0.0.0"
{}

[lib]
crate-type = ["{}"]

[dependencies]
{project_name} = {{ path = "..", default-features = false }}

[features]
{dylib_features_section}
"#,
            serialized_edition,
            if cfg!(target_os = "windows") {
                "rlib"
            } else {
                "dylib"
            }
        );
        write_atomic(dylib_manifest.as_ref(), &path!(dylib_dir / "Cargo.toml"))?;

        let dylib_examples_dir = path!(project.dir / "dylib-examples");
        fs::create_dir_all(path!(dylib_examples_dir / "src"))?;
        fs::create_dir_all(path!(dylib_examples_dir / "examples"))?;

        write_atomic(
            b"#![allow(unused_crate_dependencies)]\n",
            &path!(dylib_examples_dir / "src" / "lib.rs"),
        )?;

        // Build feature forwarding for dylib-examples - forward through the (renamed) dylib crate
        let features_section = feature_names
            .iter()
            .map(|f| format!("{f} = [\"{project_name}/{f}\"]"))
            .collect::<Vec<_>>()
            .join("\n");

        // Dylib-examples crate Cargo.toml - depends *only* on the dylib crate, renamed to the
        // base crate's package name so that generated examples referencing
        // `{crate}_hydro_trybuild` resolve to the dylib. This is what makes dynamic linking
        // actually kick in: if the base crate were also a direct dependency, rustc would
        // statically link its rlib (and the entire dependency graph) into every example,
        // making the per-example "final compile" link take several seconds. With only the
        // dylib in scope, examples link against the prebuilt shared library instead.
        //
        // The dylib is a regular dependency (not a dev-dependency) so that prebuilding this
        // crate's (empty) lib builds the dylib as a dependency, which is required for cargo
        // to pass `-C prefer-dynamic` (see the prebuild in `compile_trybuild_example`).
        let dylib_examples_manifest = format!(
            r#"[package]
name = "{project_name}-dylib-examples"
version = "0.0.0"
{}

[dependencies]
{project_name} = {{ package = "{project_name}-dylib", path = "../dylib", default-features = false }}

[features]
{features_section}

[[example]]
name = "sim-dylib"
crate-type = ["cdylib"]
"#,
            serialized_edition
        );
        write_atomic(
            dylib_examples_manifest.as_ref(),
            &path!(dylib_examples_dir / "Cargo.toml"),
        )?;

        // sim-dylib.rs for the base crate and dylib-examples crate
        let sim_dylib_contents = prettyplease::unparse(&syn::parse_quote! {
            #![allow(unused_imports, unused_crate_dependencies, missing_docs, non_snake_case, unexpected_cfgs, unfulfilled_lint_expectations)]
            include!(std::concat!(env!("TRYBUILD_LIB_NAME"), ".rs"));
        });
        write_atomic(
            sim_dylib_contents.as_bytes(),
            &path!(project.dir / "examples" / "sim-dylib.rs"),
        )?;
        write_atomic(
            sim_dylib_contents.as_bytes(),
            &path!(dylib_examples_dir / "examples" / "sim-dylib.rs"),
        )?;

        let workspace_manifest = format!(
            r#"{}
[[example]]
name = "sim-dylib"
crate-type = ["cdylib"]

[workspace]
members = ["dylib", "dylib-examples"]
"#,
            base_manifest,
        );

        write_atomic(
            workspace_manifest.as_ref(),
            &path!(project.dir / "Cargo.toml"),
        )?;

        // Compute hash for cache invalidation, covering all generated manifests (the dylib and
        // dylib-examples manifests affect Cargo.lock, so they must participate in the hash)
        let manifest_hash = {
            let mut hasher = Sha256::new();
            hasher.update(&workspace_manifest);
            hasher.update(&dylib_manifest);
            hasher.update(&dylib_examples_manifest);
            format!("{:X}", hasher.finalize())
                .chars()
                .take(8)
                .collect::<String>()
        };

        let workspace_cargo_lock = path!(project.workspace / "Cargo.lock");
        let workspace_cargo_lock_contents_and_hash = if workspace_cargo_lock.exists() {
            let cargo_lock_contents = fs::read_to_string(&workspace_cargo_lock)?;

            let hash = format!("{:X}", Sha256::digest(&cargo_lock_contents))
                .chars()
                .take(8)
                .collect::<String>();

            Some((cargo_lock_contents, hash))
        } else {
            None
        };

        let trybuild_hash = format!(
            "{}-{}",
            manifest_hash,
            workspace_cargo_lock_contents_and_hash
                .as_ref()
                .map(|(_contents, hash)| &**hash)
                .unwrap_or_default()
        );

        if !check_contents(
            trybuild_hash.as_bytes(),
            &path!(project.dir / ".hydro-trybuild-manifest"),
        )
        .is_ok_and(|b| b)
        {
            let _span = tracing::debug_span!(target: "hydro_build", "update_lockfile").entered();
            // this is expensive, so we only do it if the manifest changed
            if let Some((cargo_lock_contents, _)) = workspace_cargo_lock_contents_and_hash {
                // only overwrite when the hash changed, because writing Cargo.lock must be
                // immediately followed by a local `cargo update -w`
                write_atomic(
                    cargo_lock_contents.as_ref(),
                    &path!(project.dir / "Cargo.lock"),
                )?;
            } else {
                let _ = cargo::cargo(&project).arg("generate-lockfile").status();
            }

            // not `--offline` because some new runtime features may be enabled
            std::process::Command::new("cargo")
                .current_dir(&project.dir)
                .args(["update", "-w"]) // -w to not actually update any versions
                .stdout(std::process::Stdio::null())
                .stderr(std::process::Stdio::null())
                .status()
                .unwrap();

            write_atomic(
                trybuild_hash.as_bytes(),
                &path!(project.dir / ".hydro-trybuild-manifest"),
            )?;
        }

        // Create examples folder for base crate (static linking)
        let examples_folder = path!(project.dir / "examples");
        fs::create_dir_all(&examples_folder)?;

        let workspace_dot_cargo_config_toml = path!(project.workspace / ".cargo" / "config.toml");
        if workspace_dot_cargo_config_toml.exists() {
            let dot_cargo_folder = path!(project.dir / ".cargo");
            fs::create_dir_all(&dot_cargo_folder)?;

            write_atomic(
                fs::read_to_string(&workspace_dot_cargo_config_toml)?.as_ref(),
                &path!(dot_cargo_folder / "config.toml"),
            )?;
        }

        let vscode_folder = path!(project.dir / ".vscode");
        fs::create_dir_all(&vscode_folder)?;
        write_atomic(
            include_bytes!("./vscode-trybuild.json"),
            &path!(vscode_folder / "settings.json"),
        )?;
    }

    Ok((
        project.dir.as_ref().into(),
        project.target_dir.as_ref().into(),
        project.features,
    ))
}

fn check_contents(contents: &[u8], path: &Path) -> Result<bool, std::io::Error> {
    let mut file = File::options()
        .read(true)
        .write(false)
        .create(false)
        .truncate(false)
        .open(path)?;
    file.lock()?;

    let mut existing_contents = Vec::new();
    file.read_to_end(&mut existing_contents)?;
    Ok(existing_contents == contents)
}

pub(crate) fn write_atomic(contents: &[u8], path: &Path) -> Result<(), std::io::Error> {
    let mut file = File::options()
        .read(true)
        .write(true)
        .create(true)
        .truncate(false)
        .open(path)?;

    let mut existing_contents = Vec::new();
    file.read_to_end(&mut existing_contents)?;
    if existing_contents != contents {
        file.lock()?;
        file.seek(SeekFrom::Start(0))?;
        file.set_len(0)?;
        file.write_all(contents)?;
    }

    Ok(())
}