rom-weaver

Environment variables

This page lists the supported runtime variables and the main developer overrides. Most runtime numbers and booleans are parsed by rom_weaver_core::env; the table notes exceptions.

Command-scoped configuration

Patch metadata and browser command arguments are command inputs, not ambient environment configuration. SOLID metadata is supplied with the patch create --solid-* flags documented in patch creation metadata, or with the corresponding solid_* fields on a typed WASM PatchCreateCommand.

The browser OPFS runner likewise has no constructor-level program, argv0, or env options. WASI argv0 is always rom-weaver. A command may still supply env in its per-run options when it needs one of the runtime knobs below.

Runtime knobs

Variable Type Default Read at Purpose
ROM_WEAVER_LOG filter string unset crates/rom-weaver-cli/src/lib.rs Tracing filter spec (e.g. rom_weaver_app=trace); also honored via RUST_LOG when no explicit CLI log level is selected.
ROM_WEAVER_DATA_DIR directory path platform data directory + rom-weaver crates/rom-weaver-cli/src/identify_database.rs Parent of the native identify database's identify directory. --database-dir overrides the full database path.
ROM_WEAVER_CHEAT_DATABASE directory path unset crates/rom-weaver-cli/src/cheat_database.rs Cheat shard directory used when --cheat-database is absent. It wins over the discovered data directories, even when it lacks the needed shard.
ROM_WEAVER_MAN_DIR directory path $XDG_DATA_HOME/man/man1 (else ~/.local/share/man/man1) on Unix, %LOCALAPPDATA%\rom-weaver\docs\man on Windows crates/rom-weaver-cli/src/manpages.rs Install directory for rom-weaver man --install. --man-dir overrides it.
ROM_WEAVER_PATCH_IN_MEMORY_LIMIT u64 (bytes) 256 MiB crates/rom-weaver-patches/src/lib.rs Cap for buffering patch apply/create in memory; above it patches stream. On native builds only, sparse PPF/MOD/APS/APSGBA patches stream at 32 MiB and above (PAT at 64 MiB), even under the cap. 0 forces streaming.
ROM_WEAVER_DISC_TRACK_IN_MEMORY_LIMIT u64 (bytes) 256 MiB crates/rom-weaver-cli/src/patch_apply_disc.rs Cap for buffering a single freshly produced disc track in memory during compression instead of a temp file (only ever bounds one track, never the whole disc). 0 forces temporary-file storage.
ROM_WEAVER_MEMORY_LIMIT_BYTES u64 (bytes) physical RAM on Linux and macOS, 1 GiB on wasm, unlimited elsewhere crates/rom-weaver-core/src/threads.rs Memory the engine may use. Three quarters of it caps how many 7z solid blocks decode at once, because each decoding worker allocates its own dictionary, sized to the block's output when that is smaller than the declared size. The browser runner sets it to the shared memory maximum the browser granted.
ROM_WEAVER_ZIP_ZSTD_MEM_BUDGET_MB u64 (MiB) physical RAM / 2 (1-2 GiB fallback) crates/rom-weaver-containers/src/handlers/zip.rs Memory budget that caps zstd multi-thread job count for zip create.
ROM_WEAVER_7Z_MEM_BUDGET_MB u64 (MiB) physical RAM / 2 (1 GiB wasm / 2 GiB native fallback) crates/rom-weaver-containers/src/handlers/sevenz.rs Memory budget that caps the LZMA2 multi-thread count for 7z create. Invalid text is ignored.
ROM_WEAVER_7Z_ENCODER liblzma 7-Zip SDK encoder handlers/sevenz.rs planner and archive_write_set_format_7zip.c writer (raw getenv) Selects the seeded parallel-block liblzma LZMA2 encoder for 7z create instead of the default 7-Zip SDK one. Output is slightly smaller than 7zz's, at a large time cost on inputs bigger than the dictionary; any other value keeps the SDK encoder. Native builds only - the wasm build never compiles the SDK encoder in, so it always uses liblzma and ignores this.

Test / build-only knobs

Not for production use.

Variable Read at Purpose
ROM_WEAVER_TEST_THREAD_POOL_FAIL crates/rom-weaver-core/src/threads.rs Forces a thread-pool build failure to exercise the single-thread fallback.
ROM_WEAVER_TEST_TMPDIR container test harness Overrides the temp dir used by container tests.
ROM_WEAVER_WASI_THREADS crate build.rs scripts Forces the rom_weaver_wasi_threads cfg on (otherwise gated on the wasm32-wasip1-threads target).
ROM_WEAVER_LZMA_ASM crates/rom-weaver-containers/libarchive/build.rs Names the MASM-compatible assembler used for the x86-64 LZMA decode loop, replacing the jwasm/asmc/asmc64/uasm/ml64 probe. Missing or failing assemblers fall back to the portable C loop with a build warning, never an error. Read only on x86-64 targets.
ROM_WEAVER_UASM crates/rom-weaver-containers/libarchive/build.rs Alias for ROM_WEAVER_LZMA_ASM. Both are honoured; when both are set ROM_WEAVER_LZMA_ASM is tried first and ROM_WEAVER_UASM is the fallback candidate.

Browser / PWA runtime handles (window.* globals)

These JavaScript globals expose diagnostics and service-worker controls. They are separate from process environment variables.

Global Direction Set/read at Purpose
window.ROM_WEAVER_CONSOLE_LOGS exposed by app webapp/console-log-capture.ts Console-log capture API (getReport/copy/clear/...) for debugging.
window.ROM_WEAVER_SERVICE_WORKER exposed by app webapp/webapp.ts Service-worker cache controls (forceCacheAndReload/getState/...).
window.ROM_WEAVER_BROWSER_DIAGNOSTICS exposed by app webapp/browser-runtime-diagnostics.ts Browser runtime diagnostics handle.
window.ROM_WEAVER_MOBILE_SAFARI_DIAGNOSTICS exposed by app webapp/browser-runtime-diagnostics.ts Mobile-Safari runtime diagnostics handle (alias of the same diagnostics API).
window.ROM_WEAVER_IOS_SAFARI_MATRIX exposed by app webapp/mobile-safari-matrix.ts iOS-Safari format-matrix diagnostic harness API (diagnostic page only).

Webapp build/test/bench tooling (*.mjs)

The webapp build/test/bench also reads a ROM_WEAVER_* family in *.mjs (vite/vitest configs, scripts) - e.g. ROM_WEAVER_APP_VERSION, ROM_WEAVER_COMMIT_HASH, ROM_WEAVER_WASM_ARTIFACT_DIR, ROM_WEAVER_COVERAGE, ROM_WEAVER_BROWSER, ROM_WEAVER_WASM_STRESS_1GB, and the ROM_WEAVER_WASM_BENCH* benchmark toggles. Those are front-end tooling knobs, not part of the Rust runtime surface above.