Files
AniCraft/docs/development.md

112 lines
6.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Development
## Build, run, test
```sh
cargo build # app + CLI (debug)
cargo run # desktop app with the sample
cargo run -- --screenshot shots/now.png # draw ~120 frames, save the window, exit
cargo run -- --open <panel> --screenshot x.png # palette|shortcuts|files|confirm|selection|transform|points|pen|frames|span|bucket|sound|tlzoom|tlwide|prefs|licenses|zoom|editmultiple|edittransform|onionsymbol
cargo run -- --theme high-contrast --scale 200 --screenshot x.png # a palette and interface scale for one run (not saved)
cargo test # every crate
cargo clippy --all-targets -- -D warnings
cargo deny check licenses bans sources
cargo run --release -p anicraft-cli -- bench # performance probe
```
Fonts: builds embed Inter, JetBrains Mono and Noto Sans Georgian (the interface offers Georgian only then) when `CRAFT_FONTS_DIR` points at a craft-fonts
checkout, or when one is found next to the repository (ADR 0005). Otherwise they use the
built-in fallback fonts.
Sound output (ADR 0020) uses `cpal`, which on Linux and the BSDs builds against ALSA: install
`libasound2-dev` and `pkg-config` (Debian/Ubuntu), `alsa-lib-devel` (Fedora) or `alsa-lib`
(Arch, FreeBSD). `cargo build --no-default-features` leaves sound output out (playback is
silent; import, waveforms and audio export still work). Tests never open an audio device.
### The user guide
The user guide is Markdown in `docs/guide/` (ADR 0069); `crates/guide` bundles it as HTML for
Help › User Guide, and `cargo run -p anicraft-cli -- guide --out <folder>` writes the pages.
`cargo test` checks every link, anchor and picture and that every chapter is reachable from
`index.md`; a new chapter needs its line in `PAGES` (`crates/guide/src/lib.rs`) and a link
from the contents. The command and shortcut references in `docs/guide/reference/` are
generated: when a command or a default key changes, a test fails until you run
```sh
ANICRAFT_BLESS_GUIDE=1 cargo test -p anicraft guide_reference
```
and commit the result. The pictures come from `scripts/guide-shots.sh` (or `.ps1`), which runs
`--screenshot --open <state> --shot-width 1100`; look at each one before committing it.
### GPU stage
The stage draws on the graphics card by default (ADR 0032; the shell's `gpu-stage` feature is
on by default, and the CPU draws when there is no usable card). For a CPU-only shell:
`cargo run --no-default-features --features sound-output`; to compare at run time,
`ANICRAFT_STAGE_RENDERER=cpu|gpu`. The `anicraft-gpu` crate builds and tests in every build:
its parity tests run on the graphics card, else on a software adapter (lavapipe; WARP fails the self-test, ADR 0032), and
skip without either; `ANICRAFT_TEST_GPU=software` forces the software adapter and
`WGPU_BACKEND=dx12|vulkan|metal` picks the backend. `cargo run --release -p anicraft-gpu
--example gpu_bench` prints timings and parity.
## CI
Every workflow calls the suite's shared workflows in `storytold/craft-common-actions`, which
start each job with Harden-Runner and pin actions by SHA.
| Workflow | Runs on | When | What |
|---|---|---|---|
| `ci.yml` (CI) | Ubuntu 24.04 (lavapipe for GPU tests) | every PR, every push to `main` | `cargo test --workspace`, clippy |
| `platforms.yml` (CI (macOS, Windows), ADR 0067) | `macos-latest` (arm64), `windows-latest` (x64) | PRs and pushes to `main` that change more than docs, Markdown or other workflows | `cargo build`, `cargo test --no-fail-fast`, clippy, for the workspace |
| `web.yml` | Ubuntu | every PR, every push to `main` | wasm32 build, the engine's tests in Node, the web bundle |
| `freebsd.yml`, `windows-arm64.yml` | FreeBSD VM, Windows ARM64 | nightly / weekly, packaging changes | build and tests; ARM64 MSI install |
| `sonarcloud.yml`, CodeQL default setup | Ubuntu | every PR | coverage and static analysis |
Measured job times (wall clock, from the job's start to its end):
| Job | 2026-11-12, PR #190 |
|---|---|
| Linux gate (`ci.yml`, warm cache) | 6 m 24 s |
| macOS arm64 leg (first run, no cache) | 16 m 33 s: build 7.5 min, test build 6.0, tests 1.3, clippy 1.2 |
| Windows x64 leg (first run, no cache) | 28 m 02 s: build 12.0 min, test build 11.1, tests 4.0, clippy 1.8 |
The macOS and Windows legs run in parallel with the Linux gate, so a code PR takes about as
long as the Windows leg and about 45 more runner-minutes cold (ADR 0067 › Costs).
A superseded PR run is cancelled (each workflow has its own `concurrency` group, so one never
cancels another); pushes to `main` always run to the end and are the only runs that write the
dependency caches, so a PR's first run reuses `main`'s. To start the platform legs by hand:
`gh workflow run platforms.yml --ref <branch>`.
## Build footprint (biased for disk space, then time)
Measured on Windows, 32 threads, offline, from an empty target directory:
| | Before (2026-10-28) | Now |
|---|---|---|
| Debug build of the workspace | 6.5–6.9 GB in `target/` (3.0 GB of it the incremental cache) | **1.04 GB** (1.08 GB with all test binaries; 1.33 GB with build + tests + clippy, measured after a clean) |
| Fresh build time | ~60 s | **44 s** (tests then add 3 s) |
| Rebuild after editing a UI file | ~2 s (incremental) | **3.8 s** |
| Rebuild after editing an engine file | ~3 s | **6.0 s** |
| Debug `anicraft.exe` | 21 MB + 200 MB PDB | 21 MB + small line-table PDB |
What does it (in `Cargo.toml`):
| Setting | Effect |
|---|---|
| `profile.dev.debug = "line-tables-only"` | Panics and backtraces keep file:line; full variable info (most of the PDB/DWARF size) is gone. Also avoids MSVC's PDB limit (LNK1140). Use `debug = true` locally when you need a debugger session. |
| `profile.dev.incremental = false` | The incremental cache was ~3 GB for our crates. They rebuild from scratch in seconds. |
| `profile.dev.package."*"`: `opt-level = 2, debug = false` | Dependencies are optimized once (a fast app even in debug) and carry no debug info. |
| `profile.dev.build-override`: `opt-level = 0, debug = false` | Build scripts and proc-macros compile fast and small. |
| `profile.release.strip = "debuginfo"` | Smaller release binaries. |
| eframe without default features | Drops `links` (url/idna/ICU Unicode tables) and the web-only screen-reader shim. |
House rules:
* **One target directory.** Never point agents or scripts at a second `CARGO_TARGET_DIR`: each
copy is another full build (1+ GB now, 3–7 GB before).
* After changing profiles or dependency features, run `cargo clean` once, so the old artifacts
don't sit next to the new ones. Close the app first: Windows can't delete a running exe.
* Clean up temporary measurement directories with `cargo clean --target-dir <dir>`.