Canonical: https://rom-weaver.com/docs/environment-variables

# 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.

<!-- START doctoc -->
## Table of contents

- [Command-scoped configuration](<#command-scoped-configuration>)
- [Runtime knobs](<#runtime-knobs>)
- [Test / build-only knobs](<#test--build-only-knobs>)
- [Browser / PWA runtime handles (`window.*` globals)](<#browser--pwa-runtime-handles-window-globals>)
- [Webapp build/test/bench tooling (`*.mjs`)](<#webapp-buildtestbench-tooling-mjs>)

<!-- END doctoc -->

## 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](<https://rom-weaver.com/docs/cli.md#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.