1@README.md
2
3- Never edit anything under `zbanks-alttp/`: it is upstream's tree byte for
4  byte. What the host needs goes in `../../packages/zbanks` (`shim/host.c`
5  for C, `src/lib.rs` for Rust) or in a compiler flag in `BUCK`, with a
6  comment saying what forced it.
7- A change the host genuinely cannot make from outside is a carried patch:
8  a new `patches/NNNN-what-it-does.patch` (a `git diff` of the vendored
9  file, applied with `-p4`), in its own commit named for what it does, with
10  a comment in the patched code starting `Carried patch (jev):`, and a row
11  in `patches/README.md` plus its notes in `patches/CLAUDE.md`. `:patched`
12  in `BUCK` applies them in name order; one that stops applying fails the
13  build. To make one: edit the vendored file, `git diff --no-color <file> >
14  patches/NNNN-....patch`, `git checkout <file>`.
15- `BUCK` globs `patches/*.patch` only, so `patches/README.md` and
16  `patches/CLAUDE.md` are inert to the build. Keep any other file there out
17  of that glob's reach.
18- **`-Dap_goal_add=zb_goal_add` applies to `ap_map.c` only** (BUCK). That is
19  what lets the host decline goals the save says are done while `ap_plan.c`
20  keeps the real `ap_goal_add`. Adding the define to every source would
21  rename the definition too and silently remove the host from the path.
22- To refresh from upstream: `git fetch ~/src/github.com/zbanks/alttp master`,
23  `git rm -r third-party/c/zbanks-alttp`, `git read-tree
24  --prefix=third-party/c/zbanks-alttp/ -u <commit>`, build (every patch must
25  still apply, or be dropped with its row in `patches/` if upstream fixed the
26  same thing), and update the commit hash in `README.md`,
27  `../../packages/zbanks` (`src/lib.rs`, `shim/host.c`) and
28  `../../research/zbanks-alttp.md`.
29- The bot writes debug files with bare relative names; `-Dfopen=zb_fopen`
30  and `-Drename=zb_rename` in `BUCK` send them to the host's chosen
31  directory. A new libc file call in a future upstream (`remove`, `open`)
32  needs the same treatment, or its file lands in the repo root.