Chapter 16: third-party, other people's code, kept honest

Three big pieces of this project were written by somebody else: the SNES emulator (jgenesis, Rust), the bot (zbanks/alttp, C), and the code that talks to Jev (jevcrates, Rust, shared with three sibling projects). Plus the few hundred ordinary crates any Rust program pulls in. They all live under here, one folder per language.

The rule for all of it is the same: upstream's code is upstream's code. It is never edited to taste. When this project needs it to behave differently, the change is either made from outside (a host, a compiler flag, a wrapper), or it is a carried patch: a change recorded on its own, named for what it does, so that it can be found, re-applied after pulling a new upstream, and dropped the day upstream fixes the same thing.

Code	How it arrives	Changes we carry
zbanks/alttp	Vendored with `git read-tree`, byte for byte	Nineteen patch files, applied at build time (chapter 18).
jgenesis	A git subtree	Two commits: `wram()` and `wram_mut()` on `snes-core` (chapter 19).
jevcrates	A git submodule	None; it is changed in its own repository.
crates.io	Downloaded at build time, pinned by `Cargo.lock`	None; `fixups/` answers what reindeer cannot infer (chapter 20).

Aside: why no chapters for the vendored trees? Their documentation is upstream's, and it is upstream's text that should be there. A README of ours inside zbanks-alttp/ or jgenesis/ would be deleted by the next refresh, which replaces the folder wholesale, and anything we wrote inside it would silently stop being true the day upstream changed. So the chapters are one level up, describing the trees from outside: chapter 17 for the bot, chapter 19 for jgenesis and jevcrates. jevcrates carries a guide of its own.

Try it. See every change carried on the bot: ls third-party/c/patches/. See the two on the emulator: git log --oneline -- third-party/rust/jgenesis.

For the people who maintain it

In this folder

Path	Chapter	What
c/	17	The zbanks/alttp C bot, vendored, its carried patches (chapter 18), and its `cxx_library`.
rust/	19	The cargo manifest reindeer reads, the buck targets it generates, the reindeer fixups (chapter 20), the empty crate root (chapter 21), the vendored jgenesis emulator and the jevcrates submodule.
README.md		This chapter.
CLAUDE.md		The carried-patch rule, for agents.

← Previous: Chapter 15, hotdemo/ · Up: jevsnes · Next: Chapter 17, c/ →