|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | + |
| 5 | +- `objdiff-core`: core library with diffing logic and shared components |
| 6 | +- `objdiff-cli`: CLI/TUI with `ratatui` |
| 7 | +- `objdiff-gui`: GUI with `eframe`/`egui` |
| 8 | +- `objdiff-wasm`: WebAssembly bindings |
| 9 | + |
| 10 | +objdiff has three main frontends: GUI, CLI/TUI, and [web](https://github.com/encounter/objdiff-web) (utilizing `objdiff-wasm`). |
| 11 | + |
| 12 | +`objdiff-gui` is the most fully-featured and is the primary target for new features. |
| 13 | + |
| 14 | +`objdiff-cli` has an interactive TUI `diff` mode (powered by `ratatui`) and a non-interactive `report` mode to generate detailed progress reports (e.g. for <https://decomp.dev>). |
| 15 | + |
| 16 | +`objdiff-wasm` is compiled into a [WebAssembly Component](https://component-model.bytecodealliance.org/). The [API](objdiff-wasm/wit/objdiff.wit) is defined using [WIT](https://component-model.bytecodealliance.org/design/wit.html). The web interface is separate, but mirrors the GUI in functionality. |
| 17 | + |
| 18 | +## Build, Test, and Development Commands |
| 19 | + |
| 20 | +Run `cargo build` for a debug build and `cargo build --release` for an optimized build. |
| 21 | +The CLI can be exercised with `cargo run --release --bin objdiff-cli -- --help`. |
| 22 | + |
| 23 | +The WASM build is not included in the workspace by default due to differences in toolchain and target; build it with `npm -C objdiff-wasm run build`. (nightly required) |
| 24 | +In general, do NOT use `--workspace`, as it will include the WASM crate and likely fail. Formatting and linting commands are exempt. |
| 25 | + |
| 26 | +Pre-commit tasks: |
| 27 | + |
| 28 | +- `cargo test` to run the test suite |
| 29 | +- `cargo +nightly fmt --all` to format code (nightly required) |
| 30 | +- `cargo +nightly clippy --all-targets --all-features --workspace -- -D warnings` to lint code (nightly required) |
| 31 | +- `cargo deny check` (`cargo install --locked cargo-deny` if needed) if dependencies change |
| 32 | + |
| 33 | +## Testing Guidelines |
| 34 | + |
| 35 | +Favor focused unit tests adjacent to the code, and integration scenarios in `objdiff-core/tests`. |
| 36 | +Integration tests utilize snapshots with the `insta` crate; run `curl -LsSf https://insta.rs/install.sh | sh` if needed. |
| 37 | +To generate updated snapshots, use `cargo insta test`, review diffs manually, then accept changes with `cargo insta accept` (or simply `mv` to accept specific snapshots). |
| 38 | + |
| 39 | +## Configuration Tips |
| 40 | + |
| 41 | +- `config.schema.json`: JSON schema for the user-facing project config file (`objdiff.json`) |
| 42 | +- `objdiff-core/config-schema.json`: Internal options schema to generate `DiffObjConfig` (see `objdiff-core/config_gen.rs`) |
| 43 | + |
| 44 | +The project configuration (`objdiff.json`) is intended to be generated by the projects' build system. It includes paths to the target (expected) and base (current) object files, along with build commands and file watch patterns. See `README.md` for a summary of key options. |
0 commit comments