ktstr/
export.rs

1//! `cargo ktstr export` — package a registered test as a self-extracting
2//! `.run` file that reproduces the scenario on bare metal without a VM.
3//!
4//! [`export_test`] is the entry point invoked from the test binary's
5//! `#[ctor]` dispatch (see
6//! `crate::test_support::dispatch::maybe_dispatch_export`) when
7//! `cargo ktstr export` exec's the binary with
8//! `--ktstr-export-test=NAME`. The export pipeline locates the named
9//! test in the `KTSTR_TESTS` distributed slice, gathers the
10//! binaries it needs (the running test binary itself via
11//! `current_exe()`, the scheduler binary, and per-test include
12//! files), tarballs them with gzip, and emits a single shell script:
13//!
14//! ```text
15//! #!/bin/bash
16//! ... preamble: root check, prereq check, sched_ext conflict check,
17//!     topology check, arg parsing, mktemp+trap, archive extract,
18//!     scheduler launch, test run ...
19//! __ARCHIVE__
20//! <base64-encoded gzipped tarball>
21//! ```
22//!
23//! The result is `chmod +x` so the operator can `./repro.run`
24//! directly on a target host. `ktstr run --ktstr-test-fn <name>` is
25//! the same dispatch the in-guest test harness already uses
26//! (`test_support::eval` invokes it after VM boot), so the bare-metal
27//! path reuses every existing test entry — no separate registry, no
28//! rebuilt scenarios.
29//!
30//! # Why bare-metal repro?
31//!
32//! The framework's primary execution path runs every test inside a
33//! KVM VM. That gets us deterministic topology, fast spin-up, and
34//! kernel/scheduler isolation; it also abstracts away from real
35//! hardware. When a test fails on bare metal but passes in the VM
36//! (or vice versa) the operator wants to bisect. A self-contained
37//! `.run` file means they can hand the failing test to any host with
38//! a compatible kernel and topology, run it without re-building the
39//! workspace, and capture the output through ordinary stdout/stderr
40//! channels.
41//!
42//! # Out of scope
43//!
44//! - `host_only` tests: they orchestrate cargo invocations and nested
45//!   VMs themselves; running them outside the framework's harness
46//!   isn't useful.
47//! - `bpf_map_write` tests: they need the framework's runtime
48//!   probe-based map-write surface, not yet replicated outside the
49//!   VM dispatch.
50//! - `KernelBuiltin` schedulers: they activate via shell commands
51//!   (`enable` / `disable` slots on the spec) rather than launching a
52//!   userspace binary. The preamble doesn't generate those commands
53//!   in v1; export rejects the variant with an actionable error.
54//!
55//! # Include-file directories
56//!
57//! The framework's full include-file resolver (re-exported as
58//! [`crate::cli::resolve_include_files`]) walks directories
59//! recursively and produces an `archive_path/host_path` map that
60//! preserves directory structure. Export uses a simpler subset:
61//! every included entry must be a regular file, and the archive
62//! layout flattens by basename to `include/<basename>`. Directory
63//! specs error with EISDIR. Recursive directory packaging is a v2
64//! enhancement.
65//!
66//! # Bash-only
67//!
68//! The preamble's heredoc shebang names `/bin/bash` and uses
69//! features bash carries — indexed-array syntax
70//! (`RUN_ARGS=(...)`, `${RUN_ARGS[@]}` expansion) and
71//! `set -o pipefail` (the `o`-form syntax). Bourne / dash /
72//! busybox sh would mis-parse the script; the operator must run
73//! on a host with bash installed.
74
75use std::fs::OpenOptions;
76use std::io::Write;
77use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
78use std::path::{Path, PathBuf};
79
80use anyhow::{Context, Result, bail};
81use base64::Engine;
82use base64::engine::general_purpose::STANDARD as BASE64;
83use flate2::Compression;
84use flate2::write::GzEncoder;
85
86use crate::test_support::{
87    KtstrTestEntry, SchedulerSpec, content_hash, find_test, resolve_scheduler, scratch_dir,
88};
89
90/// Build a self-extracting `.run` file for the given test.
91///
92/// `test_name` must match a `#[ktstr_test]` registration's `name`
93/// field exactly (case-sensitive). Use `cargo nextest list` to
94/// enumerate names; strip the `<binary>::` prefix the way
95/// `cargo ktstr show-thresholds` does.
96///
97/// `output` is the destination path. `None` defaults to
98/// `<test_name>.run` in the current directory. The output file is
99/// written with mode 0o755 so the operator can invoke it directly.
100pub fn export_test(test_name: &str, output: Option<PathBuf>) -> Result<()> {
101    let entry = find_test(test_name)
102        .ok_or_else(|| anyhow::anyhow!("no registered test named '{test_name}'"))?;
103    validate_export_entry(entry)?;
104
105    let test_binary =
106        std::env::current_exe().context("locate the current test binary via /proc/self/exe")?;
107
108    let scheduler_path = resolve_scheduler_for_export(entry)?;
109    let mut include_files = resolve_include_files(entry)?;
110    let config_additions = compute_config_export_additions(entry)
111        .context("resolve scheduler config file for export")?;
112    for addition in &config_additions {
113        include_files.push(addition.host_path.clone());
114    }
115
116    let output_path = output.unwrap_or_else(|| PathBuf::from(format!("{test_name}.run")));
117
118    let archive = build_archive(&test_binary, scheduler_path.as_deref(), &include_files)
119        .context("build embedded gzip tarball")?;
120
121    let preamble = generate_preamble(entry, scheduler_path.is_some(), &config_additions);
122
123    write_runfile(&output_path, &preamble, &archive)
124        .with_context(|| format!("write runfile to {}", output_path.display()))?;
125
126    eprintln!(
127        "wrote {} ({} bytes archive, {} include files)",
128        output_path.display(),
129        archive.len(),
130        include_files.len()
131    );
132    Ok(())
133}
134
135/// Validate the cheap, static eligibility contract shared by the router's
136/// check-only phase and the selected binary's real export phase.
137///
138/// Keep every entry-only rejection here. The router can therefore select an
139/// owner without resolving/building its scheduler or reading/compressing the
140/// large test executable, while the real exporter repeats the exact same
141/// eligibility predicate before performing any expensive work.
142pub(crate) fn validate_export_entry(entry: &KtstrTestEntry) -> Result<()> {
143    let test_name = entry.name;
144    if entry.host_only {
145        bail!(
146            "test '{test_name}' is host_only — it orchestrates cargo / nested VMs \
147             from inside the test body and cannot be reproduced outside the \
148             framework harness. host_only tests are out of scope for export."
149        );
150    }
151    if !entry.bpf_map_write.is_empty() {
152        bail!(
153            "test '{test_name}' uses bpf_map_write — runtime BPF map writes are \
154             driven by the framework's host-side probe machinery, which is not \
155             reproduced bare-metal. bpf_map_write tests are out of scope for v1 \
156             export."
157        );
158    }
159    // KernelBuiltin schedulers don't ship a userspace binary; they
160    // activate via shell commands stored on the spec's `enable` /
161    // `disable` slots. The framework runs those commands in the VM
162    // around the scheduler binary launch (eval/mod.rs's
163    // run_ktstr_test_inner_impl builds sched_enable_cmds /
164    // sched_disable_cmds on the VmBuilder). The
165    // preamble in v1 does not generate equivalent shell commands —
166    // running the .run file on a host without applying those
167    // settings would silently mis-launch the scheduler. Reject with
168    // an actionable diagnostic.
169    if let SchedulerSpec::KernelBuiltin { .. } = &entry.scheduler.binary {
170        bail!(
171            "test '{test_name}' uses a KernelBuiltin scheduler — it activates via \
172             host-side shell commands (`enable` / `disable` slots) rather than a \
173             userspace binary. The export preamble does not yet emit those \
174             commands; KernelBuiltin export is out of scope for v1."
175        );
176    }
177    Ok(())
178}
179
180/// Resolve the scheduler binary for an entry, returning `None` for
181/// EEVDF / kernel-builtin payloads (which don't ship a binary).
182///
183/// Reuses `crate::test_support::eval::resolve_scheduler` so the
184/// resolution matches the in-guest path: `KTSTR_SCHEDULER` env wins;
185/// in cargo-test-mode a `$PATH` lookup is consulted next; otherwise a
186/// fresh `cargo build -p {name}` in the declaring crate's workspace so
187/// an edited scheduler is never exported stale. A build FAILURE is a
188/// hard error — the error propagates (the `?` below), so export rejects
189/// rather than packaging a possibly-stale binary; there is no pre-built
190/// fallback.
191fn resolve_scheduler_for_export(entry: &KtstrTestEntry) -> Result<Option<PathBuf>> {
192    let (path, _source) = resolve_scheduler(
193        &entry.scheduler.binary,
194        entry.scheduler.effective_manifest_dir(),
195    )
196    .with_context(|| format!("resolve scheduler binary for test '{}'", entry.name))?;
197    Ok(path)
198}
199
200/// A scheduler config file or inline content contributes one
201/// host-side file plus one set of CLI arguments to the export.
202///
203/// Mirrors the in-VM path at
204/// `crate::test_support::eval::run_ktstr_test_inner` which calls
205/// `crate::test_support::runtime::config_file_parts` +
206/// `crate::test_support::runtime::config_content_parts` to
207/// resolve the same two slots.
208#[derive(Debug)]
209struct ConfigExportAddition {
210    /// Host-filesystem path of the config file. For
211    /// `scheduler.config_file` (on-disk file), this is the file
212    /// itself. For `entry.config_content` (inline content), this
213    /// is a temp file written under `$TMPDIR` containing the
214    /// content bytes; the export-side caller doesn't differentiate
215    /// — both go through the same `build_archive` path.
216    host_path: PathBuf,
217    /// Shell-ready CLI argument string PREPENDED to the launched
218    /// scheduler's argv at preamble-render time so the rendered
219    /// argv matches the in-VM `run_ktstr_test_inner_impl` ordering
220    /// (`--config FIRST, append_base_sched_args LAST`). Uses
221    /// `"$DIR/include/<basename>"` (with the `$DIR` shell variable
222    /// preserved for runtime expansion by the .run extractor) so
223    /// the path resolves to the operator's extracted .run tree on
224    /// the target host. No leading space — the caller manages
225    /// spacing between additions and the base args.
226    args_shell_prefix: String,
227}
228
229/// Compute the scheduler-config export additions for an entry.
230///
231/// Returns 0, 1, or 2 additions matching the in-VM path's
232/// dual-slot handling:
233///   - `entry.scheduler.config_file` (`Option<host path>`)
234///   - `entry.config_content` (`Option<inline content>`) paired
235///     with `entry.scheduler.config_file_def`
236///     (`Option<(arg_template, guest_path)>`)
237///
238/// Both slots are processed independently; in practice
239/// `crate::test_support::KtstrTestEntry::validate` gates
240/// `config_content` to require a matching `config_file_def` and
241/// rejects an unpaired `config_content`, so the inline path emits
242/// at most one addition. The on-disk path is orthogonal and could
243/// in theory co-exist with the inline path — handled in lockstep
244/// with the in-VM `crate::test_support::eval` behavior so a single
245/// .run runs the scheduler with the same argv as a normal test
246/// invocation.
247fn compute_config_export_additions(entry: &KtstrTestEntry) -> Result<Vec<ConfigExportAddition>> {
248    let mut out = Vec::new();
249    if let Some(addition) = config_file_addition(entry)? {
250        out.push(addition);
251    }
252    if let Some(addition) = config_content_addition(entry)? {
253        out.push(addition);
254    }
255    Ok(out)
256}
257
258/// Translate `entry.scheduler.config_file` (`Option<host path>`)
259/// into a [`ConfigExportAddition`]. Hardcoded `--config` arg
260/// matches the in-VM behavior at
261/// `crate::test_support::runtime::config_file_parts` and the
262/// surrounding push at `crate::test_support::eval`.
263fn config_file_addition(entry: &KtstrTestEntry) -> Result<Option<ConfigExportAddition>> {
264    let Some(config_path) = entry.scheduler.config_file else {
265        return Ok(None);
266    };
267    let host_path = PathBuf::from(config_path);
268    if !host_path.exists() {
269        bail!(
270            "scheduler '{}' declares config_file {} but the file is not present on the host",
271            entry.scheduler.name,
272            host_path.display()
273        );
274    }
275    // Mirror resolve_include_files's directory-reject (export.rs near
276    // is_dir() rejection in that helper): export packs regular files,
277    // so a directory-shaped config_file would silently fail later in
278    // build_archive's `std::fs::read` with a less-actionable EISDIR.
279    if host_path.is_dir() {
280        bail!(
281            "scheduler '{}' declares config_file {} but the path is a directory — \
282             config_file must point at a regular file. Recursive directory packaging \
283             is a v2 enhancement; for now, list a single file or split the directory \
284             contents across `include_files` declarations.",
285            entry.scheduler.name,
286            host_path.display()
287        );
288    }
289    let basename = host_path
290        .file_name()
291        .and_then(|n| n.to_str())
292        .ok_or_else(|| {
293            anyhow::anyhow!(
294                "scheduler config_file {} has no valid basename",
295                host_path.display()
296            )
297        })?
298        .to_string();
299    reject_shell_metacharacters_in_basename(&basename, &host_path.display().to_string())?;
300    let args_shell_prefix = format!("--config \"$DIR/include/{basename}\"");
301    Ok(Some(ConfigExportAddition {
302        host_path,
303        args_shell_prefix,
304    }))
305}
306
307/// Translate `entry.config_content` (`Option<inline content>`) +
308/// `entry.scheduler.config_file_def`
309/// (`Option<(arg_template, guest_path)>`) into a
310/// [`ConfigExportAddition`] by writing the
311/// content bytes to a temp file under `$TMPDIR` and substituting
312/// `{file}` in the arg template with the export-side runtime path
313/// `"$DIR/include/<basename>"`.
314///
315/// The basename derives from the scheduler's declared guest path
316/// (e.g. `/include-files/layers.json` → `layers.json`) so a
317/// scheduler family that declares a stable guest_path naming
318/// convention sees the same basename in the .run archive that it
319/// would see in the in-VM /include-files mount.
320fn config_content_addition(entry: &KtstrTestEntry) -> Result<Option<ConfigExportAddition>> {
321    let Some(content) = entry.config_content else {
322        return Ok(None);
323    };
324    let Some((arg_template, guest_path)) = entry.scheduler.config_file_def else {
325        return Ok(None);
326    };
327    let basename = std::path::Path::new(guest_path)
328        .file_name()
329        .and_then(|n| n.to_str())
330        .ok_or_else(|| {
331            anyhow::anyhow!(
332                "scheduler '{}' config_file_def guest_path '{}' has no valid basename",
333                entry.scheduler.name,
334                guest_path
335            )
336        })?
337        .to_string();
338    reject_shell_metacharacters_in_basename(&basename, guest_path)?;
339    let hash = content_hash(content);
340    // Write to a uniquely-named scratch file inside the shared
341    // process-owned 0o700 scratch directory, then atomic-rename to
342    // the canonical content-addressed path. See
343    // [`crate::test_support::runtime::scratch_dir`] for the
344    // symlink-defense + leak-bound rationale — that helper is
345    // shared with the in-VM `config_content_parts` path so both
346    // sites get the same atexit cleanup + per-process 0o700
347    // directory without divergent maintenance.
348    let dir = scratch_dir();
349    let canonical = dir.join(format!("ktstr-export-config-{hash:016x}-{basename}"));
350    let mut scratch = tempfile::NamedTempFile::new_in(dir)
351        .with_context(|| "create ktstr export-config scratch file")?;
352    scratch
353        .as_file_mut()
354        .write_all(content.as_bytes())
355        .with_context(|| "write inline config_content to scratch")?;
356    scratch.persist(&canonical).with_context(|| {
357        format!(
358            "atomic-rename export-config scratch to {}",
359            canonical.display()
360        )
361    })?;
362    let runtime_path = format!("\"$DIR/include/{basename}\"");
363    let expanded = arg_template.replace("{file}", &runtime_path);
364    Ok(Some(ConfigExportAddition {
365        host_path: canonical,
366        args_shell_prefix: expanded,
367    }))
368}
369
370/// Reject basenames containing shell-metacharacters that would
371/// break the double-quote-interpolation context the addition's
372/// `args_shell_prefix` ends up in (e.g.
373/// `--config "$DIR/include/<basename>"`). Test-author input is
374/// trusted (static string slots), but defense-in-depth catches
375/// any future regression that would land a basename with `"`,
376/// `\`, `$`, or `` ` `` and silently produce a broken .run script.
377fn reject_shell_metacharacters_in_basename(basename: &str, source: &str) -> Result<()> {
378    for c in basename.chars() {
379        if c == '"' || c == '\\' || c == '$' || c == '`' {
380            bail!(
381                "scheduler config file basename {basename:?} (from {source}) contains shell-metacharacter {c:?}; \
382                 this would break the double-quoted .run preamble interpolation. \
383                 Rename the file to use only ASCII letters, digits, `_`, `-`, and `.`."
384            );
385        }
386    }
387    Ok(())
388}
389
390/// Resolve every `all_include_files()` spec to a host-side path.
391///
392/// The framework's full PATH / directory-walking resolver lives at
393/// [`crate::cli::resolve_include_files`] and returns an
394/// `archive_path/host_path` map that preserves recursive directory
395/// structure. Export uses a deliberately simpler subset:
396///   - explicit absolute paths → use as-is when they exist
397///   - explicit relative paths (containing `/` or starting with `.`)
398///     → relative to current dir
399///   - bare names → search `PATH`
400///   - directories → reject with an actionable "is a directory" error
401///     (export packs regular files only; recursive directory
402///     packaging is a v2 enhancement)
403///
404/// The simpler layout (flat `include/<basename>`) keeps the
405/// extracted .run tree predictable for the operator, at the cost of
406/// not handling tests whose include specs name directories.
407///
408/// Missing files are surfaced as a hard error so the operator can
409/// fix the include spec rather than discovering the gap on the
410/// target host.
411fn resolve_include_files(entry: &KtstrTestEntry) -> Result<Vec<PathBuf>> {
412    let mut out = Vec::new();
413    for spec in entry.all_include_files() {
414        let path = if spec.starts_with('/')
415            || spec.starts_with("./")
416            || spec.starts_with("../")
417            || spec.contains('/')
418        {
419            PathBuf::from(spec)
420        } else {
421            // Bare name — search PATH.
422            search_path_for(spec).ok_or_else(|| {
423                anyhow::anyhow!(
424                    "include file '{spec}' not found in PATH (test \
425                     declared it but the host doesn't have it; install or \
426                     supply an absolute path)"
427                )
428            })?
429        };
430        if !path.exists() {
431            bail!("include file does not exist on host: {}", path.display());
432        }
433        // Reject directories explicitly: export packs files only,
434        // and a directory spec would silently fail later inside
435        // `append_file`'s `std::fs::read` with a less-actionable
436        // error message.
437        if path.is_dir() {
438            bail!(
439                "include file '{}' is a directory — export packs regular files \
440                 only. Recursive directory packaging is a v2 enhancement; for \
441                 now, list each file individually in the test's \
442                 `include_files` slot.",
443                path.display()
444            );
445        }
446        out.push(path);
447    }
448    Ok(out)
449}
450
451/// Search `PATH` for an executable named `name`. Returns the first
452/// match. Mirrors the simplest case of the framework's PATH resolver
453/// — sufficient for export's needs since tests typically declare
454/// either bare standard tools (stress-ng, schbench) or paths to
455/// build artifacts.
456///
457/// A "match" requires the candidate to be (a) a regular file and
458/// (b) executable (any of the user/group/other execute bits set).
459/// Without the executable check, a non-binary file with a colliding
460/// name (e.g. a `stress-ng` documentation file in a PATH dir) would
461/// be picked up first and silently fail at .run time when the guest
462/// tries to exec it.
463fn search_path_for(name: &str) -> Option<PathBuf> {
464    let path_var = std::env::var_os("PATH")?;
465    for dir in std::env::split_paths(&path_var) {
466        let candidate = dir.join(name);
467        if !candidate.is_file() {
468            continue;
469        }
470        let executable = candidate
471            .metadata()
472            .map(|m| m.permissions().mode() & 0o111 != 0)
473            .unwrap_or(false);
474        if executable {
475            return Some(candidate);
476        }
477    }
478    None
479}
480
481/// Tar+gzip the binaries into an in-memory blob.
482///
483/// Layout inside the archive:
484///   - `ktstr` — the runner binary (the one calling
485///     [`export_test`])
486///   - `scheduler` — the scheduler binary (when present)
487///   - `include/<basename>` — every include file, flattened by
488///     basename. Collisions on basename are not allowed.
489///
490/// Permissions: every entry is chmod 0755. The `.run` extractor
491/// preserves these, so the operator can invoke them directly under
492/// `$DIR/ktstr` / `$DIR/scheduler` without re-chmod.
493fn build_archive(ktstr: &Path, scheduler: Option<&Path>, includes: &[PathBuf]) -> Result<Vec<u8>> {
494    let buf: Vec<u8> = Vec::new();
495    let gz = GzEncoder::new(buf, Compression::default());
496    let mut tar = tar::Builder::new(gz);
497
498    append_file(&mut tar, ktstr, "ktstr")?;
499    if let Some(s) = scheduler {
500        append_file(&mut tar, s, "scheduler")?;
501    }
502
503    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
504    for inc in includes {
505        let name = inc
506            .file_name()
507            .ok_or_else(|| anyhow::anyhow!("include file has no basename: {}", inc.display()))?
508            .to_string_lossy()
509            .into_owned();
510        if !seen.insert(name.clone()) {
511            bail!(
512                "include-file basename collision: two specs both flatten to \
513                 'include/{name}'. Rename one or use distinct paths."
514            );
515        }
516        let archive_name = format!("include/{name}");
517        append_file(&mut tar, inc, &archive_name)?;
518    }
519
520    let gz = tar.into_inner().context("finalise tar stream")?;
521    let blob = gz.finish().context("finalise gzip stream")?;
522    Ok(blob)
523}
524
525/// Append one host file at `host_path` into `tar` under `archive_name`.
526/// Forces mode 0o755 so the extracted entry is executable on the
527/// target host. Regenerates the tar header rather than reusing the
528/// host's path metadata (which could leak environment-specific
529/// information into the published artifact).
530fn append_file<W: Write>(
531    tar: &mut tar::Builder<W>,
532    host_path: &Path,
533    archive_name: &str,
534) -> Result<()> {
535    let bytes = std::fs::read(host_path)
536        .with_context(|| format!("read {} for archive", host_path.display()))?;
537    crate::tar_util::pack_tar_entry(
538        tar,
539        archive_name,
540        0o755,
541        bytes.len() as u64,
542        bytes.as_slice(),
543    )
544    .with_context(|| format!("append {archive_name} to tar"))?;
545    Ok(())
546}
547
548/// Generate the bash preamble. The output is a complete shell script
549/// up to (but not including) the `__ARCHIVE__` marker; [`write_runfile`]
550/// concatenates the preamble, the marker line, and the base64 archive.
551///
552/// The preamble is verbose by default: a banner identifying test +
553/// scheduler + git provenance, every prereq/conflict check spelled
554/// out with actionable error text, and a security-posture line
555/// warning the operator to inspect the script (everything before
556/// `__ARCHIVE__`) before running on a system they do not control.
557/// `--quiet` suppresses the banner only — error paths still print
558/// so a failing repro is never silent.
559fn generate_preamble(
560    entry: &KtstrTestEntry,
561    has_scheduler: bool,
562    config_additions: &[ConfigExportAddition],
563) -> String {
564    let topology = entry.topology;
565    let need_llcs = topology.llcs;
566    let need_cores = topology.cores_per_llc;
567    let need_threads = topology.threads_per_core;
568    let need_numa = topology.numa_nodes;
569
570    let sched_args_joined = compose_sched_args_joined(entry, config_additions);
571
572    // Defensive shell-quoting on every interpolated runtime value.
573    // The names come from compile-time const slots that are
574    // `[A-Za-z0-9_-]+` in practice today, but interpolating
575    // unquoted lets a future producer regression land an
576    // unescaped value with shell metacharacters in the preamble.
577    // Quoting at the producer is cheap and matches the same defense
578    // applied to extra_sched_args above.
579    let test_name = shell_quote(entry.name);
580    let scheduler_name = shell_quote(entry.scheduler.name);
581    let git_hash = shell_quote(&git_provenance());
582
583    let duration_secs = entry.duration.as_secs();
584    let watchdog_secs = entry.watchdog_timeout.as_secs();
585
586    let scheduler_launch = scheduler_launch_block(has_scheduler, &sched_args_joined);
587
588    let mut script = script_header_and_spec(
589        &test_name,
590        &scheduler_name,
591        &git_hash,
592        need_llcs,
593        need_cores,
594        need_threads,
595        need_numa,
596        duration_secs,
597        watchdog_secs,
598    );
599    script.push_str(&script_arg_parser_and_help());
600    script.push_str(&script_prereq_and_topology_checks());
601    script.push_str(&script_dispatch(&scheduler_launch));
602    script
603}
604
605/// Assemble the scheduler argv string interpolated into the
606/// launch line: config-addition prefixes first, then the joined
607/// base sched-args.
608fn compose_sched_args_joined(
609    entry: &KtstrTestEntry,
610    config_additions: &[ConfigExportAddition],
611) -> String {
612    // Compose scheduler args via the same host-side builder the
613    // in-VM test path uses to assemble the scheduler argv
614    // (`append_base_sched_args`, invoked from both `eval/mod.rs` and
615    // `probe.rs`): fail-fast validation of any user-supplied
616    // `--cell-parent-cgroup` value, then the scheduler def's own
617    // `sched_args`, then per-test `extra_sched_args`. Reusing the
618    // helper keeps the bare-metal repro aligned with a normal test
619    // run for these sources — without it, the export would
620    // silently drop any sched-def baseline args, and a malformed
621    // `--cell-parent-cgroup` would slip past the runtime gate.
622    //
623    // Config-driven schedulers (declared `config_file` and/or
624    // `config_content`) are handled via the `config_additions`
625    // parameter: each addition contributes a shell-ready prefix
626    // that lands BEFORE the joined base args. The ordering matches
627    // the in-VM path at `run_ktstr_test_inner_impl` which pushes
628    // `--config <path>` (and any `config_file_def`-templated arg)
629    // first and then appends `append_base_sched_args` last.
630    // Keeping in-VM and export argv-order in lockstep means an
631    // exported reproducer's scheduler-launch line is byte-similar
632    // (modulo path expansion) to the live test's, so clap parsers
633    // with order-sensitive semantics (e.g. trailing-args,
634    // override-on-conflict) behave identically across both paths.
635    //
636    // Each prefix uses `"$DIR/include/<basename>"` so the path
637    // resolves to the operator's extracted .run tree at script-run
638    // time — the matching include-file is packed into the archive
639    // at `include/<basename>` by [`compute_config_export_additions`]
640    // and [`build_archive`].
641    let mut sched_arg_tokens_raw: Vec<String> = Vec::new();
642    crate::test_support::append_base_sched_args(entry, &mut sched_arg_tokens_raw);
643    let base_joined: String = sched_arg_tokens_raw
644        .iter()
645        .map(|a| shell_quote(a))
646        .collect::<Vec<_>>()
647        .join(" ");
648    let mut sched_args_joined = String::new();
649    for addition in config_additions {
650        if !sched_args_joined.is_empty() {
651            sched_args_joined.push(' ');
652        }
653        sched_args_joined.push_str(&addition.args_shell_prefix);
654    }
655    if !base_joined.is_empty() {
656        if !sched_args_joined.is_empty() {
657            sched_args_joined.push(' ');
658        }
659        sched_args_joined.push_str(&base_joined);
660    }
661    sched_args_joined
662}
663
664/// Build the scheduler-launch shell block (launch + 10s attach-wait
665/// loop) for a scheduler-bearing test, or the empty string for a
666/// binary-kind / EEVDF payload.
667fn scheduler_launch_block(has_scheduler: bool, sched_args_joined: &str) -> String {
668    if has_scheduler {
669        format!(
670            r#"
671# --- scheduler launch ---
672echo "ktstr export: launching scheduler $KTSTR_SCHED_NAME"
673"$DIR/scheduler" {sched_args_joined} &
674SCHED_PID=$!
675
676# Wait up to 10s for the scheduler to attach. The kernel's sysfs
677# layout exposes attach state under two files; both are accepted
678# so the wait loop works on every kernel that ships sched_ext:
679#   - `/sys/kernel/sched_ext/root/ops` — non-empty when a scheduler
680#     is currently attached. Present on every kernel revision that
681#     has sched_ext, but the path moved structurally between early
682#     6.x revisions and the upstream-stabilized layout. Treat the
683#     file's absence as "no scheduler attached" rather than an
684#     error; the secondary check below catches stabilized kernels.
685#   - `/sys/kernel/sched_ext/state` (introduced upstream in 6.12)
686#     reads `enabled` once a scheduler attaches, `disabled`
687#     otherwise. Use as the primary signal where available; it has
688#     a stable wire format across kernel versions.
689# Bail if the scheduler exits before attaching, or if the timeout
690# elapses while the scheduler is still alive but unattached.
691ATTACHED=""
692for _ in $(seq 1 100); do
693    if ! kill -0 "$SCHED_PID" 2>/dev/null; then
694        echo "error: scheduler $KTSTR_SCHED_NAME exited before attaching" >&2
695        wait "$SCHED_PID" || true
696        exit 1
697    fi
698    if [ -r /sys/kernel/sched_ext/state ]; then
699        STATE=$(cat /sys/kernel/sched_ext/state 2>/dev/null || true)
700        if [ "$STATE" = "enabled" ]; then
701            ATTACHED="$STATE"
702            break
703        fi
704    fi
705    if [ -f /sys/kernel/sched_ext/root/ops ]; then
706        OPS=$(cat /sys/kernel/sched_ext/root/ops 2>/dev/null || true)
707        if [ -n "$OPS" ]; then
708            ATTACHED="$OPS"
709            break
710        fi
711    fi
712    sleep 0.1
713done
714if [ -z "$ATTACHED" ]; then
715    echo "error: scheduler $KTSTR_SCHED_NAME launched but did not attach within 10s" >&2
716    echo "       (process is still alive; check kernel log for BPF verifier or load errors)" >&2
717    exit 1
718fi
719"#
720        )
721    } else {
722        // Binary-kind / EEVDF payload — no scheduler.
723        String::new()
724    }
725}
726
727/// Script segment 1: shebang, `set -euo pipefail`, and the frozen
728/// test-specification variable block. Ends with the blank line
729/// before the arg parser.
730#[allow(clippy::too_many_arguments)]
731fn script_header_and_spec(
732    test_name: &str,
733    scheduler_name: &str,
734    git_hash: &str,
735    need_llcs: u32,
736    need_cores: u32,
737    need_threads: u32,
738    need_numa: u32,
739    duration_secs: u64,
740    watchdog_secs: u64,
741) -> String {
742    format!(
743        r#"#!/bin/bash
744# Generated by `cargo ktstr export`. Do not edit; regenerate to update.
745set -euo pipefail
746
747# --- frozen test specification ---
748KTSTR_TEST_NAME={test_name}
749KTSTR_SCHED_NAME={scheduler_name}
750KTSTR_GIT_HASH={git_hash}
751NEED_LLCS={need_llcs}
752NEED_CORES_PER_LLC={need_cores}
753NEED_THREADS_PER_CORE={need_threads}
754NEED_NUMA_NODES={need_numa}
755TEST_DURATION_SECS={duration_secs}
756TEST_WATCHDOG_SECS={watchdog_secs}
757"#
758    )
759}
760
761/// Script segment 2: arg parser, `--help` heredoc, banner, and the
762/// root check. Leads with the blank line after the spec block; ends
763/// with the root-check `fi`. No interpolation vars — every value is
764/// a runtime shell variable.
765fn script_arg_parser_and_help() -> String {
766    String::from(
767        r#"
768QUIET=0
769DURATION_OVERRIDE=""
770WATCHDOG_OVERRIDE=""
771while [ $# -gt 0 ]; do
772    case "$1" in
773        --quiet) QUIET=1; shift ;;
774        --duration) DURATION_OVERRIDE="$2"; shift 2 ;;
775        --watchdog-timeout) WATCHDOG_OVERRIDE="$2"; shift 2 ;;
776        --cpus|--topology|--affinity)
777            echo "error: --$1 is frozen for repro fidelity. Re-export to change." >&2
778            exit 1 ;;
779        -h|--help)
780            cat <<EOF
781Usage: $0 [--quiet] [--duration SECS] [--watchdog-timeout SECS]
782
783Reproduces ktstr test '$KTSTR_TEST_NAME' on bare metal. The script
784extracts an embedded gzip tarball containing the ktstr binary and
785the scheduler binary, then dispatches the test directly without
786booting a VM.
787
788Frozen (cannot be overridden):
789  scheduler         $KTSTR_SCHED_NAME
790  topology          $NEED_NUMA_NODES NUMA / $NEED_LLCS LLCs / $NEED_CORES_PER_LLC cores/LLC / $NEED_THREADS_PER_CORE threads/core
791  scheduler args    (compiled into the script)
792  --cpus, --topology, --affinity reject any override
793
794Overridable:
795  --duration SECS         workload duration (default $TEST_DURATION_SECS)
796  --watchdog-timeout SECS scheduler watchdog (default $TEST_WATCHDOG_SECS)
797  --quiet                 suppress the banner (errors still print)
798
799Requirements:
800  Run as root. The script attaches a kernel BPF scheduler and sets
801  up cgroup v2 subgroups; both need CAP_SYS_ADMIN.
802
803  Host must satisfy the frozen topology (LLCs, cores per LLC,
804  threads per core, NUMA nodes); the script's topology check bails
805  with a specific "host has X, test needs Y" message if not.
806
807  /sys/kernel/sched_ext must exist (kernel built with
808  CONFIG_SCHED_CLASS_EXT) and no other sched_ext scheduler may be
809  attached.
810
811Exit codes:
812  0   test passed
813  1   prerequisite or topology check failed, scheduler attach
814      failed, or test failed
815EOF
816            exit 0 ;;
817        *) echo "error: unknown arg '$1' (use --help)" >&2; exit 1 ;;
818    esac
819done
820
821if [ "$QUIET" != "1" ]; then
822    cat <<EOF
823ktstr export: test=$KTSTR_TEST_NAME scheduler=$KTSTR_SCHED_NAME git=$KTSTR_GIT_HASH
824Generated by cargo ktstr export. This script attaches a kernel BPF scheduler
825and runs as root. Inspect this script (everything before __ARCHIVE__) before
826running on a system you do not control.
827EOF
828fi
829
830# --- root check ---
831if [ "$(id -u)" != "0" ]; then
832    echo "error: must run as root (need CAP_SYS_ADMIN for sched_ext + cgroup ops)" >&2
833    exit 1
834fi
835"#,
836    )
837}
838
839/// Script segment 3: prereq checks, sched_ext conflict check, and
840/// topology check. Leads with the blank line after the root check;
841/// ends with the blank line before the archive-extract block. No
842/// interpolation vars — every value is a runtime shell variable.
843fn script_prereq_and_topology_checks() -> String {
844    String::from(
845        r#"
846# --- prereq checks ---
847if [ ! -d /sys/kernel/sched_ext ]; then
848    echo "error: kernel lacks sched_ext support (no /sys/kernel/sched_ext)" >&2
849    exit 1
850fi
851if [ ! -d /sys/fs/cgroup ]; then
852    echo "error: cgroup2 not mounted at /sys/fs/cgroup" >&2
853    exit 1
854fi
855if ! grep -q '^cgroup2 /sys/fs/cgroup ' /proc/mounts; then
856    echo "error: /sys/fs/cgroup is not a cgroup2 mount" >&2
857    exit 1
858fi
859
860# --- sched_ext conflict check ---
861# Mirror the attach-detection logic below: prefer
862# /sys/kernel/sched_ext/state (stabilized in 6.12) when readable,
863# fall back to /sys/kernel/sched_ext/root/ops otherwise. Either
864# file reporting an attached scheduler aborts here so we don't
865# silently displace someone else's running scheduler.
866if [ -r /sys/kernel/sched_ext/state ]; then
867    CURRENT_STATE=$(cat /sys/kernel/sched_ext/state 2>/dev/null || true)
868    if [ "$CURRENT_STATE" = "enabled" ]; then
869        CURRENT_OPS=""
870        if [ -f /sys/kernel/sched_ext/root/ops ]; then
871            CURRENT_OPS=$(cat /sys/kernel/sched_ext/root/ops 2>/dev/null || true)
872        fi
873        echo "error: another sched_ext scheduler is already attached (state=enabled, ops=${CURRENT_OPS:-unknown})." >&2
874        echo "       Detach it before running this repro (e.g. kill its supervisor)." >&2
875        exit 1
876    fi
877elif [ -f /sys/kernel/sched_ext/root/ops ]; then
878    CURRENT=$(cat /sys/kernel/sched_ext/root/ops 2>/dev/null || true)
879    if [ -n "$CURRENT" ]; then
880        echo "error: another sched_ext scheduler '$CURRENT' is already attached." >&2
881        echo "       Detach it before running this repro (e.g. kill its supervisor)." >&2
882        exit 1
883    fi
884fi
885
886# --- topology check ---
887# LLC count: find the highest cache-index level under cpu0 (index3
888# on most x86, but skylake-x has a dedicated L4 at index4 and ARM
889# machines vary). Sum distinct shared_cpu_lists at that level.
890HIGHEST_INDEX=$(ls -d /sys/devices/system/cpu/cpu0/cache/index* 2>/dev/null \
891    | sort -V | tail -n1 || true)
892if [ -n "$HIGHEST_INDEX" ]; then
893    HIGHEST_LEVEL=$(basename "$HIGHEST_INDEX")
894    HOST_LLCS=$(ls -d /sys/devices/system/cpu/cpu*/cache/$HIGHEST_LEVEL 2>/dev/null \
895        | xargs -I{} cat {}/shared_cpu_list 2>/dev/null \
896        | sort -u | wc -l)
897else
898    HOST_LLCS=0
899fi
900HOST_NUMA=$(ls -d /sys/devices/system/node/node* 2>/dev/null | wc -l || echo 0)
901[ "$HOST_NUMA" -lt 1 ] && HOST_NUMA=1
902
903# Cores per LLC: count distinct core_id values among cpus that share
904# the highest-level cache with cpu0. threads per core: count cpus
905# that share the same core_id within one LLC.
906if [ -n "$HIGHEST_INDEX" ]; then
907    CPU0_LLC=$(cat "$HIGHEST_INDEX/shared_cpu_list" 2>/dev/null || echo "")
908else
909    CPU0_LLC=""
910fi
911HOST_CORES_PER_LLC=0
912HOST_THREADS_PER_CORE=0
913if [ -n "$CPU0_LLC" ]; then
914    # Expand cpu list ranges (e.g. "0-3,8-11") into individual ids.
915    CPU_IDS=$(echo "$CPU0_LLC" | tr ',' '\n' | while read range; do
916        if [ -z "$range" ]; then continue; fi
917        if echo "$range" | grep -q '-'; then
918            start=$(echo "$range" | cut -d- -f1)
919            end=$(echo "$range" | cut -d- -f2)
920            seq "$start" "$end"
921        else
922            echo "$range"
923        fi
924    done)
925    HOST_CORES_PER_LLC=$(for id in $CPU_IDS; do
926        cat "/sys/devices/system/cpu/cpu$id/topology/core_id" 2>/dev/null || echo
927    done | sort -u | wc -l)
928    CPU0_CORE=$(cat /sys/devices/system/cpu/cpu0/topology/core_id 2>/dev/null || echo)
929    if [ -n "$CPU0_CORE" ]; then
930        HOST_THREADS_PER_CORE=$(for id in $CPU_IDS; do
931            this_core=$(cat "/sys/devices/system/cpu/cpu$id/topology/core_id" 2>/dev/null || echo)
932            if [ "$this_core" = "$CPU0_CORE" ]; then echo "$id"; fi
933        done | wc -l)
934    fi
935fi
936
937if [ "$HOST_LLCS" = "0" ]; then
938    echo "warning: could not detect host LLC count from sysfs (no cache/index* found for cpu0); the topology check below will fail" >&2
939fi
940if [ "$HOST_LLCS" -lt "$NEED_LLCS" ]; then
941    echo "error: host has $HOST_LLCS LLCs, test needs $NEED_LLCS" >&2
942    exit 1
943fi
944if [ "$HOST_NUMA" -lt "$NEED_NUMA_NODES" ]; then
945    echo "error: host has $HOST_NUMA NUMA nodes, test needs $NEED_NUMA_NODES" >&2
946    exit 1
947fi
948if [ "$HOST_CORES_PER_LLC" -gt 0 ] && [ "$HOST_CORES_PER_LLC" -lt "$NEED_CORES_PER_LLC" ]; then
949    echo "error: host has $HOST_CORES_PER_LLC cores per LLC, test needs $NEED_CORES_PER_LLC" >&2
950    exit 1
951fi
952if [ "$HOST_THREADS_PER_CORE" -gt 0 ] && [ "$HOST_THREADS_PER_CORE" -lt "$NEED_THREADS_PER_CORE" ]; then
953    echo "error: host has $HOST_THREADS_PER_CORE threads per core, test needs $NEED_THREADS_PER_CORE" >&2
954    exit 1
955fi
956"#,
957    )
958}
959
960/// Script segment 4: archive extraction, the EXIT-trap cleanup,
961/// base64 decode, the interpolated scheduler-launch block, and the
962/// in-process test dispatch. Leads with the blank line after the
963/// topology check. `{scheduler_launch}` is the only interpolation;
964/// every other value is a runtime shell variable.
965fn script_dispatch(scheduler_launch: &str) -> String {
966    format!(
967        r#"
968# --- extract embedded archive ---
969DIR=$(mktemp -d -t ktstr-export-XXXXXX)
970chmod 700 "$DIR"
971# The ktstr in-process dispatch creates its cgroup tree under
972# /sys/fs/cgroup/ktstr — the export-relevant path goes through the
973# ctor early-dispatch into `test_support::probe::build_dispatch_ctx_parts`
974# which calls `test_support::args::resolve_cgroup_root` (fn at
975# args.rs:336, `/sys/fs/cgroup/ktstr` fallback at args.rs:377), and
976# the in-VM init follows the same convention.
977# Capture the path here so the trap teardown can clean any subgroups
978# the dispatch created. The rmdir must walk depth-first because
979# cgroup v2 forbids rmdir on a subtree that still contains child
980# groups.
981#
982# WARNING: this cleanup removes ALL subgroups under
983# /sys/fs/cgroup/ktstr, including those created by concurrent
984# ktstr processes. Do not run multiple ktstr workloads on the same
985# host simultaneously.
986KTSTR_CGROUP_PARENT="/sys/fs/cgroup/ktstr"
987SCHED_PID=""
988cleanup() {{
989    if [ -n "$SCHED_PID" ]; then
990        kill "$SCHED_PID" 2>/dev/null || true
991        wait "$SCHED_PID" 2>/dev/null || true
992    fi
993    rm -rf "$DIR"
994    # Cgroup teardown: depth-first rmdir over every subgroup the
995    # test created. cgroup v2's interface files (cgroup.procs,
996    # cgroup.controllers, ...) are auto-removed when their parent
997    # directory rmdirs, so a recursive `rm -rf` is wrong (would
998    # ENOTEMPTY on every interior node). `find -depth` visits
999    # leaves before parents; rmdir succeeds at each step because
1000    # children are gone. Errors swallowed via `2>/dev/null` so a
1001    # cleanup race with another tool doesn't bleed into the test
1002    # exit status.
1003    if [ -d "$KTSTR_CGROUP_PARENT" ]; then
1004        find "$KTSTR_CGROUP_PARENT" -mindepth 1 -depth -type d \
1005            -exec rmdir {{}} + 2>/dev/null || true
1006        rmdir "$KTSTR_CGROUP_PARENT" 2>/dev/null || true
1007    fi
1008}}
1009trap cleanup EXIT
1010
1011# Decode embedded base64 archive (everything after __ARCHIVE__).
1012sed -n '/^__ARCHIVE__$/,$p' "$0" | tail -n+2 | base64 -d | tar xz -C "$DIR"
1013
1014if [ ! -x "$DIR/ktstr" ]; then
1015    echo "error: extracted ktstr binary missing or not executable" >&2
1016    exit 1
1017fi
1018{scheduler_launch}
1019# --- run the test ---
1020# `--ktstr-test-fn $KTSTR_TEST_NAME` is intercepted by the ktstr
1021# binary's `#[ctor(unsafe)] ktstr_test_early_dispatch` (in
1022# `src/test_support/dispatch.rs`), which fires from `.init_array`
1023# BEFORE `main()` runs. The ctor reads the argv directly via
1024# `extract_test_fn_arg` and dispatches via
1025# `maybe_dispatch_vm_test_with_args` (in
1026# `src/test_support/probe.rs`) which calls `(entry.func)(&ctx)`
1027# directly, then exits the process on completion. The leading
1028# `"run"` token is cosmetic — it's never parsed because the ctor
1029# exits before clap sees it. This early-dispatch path is the
1030# contract for in-process repro and is load-bearing: a future
1031# refactor that moves dispatch out of the ctor must keep an
1032# equivalent argv-intercept path in place, or this preamble must
1033# change to match the new dispatch shape.
1034#
1035# IMPORTANT: do NOT use `exec` here. `exec` replaces the bash
1036# shell with the ktstr binary and DESTROYS the EXIT trap before
1037# it can fire — leaking the scheduler PID, the tempdir, and the
1038# cgroup tree. Run as a child and forward the exit code so the
1039# trap fires on bash exit.
1040RUN_ARGS=("run" "--ktstr-test-fn" "$KTSTR_TEST_NAME")
1041if [ -n "$DURATION_OVERRIDE" ]; then
1042    RUN_ARGS+=("--duration" "$DURATION_OVERRIDE")
1043fi
1044if [ -n "$WATCHDOG_OVERRIDE" ]; then
1045    RUN_ARGS+=("--watchdog-timeout" "$WATCHDOG_OVERRIDE")
1046fi
1047# Disable errexit just for the ktstr invocation so a non-zero
1048# exit from the test (the legitimate "test failed" outcome)
1049# propagates as our exit code instead of triggering set -e and
1050# bypassing the cleanup. The `|| true` would also keep going,
1051# but `set +e` makes the intent explicit.
1052set +e
1053"$DIR/ktstr" "${{RUN_ARGS[@]}}"
1054EXIT_CODE=$?
1055set -e
1056exit $EXIT_CODE
1057"#
1058    )
1059}
1060
1061/// Best-effort git provenance: the project HEAD short hex, or
1062/// `"unknown"` when not in a git checkout. Stamped into the
1063/// preamble's banner so an operator running an old `.run` can tell
1064/// what code was packaged.
1065///
1066/// Uses gix in-process rather than shelling out to `git rev-parse`.
1067/// Same shape as [`crate::fetch::inspect_local_source_state`]: walk
1068/// up from the current directory with `gix::discover`, read the head
1069/// id, format and truncate. No process fork, no PATH dependency —
1070/// the export pipeline never depends on a `git` binary being
1071/// installed on the host running `cargo ktstr export`.
1072fn git_provenance() -> String {
1073    std::env::current_dir()
1074        .ok()
1075        .and_then(|cwd| gix::discover(&cwd).ok())
1076        .and_then(|repo| {
1077            // `head_id()` returns an Id<'_> borrowing `repo`, so format
1078            // and truncate to an owned String inside the same scope as
1079            // `repo` to satisfy the borrow checker. Mirrors the
1080            // head_id/format/truncate pattern in
1081            // `crate::fetch::inspect_local_source_state`.
1082            repo.head_id()
1083                .ok()
1084                .map(|id| format!("{id}").chars().take(7).collect::<String>())
1085        })
1086        .unwrap_or_else(|| "unknown".to_string())
1087}
1088
1089/// Single-quote a shell argument. Embedded single quotes are
1090/// terminated, escaped via `'\''`, and re-opened. Sufficient for
1091/// passing arbitrary `extra_sched_args` strings through the
1092/// preamble's word-split positional context.
1093///
1094/// Empty input is quoted to `''` rather than left as the empty
1095/// string. An unquoted empty arg word-splits to nothing in bash,
1096/// silently dropping the slot — quoting preserves the empty
1097/// positional argument so the scheduler's argv index is preserved.
1098fn shell_quote(s: &str) -> String {
1099    if s.is_empty() {
1100        return "''".to_string();
1101    }
1102    if !s.contains('\'')
1103        && s.chars()
1104            .all(|c| c.is_ascii_alphanumeric() || "._-+=/:".contains(c))
1105    {
1106        return s.to_string();
1107    }
1108    let mut out = String::with_capacity(s.len() + 2);
1109    out.push('\'');
1110    for c in s.chars() {
1111        if c == '\'' {
1112            out.push_str("'\\''");
1113        } else {
1114            out.push(c);
1115        }
1116    }
1117    out.push('\'');
1118    out
1119}
1120
1121/// Write the final `.run` file: preamble bytes, the `__ARCHIVE__`
1122/// marker line, then the base64-encoded archive split into 76-column
1123/// lines (POSIX-friendly width). Sets executable mode 0o755.
1124fn write_runfile(path: &Path, preamble: &str, archive: &[u8]) -> Result<()> {
1125    let mut f = OpenOptions::new()
1126        .write(true)
1127        .create(true)
1128        .truncate(true)
1129        .mode(0o755)
1130        .open(path)
1131        .with_context(|| format!("open {} for write", path.display()))?;
1132
1133    f.write_all(preamble.as_bytes()).context("write preamble")?;
1134    f.write_all(b"__ARCHIVE__\n")
1135        .context("write archive marker")?;
1136
1137    let encoded = BASE64.encode(archive);
1138    // Split into 76-char lines so the file works through legacy
1139    // text-only transports (email MIME, some line editors).
1140    for chunk in encoded.as_bytes().chunks(76) {
1141        f.write_all(chunk).context("write base64 chunk")?;
1142        f.write_all(b"\n").context("write newline")?;
1143    }
1144    f.sync_all().context("fsync runfile")?;
1145    drop(f);
1146    let mut perms = std::fs::metadata(path)
1147        .with_context(|| format!("stat {}", path.display()))?
1148        .permissions();
1149    perms.set_mode(0o755);
1150    std::fs::set_permissions(path, perms)
1151        .with_context(|| format!("chmod 755 {}", path.display()))?;
1152    Ok(())
1153}
1154
1155#[cfg(test)]
1156#[path = "export_tests.rs"]
1157mod tests;