Quick Reference
| Goal | Command / Path | Notes |
|---|---|---|
| Format everything | conda run -n orbitron-dev cargo fmt --all |
Run before sending PRs; CI enforces formatting. |
| Run focused viewer tests | conda run -n orbitron-dev cargo nextest run -p orbitron-ui-shell start_new_session_uses_truly_empty_scene |
A filter that matches nothing exits 0 having run nothing, so check the reported test count. |
| Launch viewer from workspace root | conda run -n orbitron-dev cargo run --release -p orbitron-cli --features gui -- view fixtures/benzene.xyz |
Mirrors the user workflow in the User Guide (§3 Graphical Viewer). |
| GUI smoke test | ORBITRON_AUTOCLOSE_MS=200 conda run -n orbitron-dev cargo nextest run -p orbitron-cli --features gui --test view |
Opens the desktop viewer in a blank session and auto-closes after about 200 ms. |
| TUI smoke test | ORBITRON_TUI_AUTOCLOSE=1 conda run -n orbitron-dev cargo nextest run -p orbitron-cli --features tui --test view |
Loads the terminal UI with an empty scene and exits immediately. |
| TUI render benchmark | conda run -n orbitron-dev cargo bench -p orbitron-tui --bench render |
Profiles ASCII glyph/bond rendering via Criterion. |
| Build Python bridge | conda run --no-capture-output -n orbitron-dev python -m pip install -e extensions/python-bridge |
Uses the PEP 517 wrapper, which builds and stages the widget and WASM assets. maturin develop skips those steps. |
| Inspect selection engine | conda run -n orbitron-dev cargo run --release -p orbitron-cli -- select "element C and within_atom(1, 3.0)" fixtures/benzene.xyz |
Uses the query stack described in §5.2. |
| Generate release bundle (macOS) | bash scripts/build-macos-release.sh (or see scripts/BUILD_RELEASE.md) |
Wraps the steps in Packaging & Distribution. |
Environment Variables
| Variable | Applies to | Effect |
|---|---|---|
RUST_LOG |
desktop viewer | Tracing filter for stderr (default warn; e.g. RUST_LOG=debug). The CLI ignores it; use --log-level there. |
WGPU_BACKEND |
desktop, CLI render | Force a wgpu backend (gl, vulkan, metal) when the default is unavailable. See the Debugging Playbook. |
RAYON_NUM_THREADS |
all native crates | Cap Rayon’s global thread pool. =1 pins parallel paths (e.g. orbital grid evaluation) to one worker for approximate serial-vs-parallel comparisons. |
ORBITRON_CANONICAL_CACHE |
CLI, desktop | Override the canonical-bundle cache directory. |
ORBITRON_CLI_PROGRESS |
CLI | =0 disables progress bars (set automatically by --no-progress and --quiet). |
ORBITRON_CLI_QUIET |
CLI | =1 suppresses the startup banner (set automatically by --quiet). |
ORBITRON_VASP_SKIP_VOLUMETRIC |
parsers | Skip volumetric payloads in VASP output; faster loads when densities are not needed. |
ORBITRON_MSAA_SAMPLES |
desktop renderer | Request an MSAA sample count (1, 2, 4, 8, or 16; clamped to a power of two and to what the adapter supports). |
ORBITRON_LIGHTING_PRESET |
desktop | Apply a named lighting preset at startup (case-insensitive). |
ORBITRON_NO_SPECULAR |
desktop | Zero both specular intensities for a matte look. |
ORBITRON_SYNC_LOAD |
desktop | Load the startup file synchronously before first paint. |
ORBITRON_AUTOCLOSE_MS |
GUI smoke tests | Auto-close the viewer after N milliseconds (CI-friendly). |
ORBITRON_TUI_AUTOCLOSE |
TUI smoke tests | Exit immediately after load (CI-friendly). |
ORBITRON_TUI_NO_SPLASH |
TUI | Skip the splash screen. |
ORBITRON_TUI_FPS |
TUI | Show the frame rate in the molecule panel title. |
ORBITRON_REGEN_BASELINES |
render-parity tests | Regenerate golden images instead of diffing against them. |
ORBITRON_RENDER_PARITY_REQUIRE_GPU |
render-parity tests | =1 turns “no usable GPU adapter” into a failure instead of a skip. CI’s lavapipe job sets it. |
ORBITRON_SKIP_VIEWER_BUILD |
stage_viewer_assets.sh |
=1 stages the existing viewer/wasm artifacts without re-running trunk + esbuild. |
ORBITRON_SKIP_VIEWER_ASSETS |
wheel build backend | =1 builds the wheel without the staged viewer bundle. |
ORBITRON_SKIP_WIDGET_BUILD |
wheel build backend | =1 skips the Jupyter widget frontend build. |
ORBITRON_NO_MMAP |
parsers | Any non-empty value disables memory-mapped reads and falls back to buffered I/O. |
ORBITRON_INCHI_BINARY |
orbitron-inchi oracle tests |
Path to a reference inchi-1 executable; the #[ignore]d oracle tests need it. |
ORBITRON_SKIP_GUI_TESTS / ORBITRON_FORCE_GUI_TESTS |
GUI smoke tests | Force the display guard off / on regardless of the detected environment. |
CARGO_BUILD_JOBS |
all builds | Cap rustc parallelism (16 on the 24-core dev box). Does nothing once nextest starts running tests — see .config/nextest.toml. |
Smoke Test Checklist (Pre-release)
conda run -n orbitron-dev cargo run --release -p orbitron-cli --bin orbitron -- info io/pipelines/tests/fixtures/xyz/water.xyz --jsonconda run -n orbitron-dev cargo run --release -p orbitron-cli --bin orbitron -- analyze geometry fixtures/benzene.xyz --jsonconda run -n orbitron-dev cargo run --release -p orbitron-cli --features gui --bin orbitron -- view --blankconda run -n orbitron-dev cargo run --release -p orbitron-cli --features gui --bin orbitron -- view io/pipelines/tests/fixtures/xyz/water.xyzmkdir -p ~/scratch/orbitron-smoke && conda run -n orbitron-dev cargo run --release -p orbitron-cli --bin orbitron -- render --output ~/scratch/orbitron-smoke/water.png io/pipelines/tests/fixtures/xyz/water.xyz- TUI (manual):
conda run -n orbitron-dev cargo run --release -p orbitron-tui -- io/pipelines/tests/fixtures/xyz/water.xyz