BFM-decomp/phase-ends/PhaseEnd_Phase4.md

PhaseEnd — Phase 4: Matching-build toolchain (WSL)

Date: 2026-06-14 · Project Version: 1.4.0 · Phase Status: Complete

Build Log

Files created/changed and complete — do not recreate:

• Makefile — new, repo root. The live target is check-env (the Phase-4 milestone preflight): .ONESHELL bash, default goal help. Asserts python ≥ 3.12, venv import splat, both cc1 candidates (R12-clean stdin smoke), tools/maspsx/maspsx.py, the three mipsel binutils (as/ld/objcopy), and sha1(committed extracted/retail/SLUS_007.26) == EXPECTED_EXE_SHA1 (imported from tools/bfm_extract/extract_exe.py — no magic literal). binutils ≥ 2.38 → [WARN], not FAIL (§4.5). extract/build/check/expected/clean are loud-failing no-op stubs (names fixed per §6.3; Phase 5 implements them). Consumed by: the daily build (Phase 5 extends this file).
• .gitmodules — new; 4 submodules under tools/.
• tools/maspsx, tools/asm-differ, tools/m2c, tools/decomp-permuter — new submodule gitlinks (pinned, see Verification). Their working-tree contents are gitignored-by-submodule (a fresh clone runs git submodule update --init).
• tools/bin/CHECKSUMS.sha256 — new, committed; sha256 of the two old-gcc 0.17 tarballs. The ONLY thing committed out of the otherwise-ignored tools/bin/. Verify with sha256sum --check.
• .gitignore — modified: /tools/bin/ → /tools/bin/* + !/tools/bin/*.sha256 (contents-exclude form so the checksum record commits while all compiler binaries/tarballs stay ignored).
• docs/SETUP.md — modified: as-built versions (binutils 2.42, splat 0.41.0 + deps, gcc tarball sha256, submodule pins, check-env); §4.7 corrected (cc1 is 32-bit i386 not x86-64; flat-tarball → per-subdir extraction fix); §4.8 deferred-to-Phase-6 note; ledger #5/#6/#7 resolved; pin-summary splat/binutils rows updated.
• phase-ends/CURRENT_PHASE.md — absorbed into this file and deleted (P8).
• phase-ends/PhaseEnd_Phase4.md — this file.

Local artifacts (gitignored / outside the repo — present on this machine, do NOT recreate; a fresh clone redoes them):

• .venv/ — Python 3.12.3 venv. Recreate: python3 -m venv .venv && .venv/bin/pip install 'splat64[mips]>=0.41.0,<1.0.0'.
• tools/bin/gcc-2.7.2-psx/ + tools/bin/gcc-2.7.2-cdk/ — old-gcc 0.17 prebuilts (32-bit i386 static cc1/cc1plus/cpp/gcc/g++) + the two .tar.gz. Recreate per the corrected §4.7.
• Submodule working trees under tools/{maspsx,asm-differ,m2c,decomp-permuter} — git submodule update --init.

Tools/packages installed:

• apt: build-essential (make 4.3, g++ 13.3.0), binutils-mipsel-linux-gnu 2.42 + cpp/gcc-mipsel-linux-gnu 12.x, python3-pip 24.0, python3-venv (3.12), ninja-build 1.11.1, libelf-dev, clang-format 18, p7zip-full, bchunk, bsdmainutils (curl/wget/unzip/git/coreutils already present, ensured).
• venv (pip): splat64 0.41.0; deps spimdisasm 1.41.0, rabbitizer 1.16.2, PyYAML 6.0.3, colorama 0.4.6, intervaltree 3.1.0, tqdm 4.67.1.
• downloaded (gitignored): old-gcc 0.17 gcc-2.7.2-psx.tar.gz + gcc-2.7.2-cdk.tar.gz.

Verification results (literal):

• MILESTONE — make check-env → exit 0: [PASS] python3 3.12; venv import splat (splat64 0.41.0); cc1 runs tools/bin/gcc-2.7.2-psx/cc1 and …-cdk/cc1; maspsx present; mipsel as/ld/objcopy all 2.42; extracted/retail/SLUS_007.26 sha1 143dbb89f34491258bbc27810d0a12ec8b43a8dd == EXPECTED_EXE_SHA1. Plus [WARN] mipsel binutils 2.42 ≥ 2.38. check-env: OK.
• git submodule status: maspsx 874855c5 ✓, decomp-permuter b44b0622 ✓ (both pinned per the table), asm-differ 2ad4a4a4 (HEAD@adoption), m2c 4266cc28 (HEAD@adoption).
• sha256sum --check tools/bin/CHECKSUMS.sha256: both OK — psx 500a459b…, cdk 42bb0df9….
• cc1 binaries are 32-bit i386 statically-linked ELF (run via IA-32 emulation); psx cc1 smoke emits GNU C 2.7.2 [AL 1.1, MM 40] Sony Playstation + valid MIPS asm; psx/cdk cc1 are distinct (different sha256 — the naive flat extraction would have silently kept only one).
• Hygiene: git add tools/bin/ stages only CHECKSUMS.sha256; git status shows zero ROM-derived/binary bytes would stage (.venv, compiler binaries, .tar.gz all ignored). bare make → help; make extract → loud fail (make: *** Error 1).
• Ubuntu 24.04.4 LTS confirmed (ledger #5).
• Nothing committed (R8): all work is staged/untracked and uncommitted, awaiting Drew's phase-end commit.

Milestone achieved: make check-env exits 0 in the WSL ext4 clone — both cc1 candidates execute and emit MIPS asm, splat imports in the venv, the mipsel binutils are present, and the committed SLUS_007.26 sha1 equals EXPECTED_EXE_SHA1 — the matching-build toolchain is stood up and self-verifying.

Next: Phase 5 — splat config + build skeleton (all-asm byte-match). Start with config/splat.us.exe.yaml authored (section boundaries iterated until a clean link), config/symbols.us.txt already seeded from Phase 3. (Phase 5 RE-reads gp_value for -G0/-G8, ledger #8; implements the Makefile's stub targets.)

Deviations

Item	Plan	Actual	Reason
cc1 architecture	"x86-64 Linux ELF" (§4.7)	32-bit i386 statically-linked	old-gcc 0.17 ships i386 binaries; run on x86-64 via IA-32 emulation; §4.7 corrected
old-gcc extraction	tar xzf psx ; tar xzf cdk flat (§4.7)	per-subdir -C gcc-2.7.2-{psx,cdk}	tarballs are flat and share filenames → flat extraction clobbers psx with cdk; §4.7 command fixed
check-env "dump hash"	disc-level implied by milestone	sha1(committed EXE) == EXPECTED_EXE_SHA1, reused constant	fresh-clone-safe (disc-walk needs gitignored disks/); reuses existing code (no magic literal)
cc1 liveness check	"cc1 runs (--version)"	trivial stdin compile	gcc-2.7.2 cc1 rejects --version; stdin→/dev/null compile is the real test, and R12-clean (no temp file)
§4.8 native PsyQ binaries	optional Phase-4 checkbox	deferred to Phase 6	Drew decision; tie-breaker only if maspsx output is disputed during fingerprinting
submodule pip deps + requirements freeze	implied by "installed"	deferred (Phase 6 / after Phase-5 green)	milestone names only splat/cc1/maspsx/binutils; avoids polluting the to-be-frozen requirements-python.txt
binutils version	2.35 known-good target	2.42 installed + WARN, verdict deferred	§4.5 mandates deferral to Phase 5's first full build; Ubuntu 24.04 ships 2.42
Makefile scope	check-env only (milestone)	check-env + Phase-5 target name stubs	§6.3 fixes the names now; loud-failing stubs prevent a silent false-success build

Commit Message

feat(phase-4): matching-build toolchain (WSL) — make check-env green

- apt: build-essential, binutils-mipsel-linux-gnu 2.42 (+gcc-mipsel 12.x), ninja
  1.11.1, python3-pip/venv, libelf-dev, clang-format, p7zip, bchunk, bsdmainutils
- .venv + splat64 0.41.0 ([mips]: spimdisasm 1.41.0, rabbitizer 1.16.2, PyYAML 6.0.3)
- 4 pinned submodules under tools/: maspsx@874855c5, decomp-permuter@b44b0622,
  asm-differ@2ad4a4a4, m2c@4266cc28 (.gitmodules)
- old-gcc 0.17 cc1 candidates -> tools/bin/gcc-2.7.2-{psx,cdk}/ (32-bit i386 static;
  tarballs are flat + same-named -> per-subdir extraction); CHECKSUMS.sha256 committed
  (gitignore exception !/tools/bin/*.sha256); psx cc1 self-id "GNU C 2.7.2 [AL 1.1,
  MM 40] Sony Playstation"
- Makefile: check-env (.ONESHELL bash) asserts python>=3.12, venv import splat, both
  cc1 (stdin smoke), maspsx, mipsel as/ld/objcopy, sha1(EXE)==EXPECTED_EXE_SHA1;
  binutils>=2.38 -> WARN (verdict deferred to Phase 5, §4.5); extract/build/check/
  expected/clean are loud-failing Phase-5 stubs (names per §6.3)
- docs/SETUP.md: as-built versions; §4.7 corrected (i386, flat-tarball fix); §4.8
  deferred to Phase 6; ledger #5 confirmed (Ubuntu 24.04.4), #6 (2.42), #7 (sha256)
- MILESTONE: make check-env exits 0; zero ROM-derived bytes staged
- bumps project version 1.3.1 -> 1.4.0

Rules Added This Phase

Rule

Reason

None

Phase 4's findings are deviations / doc-corrections (cc1 is i386 not x86-64; the flat-tarball extraction trap; binutils 2.42 WARN; §4.8 deferral), not governance rules. Noted practice (not elevated to a rule): build/preflight targets should be fresh-clone-safe and reuse single-source constants (no magic literals, no gitignored deps) — applied in check-env (imports EXPECTED_EXE_SHA1, hashes the committed EXE). Elevate later if Phase 5's build targets benefit.

PhaseEnd Changelog

v1.3.1 → v1.4.0 — Phase 4 complete. The matching-build toolchain is stood up and self-verifying in the WSL ext4 clone: the apt cross-toolchain (binutils-mipsel 2.42), a Python 3.12 venv with splat64 0.41.0, four pinned submodules (maspsx/asm-differ/m2c/decomp-permuter), and the old-gcc 0.17 cc1 candidates (gcc-2.7.2-psx + gcc-2.7.2-cdk) — all asserted by a new make check-env target that exits 0. Two SETUP.md corrections caught by the bytes: the cc1 prebuilts are 32-bit i386 (not x86-64), and the 0.17 tarballs are flat & same-named so each must extract into its own subdir. binutils 2.42 is WARN-flagged with the regression verdict deferred to Phase 5's first build (§4.5). Ledger #5/#6/#7 resolved; §4.8 native-PsyQ arbitration deferred to Phase 6; submodule pip deps + requirements freeze deferred. No new rules. Next: Phase 5 (splat config + all-asm byte-match).

🛑 Stop Here

PhaseEnd written; CURRENT_PHASE.md absorbed and removed. Drew commits AND pushes this PhaseEnd (R6/R8 — the single Phase-4 commit lands everything: Makefile, .gitmodules, submodule gitlinks, tools/bin/CHECKSUMS.sha256, .gitignore, docs/SETUP.md, PhaseEnd_Phase4.md). Start a fresh session for Phase 5 — splat config + build skeleton. Keep this file forever.