# `cargo xtask <verb>` → run the dwarves build-automation crate. The demo web build +
# Codeberg-Pages deploy live here (`demo-wasm` / `deploy-pages`); pure-Rust, zero-shell.
[alias]
xtask = "run --package xtask --"
# `cargo ci-verbs <verb>` → the CI runner's own DETACHED verbs (ci/verbs: lockcheck, status,
# scorecard), the forge's nightly Scorecard step (pipelines/scorecard.runa.ron).
ci-verbs = "run --quiet --manifest-path ci/verbs/Cargo.toml --"
# `cargo xtask-docs docs` → the SVG-book renderer, which needs nornir's typst stack
# (the `docs` feature). Kept a SEPARATE alias so the lean `cargo xtask demo-wasm` /
# `deploy-pages` builds never pull typst into the automation crate.
xtask-docs = "run --package xtask --features docs --"
# `cargo robot-ui -- --robot-mode headless` → the UI WITH THE ROBOT DRIVE COMPILED IN.
#
# This alias exists so nobody hand-writes the feature string again. The robot drive is
# not a delivery, so it is deliberately NOT a sixth atom in
# `.nornir/build-variants.toml` — atoms are things you ship, and a variant reusing the
# `dwarves-ui` bin name would collide in `check_bins` anyway (it keys on
# `(suite, target, profile, package, bin)`; a bin name is a FILE PATH). But "not an
# atom" was silently reading as "figure it out yourself": every robot run so far
# rebuilt `--features robot-remote,watch` from memory, which is exactly how the
# invocation and the declaration drift apart.
#
# `robot-remote` compiles the headless off-screen drive (`--robot-mode headless`),
# `watch` the real visible window (`--robot-mode watch`, Wayland only). Both are off in
# the shipped `dwarves-ui`, and a binary without them REFUSES the flags rather than
# opening a plain GUI — so this alias is the only way to get a drivable UI.
robot-ui = "build --package dwarves-gui --bin dwarves-ui --features robot-remote,watch"
# ── THE LINKER IS DECLARED, because GNU ld cannot link this GUI ──────────────
#
# MEASURED 2026-08-23 on `dwarf` (12 cores / 62 GB — NOT oden; unverified there): `cargo test -p dwarves-gui` — and every other
# link of the `dwarves-ui` bin — dies
#
# collect2: fatal error: ld terminated with signal 11 [Segmentation fault]
#
# with GNU ld 2.46 (Ubuntu binutils, gcc 15.2.0). It is NOT resource pressure and
# NOT link scale: 36 GB RAM and 580 GB disk were free, and `cargo build -p dwarves
# --bin dwarves-server` links green at comparable size on the same box in the same
# minute. It is the dwarves-gui input set specifically — eframe + wgpu + resvg +
# the embed crates, ~120 objects over a very large rlib set.
#
# So the linker becomes part of the DECLARED build surface rather than something
# each agent rediscovers by watching a segfault: same reasoning as holger putting
# its zig cross-toolchain in its own `.cargo/config.toml` (fail-loud, workspace
# law "declare the build, don't remember it").
#
# WHY THIS EXACT SHAPE, and not the two shapes that look equivalent and are not:
# * `-C link-arg=-fuse-ld=mold` does NOT work — gcc's collect2 spawns the real
# `ld` regardless and you get the same signal 11. MEASURED, both arms.
# * `mold -run cargo test` does NOT work either — same segfault. MEASURED.
# The working form is clang as the link DRIVER with `--ld-path`, which clang
# honours where gcc's `-fuse-ld` did not.
#
# PROOF it is the linker and not the code: with this declaration
# `dwarves-gui/tests/robot_kernel_scene.rs` links and runs 5/5 GREEN in 1.78 s;
# without it, the same tree cannot produce a test binary at all.
#
# FAIL-LOUD, deliberately: a box without clang or mold now fails with a named
# "linker `clang` not found" instead of a mystery segfault. Both are in Ubuntu
# (`clang`, `mold`). Note `--ld-path` takes an ABSOLUTE path — clang does not
# search PATH for it.
#
# CAVEAT worth knowing before you debug a build that ignores this: setting
# RUSTFLAGS in the environment REPLACES `rustflags` here wholesale (it does not
# merge), so a shell that exports RUSTFLAGS silently gets GNU ld and the segfault
# back. If a link starts segfaulting again, check `echo $RUSTFLAGS` first.
#
# WHY THE LINKER RIDES `rustflags` (`-C linker=clang`) AND NOT `linker = "clang"`
# (2026-09-26): this choice belongs to the HOST, and the declared build is not
# the host. `.nornir/build-variants.toml` pins `[build.toolchain]`, so the
# forge builds dwarves inside nordisk-cargo-toolchain, and that image has
# gcc, GNU ld 2.44 and ld.lld but no clang and no mold. MEASURED on loki: with
# `linker = "clang"` the container build died in 2.2 s with "linker `clang` not
# found" on the first build script. The container runner exports its own
# RUSTFLAGS, which replaces this `rustflags` wholesale (the caveat above), so a
# linker spelled HERE stays out of the container and the image's own `cc`
# links. A `linker =` key would still apply there. On the host nothing changes:
# `-C linker=clang` is the same choice as the `linker` key, and the same
# RUSTFLAGS caveat still applies.
[target.x86_64-unknown-linux-gnu]
rustflags = ["-C", "linker=clang", "-C", "link-arg=--ld-path=/usr/bin/ld.mold"]