alchemy-gcc

alchemy-gcc is the compiler repository used by Alchemy, a clean-room Golden Sun reconstruction. It is kept separate because the compiler sources have their own upstream provenance, build system, and redistribution notices. The main repository consumes staged compiler runtimes; it does not vendor compiler binaries or license files.

This repository follows the practical pret/agbcc pattern: keep the compiler source and its applicable notices together, provide a reproducible build, and let the game reconstruction choose the runtime it needs.

Included compiler sources

• gcc-2.96/ is the 2000-07-31 GCC development snapshot at 04179d4a511b13cef92eacdb10a51bcd124fea7a, from the gcc-mirror/gcc history, used for the GS1 Camelot code-generation path. Its GCC license notices remain in gcc-2.96/COPYING and gcc-2.96/COPYING.LIB.
• agbcc/ is a pruned checkout of pret/agbcc at da598c1d918402c42c0c0d7128ba14567f3175e9, retained for the stock Thumb audio library compiler (old_agbcc). Its corresponding source and notices are kept together, including agbcc/gcc/COPYING, agbcc/gcc/COPYING.LIB, and agbcc/libc/COPYING.NEWLIB.
• gcc-3.0/ contains the comparison and GS2 backend family used by Alchemy. Its source and notices remain in gcc-3.0/.

The vendored trees are the corresponding source for the compiler runtimes built here. Do not publish a staged binary without the applicable source and license files from this repository. This README makes no legal guarantee; review the notices and source obligations for the distribution you make.

Build and test

Requirements are Rust/Cargo, a host C toolchain with make, and ARM binutils (arm-none-eabi-as and arm-none-eabi-ar, or a devkitARM installation).

From this directory:

cargo test --offline
cargo run --release -- build gcc296
cargo run --release -- build gcc3
cargo run --release -- build gs2
cargo run --release -- build agbcc
cargo run --release -- test gcc296

build all and test all run the complete supported set. The driver owns the historical build orchestration, timestamp handling, host flags, and the serial agbcc build; do not invoke the old build products by hand when reproducing a runtime.

Generated build directories and Cargo targets are local artifacts. They are not part of the source distribution.

GCC 2.96 resource-373 matching modes

The following six GCC 2.96 modes are opt-in, source-routed repairs admitted for resource 373. Each has an auditable matcher boundary plus positive and negative fixtures. A mode is not admitted merely because its positive fixture changes or one Alchemy source becomes closer: the complete compiler and consuming-ROM gates below remain the acceptance boundary.

The routed owners below are entries in Alchemy's append-only routing tables. The phase in parentheses is the file currently present in the Alchemy checkout; a routing-table entry may name both semantic and exact forms while an owner is moving through adoption. The compiler repository does not own those C sources.

