From f30afb08985c81d77109291eaf83881127e2fda0 Mon Sep 17 00:00:00 2001 From: JC-000 <3798556+JC-000@users.noreply.github.com> Date: Fri, 14 Aug 2026 08:20:24 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20fix=20the=20fresh-clone=20recipe=20?= =?UTF-8?q?=E2=80=94=20it=20was=20missing=20`make=20ip65-blob`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #86 documented a fresh-clone build recipe that does not work. Verified 2026-08-14 against a clean `git clone` of master: - plain `make` -> FAILS - after `make ip65-libs`, `make` -> FAILS, identically - after `make ip65-blob`, `make` -> succeeds `make` cannot build the blob: `ip65-blob` is phony, and ip65_blob.s pulls the file in via a ca65 `.incbin` that make's dependency graph never sees, so no rule connects them. The recipe now includes the step. The documented failure mode was also wrong. #86 quoted `ld65: Input file '../ip65/ip65/ip65_tcp.lib' not found`, but that is what `make ip65-blob` produces when run *without* the libs. A genuine fresh clone fails earlier, at assembly: src/net/ip65/ip65_blob.s(22): Error: Cannot open include file '../../../ip65-build/ip65-c64.bin' which is the error users actually report. Both are now documented with the ordering that produces each. Reported by a second user hitting the same wall after #86 merged. #86 verified that the failure reproduces; it did not verify that its own recovery worked from a clean clone. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1a8e4b3..978e0b7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,17 +20,35 @@ backend needs none of this): git submodule update --init --recursive make ip65-libs # once per clone + make ip65-blob # once per clone — `make` will NOT do this for you make `ip65-build/ip65-c64.bin` is a **gitignored local build artifact** (`.gitignore` line `ip65-build/*.bin`; `git ls-files ip65-build/` returns -only `ip65.cfg` and `ip65_stub.s`), *not* a committed file. A plain `make` -does try to build it, but the link step consumes ip65 `.lib` archives that -the submodule does not ship — it ships the sources for them — so without -`make ip65-libs` first it dies with: +only `ip65.cfg` and `ip65_stub.s`), *not* a committed file. + +**A plain `make` does not build it and cannot.** `ip65-blob` is a phony +target, and `src/net/ip65/ip65_blob.s` pulls the file in through a ca65 +`.incbin` that make's dependency graph never sees — so there is no rule +connecting the two. A fresh clone therefore fails at assembly, before any +link, with: + + src/net/ip65/ip65_blob.s(22): Error: Cannot open include file + '../../../ip65-build/ip65-c64.bin': No such file or directory + +and it fails identically whether or not `make ip65-libs` has been run. +Running `make ip65-blob` *without* the libs is what produces the other +error you may see, since the blob's link step consumes ip65 `.lib` +archives that the submodule ships sources for rather than binaries: ld65: Error: Input file '../ip65/ip65/ip65_tcp.lib' not found +Both orderings are recoverable by running the four commands above in +order. Verified end to end on 2026-08-14 from a clean `git clone` of +master: plain `make` fails with the `.incbin` error, still fails after +`make ip65-libs`, and succeeds after `make ip65-blob` — yielding the +6,951 B blob (`cf1a5ff7...`) and a 47,105 B ip65 PRG. + `make clean` only removes `build/`, so once built the blob survives and is never rebuilt; that persistence, not a committed file, is why the rebuild targets are normally invisible. The rebuild is deterministic: 6,951 B,