1@README.md
2
3- Never edit `BUCK`. Change `Cargo.toml`, `reindeer.toml` or a fixup and
4  re-run buckify.
5- A new crate with a `build.rs` makes buckify warn that its fixup "does not
6  say what to do". Answer it in `fixups/<crate>/fixups.toml` with
7  `buildscript.run = true` or `false` - read the build script to decide; most
8  only probe rustc features and need `true`.
9- `cargo_env = true` in `reindeer.toml` is load-bearing: `serde_core` and
10  `thiserror` read `CARGO_PKG_VERSION_PATCH` via `env!()` and fail to compile
11  without it. It must sit above `[vendor]`: TOML keys after a table header
12  belong to that table.
13- `jgenesis/` is excluded from this manifest's workspace on purpose. Left in,
14  cargo resolves jgenesis's `workspace = true` keys against THIS manifest and
15  fails with "workspace.package.version was not defined".
16- `jgenesis/` carries two patches over upstream d19ee94f: `SnesEmulator::wram()`
17  (commit "jgenesis: expose work RAM from snes-core") and
18  `SnesEmulator::wram_mut()` (commit "jgenesis: let a host write work RAM",
19  for the zbanks bot, which writes its cheats into RAM each frame). After
20  `git subtree pull --prefix=third-party/rust/jgenesis`, confirm both survived:
21  `grep -n "pub fn wram" third-party/rust/jgenesis/backend/snes-core/src/api.rs`
22  (two hits).
23- jgenesis needs a Rust newer than nixpkgs 26.05 ships (it uses
24  `float_algebraic`); the devshell's fenix toolchain is why it builds.
25- Build scripts run inside the buck2 DAEMON's environment, not the calling
26  shell's. After adding something a build script needs to the devshell
27  (`pkg-config`, a library), run `buck2 kill` from the new shell first; until
28  then the script fails as if the package were missing (measured 2026-09-20:
29  `alsa-sys` could not find `pkg-config` that the shell itself could run).
30- `alsa-sys` is the one crate here that links a system library at build time.
31  Everything the window needs (wayland, xkbcommon, X11, Vulkan, GL) is
32  dlopened at startup instead, which is what `LD_LIBRARY_PATH` in `flake.nix`
33  is for.
34- `jevcrates/` is a git submodule of ~/jevcrates (`jev-protocol`,
35  `jev-client`, `jev-http`), path dependencies in `Cargo.toml`; they were
36  `packages/jev` and `packages/jev-http` until 2026-10-01. Never edit inside
37  it here: change ~/jevcrates, then move the gitlink. Its URL in
38  `.gitmodules` is relative (`../jevcrates.git`) so a clone from the lmjtfy
39  site finds it beside this one; do not make it absolute, or a clone from
40  the site points at private GitHub and fails. `git submodule update --init`
41  checks it out.