Mode	Matcher intent and safety contract	Routed owners	Positive fixtures	Negative fixtures
-fthumb-pool-long-call-arg0	Pool a long r0 literal formed by a small literal plus a left shift immediately before a call. The matcher requires a split-constant predecessor call, r0, a shift of 5–30, a shiftable result greater than 255, and no r1–r3 call uses. It must leave shorter 772 (193 << 2) and unrelated setup unchanged.	resource_373_c_02002f14 (exact)	gcc296_thumb_pool_long_call_arg0.c; gcc296_thumb_pool_long_call_arg0_interleaved.c	gcc296_thumb_pool_long_call_arg0_772.c
-fthumb-order-zero-arg1-before-nonzero-arg0	Transpose only an adjacent nonzero r0 literal and zero r1 literal before a two-argument call whose predecessor has the observed split r1 setup. It must reject calls using r2 or r3, and must not generalize into arbitrary argument scheduling.	resource_373_c_02002f14 (exact)	gcc296_thumb_zero_arg1_before_nonzero_arg0.c	gcc296_thumb_zero_arg1_before_nonzero_arg0_multi.c
-fthumb-store-before-pool-load	Restore the observed order of a nonvolatile byte store through r3 and a constant-pool load, inside the exact r1 = 200, pool-load-to-r0, store, r1 << 4, call sheet. Admission requires an alias proof that the store cannot affect the pool load, plus an explicit byte-store check; register non-overlap alone is insufficient.	resource_373_c_02002a54 (exact)	gcc296_thumb_store_before_pool_load.c	gcc296_thumb_store_before_pool_load_negative.c
-fthumb-order-8-0-20-args	Restore the exact three-argument 8, 0, 20 reference order as r2, r1, r0 immediately before the call, with the required predecessor call. It must not reorder the near miss 8, 0, 21 or become a general argument reorder.	resource_373_c_02002cb0 (exact)	gcc296_thumb_order_8_0_20_args.c	gcc296_thumb_order_8_0_20_args_negative.c
-fthumb-zero-r1-before-r0-load-after-8-2	Move the zero r1 setter before the constant r0 load only after the exact predecessor call carrying 8, 2, then preserve the following call boundary. The neighboring 8, 3 family must remain unchanged.	resource_373_c_02002cb0 (exact)	gcc296_thumb_zero_r1_before_r0_load_after_8_2.c	gcc296_thumb_zero_r1_before_r0_load_after_8_2_negative.c
-fthumb-call-arg12-before-arg0	Move a nonvolatile QI byte load into r0 after an immediate r1 = 128 and hard-register r2 copy, only for an original-order three-argument call using exactly r0–r2. It rejects volatile loads, overlaps, pseudos, and calls using r3.	resource_39a_c_02001b1c (semantic)	gcc296_thumb_call_arg12_before_arg0.c	gcc296_thumb_call_arg12_before_arg0_negative.c
-fthumb-stack-slot-before-table	Bias allocation for the proven reference pair: the stack-loaded selector takes r2 and the following global table pointer takes r4. The discriminator must identify that pair, preserve liveness and register availability, and never treat an arbitrary SYMBOL_REF as the table pointer.	resource_373_c_020008c0 (semantic)	gcc296_thumb_stack_slot_before_table.c	gcc296_thumb_stack_slot_before_table_negative.c

The fixture names are source files under tests/fixtures/; they are regression inputs, not substitutes for a byte-identical ROM rebuild. The store/load mode checks width, volatility, constant-pool provenance, alias separation, and the complete call sheet. The stack/table allocator mode requires a frame-derived selector and its witnessed indexed use with the symbolic table pointer before forcing either register.

Register-order routes

The same resource-373 work currently routes two existing backend controls that are relevant to the allocator experiment:

• -mcallee-reg-order=0132 is routed for semantic/resource_373_c_020008c0.c and semantic/resource_373_c_0200564c.c.
• -mhigh-reg-order=1203 is routed for semantic/resource_373_c_0200564c.c.

The driver covers both controls with dedicated positive fixtures and a shared register-pressure negative fixture, so an accepted run proves that the opt-in orders change their intended sheets without changing the negative case.

Required admission sequence

For each mode, retain the positive and negative fixture outputs and review the generated assembly against the matcher contract. Then admission requires this ordered sequence:

1. Run the focused Rust tests and the GCC 2.96 regression driver, including every positive and negative fixture above and the register-order tests.
2. Build the GCC 2.96 runtime and stage the exact resulting bundle; run stage --check gcc296 and record the actual executable and bundle digests.
3. Run Alchemy's routed main-image exact-C corpus with zero sampling. Every selected main-image owner must remain byte-exact, with zero regressions and no cached result whose source, route, compiler, linker, scorer, or tool version has changed.
4. Rebuild all assets and decoded overlays. The main-image corpus does not cover overlay owners; make build-assets, make build-full, and the final ROM gate are what catch an overlay compiler regression.
5. Run make build-claimed, the compiler-focused checks, and the authoritative make verify from the consuming Alchemy checkout.
6. Only after all gates pass may Alchemy append the new approved-host digest; until then, the mode and its compiler bundle remain pending and must not be presented as an admitted result.

Verification record: 2026-08-09

The resource-373 modes and register-order controls above passed the complete admission sequence on macOS arm64:

• Rust driver tests: 3/3; GCC 2.96 routed regression modes: 24/24.
• Uncached routed main-image corpus: 1,456/1,456 byte-exact, zero regressions.
• Decoded resource-373 overlay: 30,764/30,764 bytes identical.
• Asset rebuild: 2,431 assets and 7,840,244 bytes; claimed build: 1,456 linked, zero failures.
• Alchemy make verify: green, including 112/112 native self-tests and a byte-identical 8 MiB ROM rebuild.

The admitted staged executable digests are:

Executable	SHA-256
xgcc	df0413f0051c07c654a753764235f39891d6f08a95d603a50f3cca9c645fc4e3
cc1	b771d74eaf6b1c11ec8d4dcf8ed377ef93115266f157d4a13a9ebdab468fe774
cpp	c6e5093aa3cda856c10b8fdff5a7f645a6ca63c92d2aea46688f8da4f5357915
tradcpp	553a34add496b8a063707e32376824ba11cf0153b4b6283309c9a2518a866281

Alchemy compiler-bundle signature v2: cfcb489d88b932073937316470c3adb2bdd4b05ad3883e8178d3396587aca72c.

Stage and admit a runtime

Stage only a runtime that has passed its focused compiler tests and the consuming Alchemy verification gates:

cargo run --release -- stage gcc296
cargo run --release -- stage gcc3
cargo run --release -- stage gs2
cargo run --release -- stage agbcc
cargo run --release -- stage --check gcc296

The staged layouts are:

Target	Runtime	Purpose
gcc296	dist/{xgcc,cc1,cpp,tradcpp}	GS1 Camelot code generation
gcc3	dist/gcc3/cc1	comparison probe
gs2	dist/gs2/{xgcc,cc1,cpp0,tradcpp0}	GS2 backend family
agbcc	dist/agbcc/old_agbcc	stock Thumb audio compiler

stage --check TARGET verifies that an existing staged bundle still matches the local build. stage all stages every target. The staged files are ignored runtime artifacts, not source files to commit.

dist/ is the single canonical stage. Staging takes an exclusive lock while Alchemy consumers hold the matching shared lock for validation, cache identity, and compiler execution, preventing a process from seeing a mixed bundle. The driver deliberately does not support an alternate staging root.

Alchemy admits a bundle by recording its actual staged executable and bundle digests in its append-only approved-host table. Admission is evidence, not a cosmetic version bump: the compiler-focused regressions, full routed exact-C corpus, claimed build, and authoritative make verify must pass before a new digest is approved. Existing approved digests are retained. A compiler rebuild therefore produces a new candidate digest until the consuming repository has verified it.

How Alchemy consumes it

The Alchemy repository points its native compiler tooling at a staged bundle. Its routing tables select compiler families and source-scoped modes per owner; the compiler repository supplies the executable behavior, while Alchemy supplies the C sources, linker inputs, byte comparison, and ownership evidence.

From the Alchemy checkout, the normal handoff is:

cargo run --release --manifest-path alchemy-gcc/Cargo.toml -- build gcc296
cargo run --release --manifest-path alchemy-gcc/Cargo.toml -- stage gcc296
cargo run --release --manifest-path alchemy-gcc/Cargo.toml -- test gcc296
make compiler-checks
make build-claimed
make build-assets
make verify

The final proof is byte equality in Alchemy's target ROM. A compiler that builds successfully, or a candidate that is merely close, is not an exact result.

Source and publication boundary

Keep these with the compiler repository when distributing its source:

• the complete vendored source trees needed by the supported builds;
• the Rust driver in src/main.rs, its Cargo.toml, and Cargo.lock;
• the applicable COPYING* and other upstream notices shipped by those trees;
• the build and provenance records needed to reproduce the selected source revisions and patches.

Do not commit generated build directories, target/, staged runtime binaries, archives, object files, compiler dumps, or ROM/build outputs. The Alchemy repository contains the reconstruction and its own publication policy; this repository contains the compiler sources and their corresponding notices.

Credits and provenance

The GCC sources are redistributed under the notices included with their respective trees. The agbcc source follows the pret/agbcc repository and its recorded revision. The GCC 2.96 snapshot and Camelot-specific work derive from the documented upstream/compiler research recorded in this repository. Consult the source history and notices for exact provenance rather than treating this summary as a license statement.