Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ dist/
ip65-build/*.o
ip65-build/*.bin
ip65-build/*.map
ip65-build/*.stamp
.claude/*
!.claude/settings.json
tools/https_e2e/certs/*
Expand Down
12 changes: 9 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,14 @@ Fresh clone (ip65 backend; UCI needs none of the ip65 steps):

- `ip65-build/ip65-c64.bin` is a **gitignored artifact** (6,951 B,
sha256 `cf1a5ff7…`, deterministic). Plain `make` builds it, but it
cannot build the ip65 `.lib` archives — skip `make ip65-libs` and the
link dies with `ld65: Input file '../ip65/ip65/ip65_tcp.lib' not found`.
cannot build the ip65 `.lib` archives — skip `make ip65-libs` and make
dies `missing ip65/ip65/ip65_tcp.lib -- run 'make ip65-libs'` (#309). The
blob tracks stub, `ip65.cfg` and both libs by content
(`ip65-build/ip65-c64.stamp`, #305 shape; `-n` writes nothing); `c64.lib`
is covered only via the toolchain id and LD65_LIB/OBJ/CC65_HOME, not
hashed. The blob's own bytes are stamped too (`ip65-c64-bin.stamp`, written
by the blob rule; a stampless tree records it at the next parse), so a
same-second byte flip reaches the PRG from the first parse after a build.
- **A nested git worktree needs `git submodule update --init --recursive`
before it can link ip65** — a fresh worktree has no submodule working
trees, so the link dies by name. It fails LOUDLY; that is the whole
Expand Down Expand Up @@ -112,7 +118,7 @@ like "overflows".

Targets: `make` (PRG + `build/labels.txt` + `build/c64-https.dbg`),
`make clean` (removes `build/` only; the blob survives), `make run`,
`make ip65-libs`, `make ip65-blob` (force rebuild), `make package`,
`make ip65-libs`, `make ip65-blob` (build if stale; does not force), `make package`,
`make package-verify`.

Variables:
Expand Down
85 changes: 84 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -1057,11 +1057,94 @@ ip65-libs:
# and then reuses it — `clean` only removes build/, so it survives.
ip65-blob: $(IP65_BIN)

$(IP65_BIN): $(IP65_BUILD)/ip65_stub.s $(IP65_BUILD)/ip65.cfg
# #309: the blob's inputs are its stub, its cfg and BOTH ip65 archives. They
# used to be only the first two, so a rebuilt lib or a same-second cfg edit
# left the blob (and, through .incbin, the PRG) stale at "Nothing to be done".
# - Missing archive: the empty rule below fails the build naming it, with
# the fix, instead of ld65's "Input file ... not found" from inside a cd.
# - Archive newer than the blob: an ordinary prerequisite relinks it.
# - Content (same-second edits, a pin move that keeps mtimes): the digest
# below, in the #305 shape -- compared at PARSE time, and a change deletes
# the blob, its object and the link outputs. Absence, not an mtime.
# c64.lib lives in the cc65 install and is deliberately NOT hashed: the digest
# carries TOOLCHAIN_ID (ca65/ld65 resolved binary + sha256), which moves
# whenever the install does; locating the file would need ld65's search path.
# BACKEND=ip65 only: a UCI build never reads or requires the ip65 tree.
# `clean` and `ip65-libs` skip it (#220: they must not mutate anything), the
# dry-run flags compare and warn only (#174). A maintenance-only goal set
# (`make ip65-blob`, possibly over a UCI tree) deletes just the blob and its
# object, never the link outputs (#220). ip65-c64.stamp is gitignored.
IP65_LIBS := $(IP65_DIR)/ip65/ip65_tcp.lib $(IP65_DIR)/drivers/ip65_c64.lib
IP65_BLOB_STAMP := $(IP65_BUILD)/ip65-c64.stamp
IP65_BLOB_OBJ := build/net/ip65/ip65_blob.o
# ld65's own search-path environment (LD65_LIB, LD65_OBJ, CC65_HOME) can
# swap c64.lib without moving TOOLCHAIN_ID, so it rides in the digest too.
IP65_BLOB_STAMP_BODY := { printf 'TOOLCHAIN=%s\n' '$(TOOLCHAIN_ID)'; \
printf 'LD65_ENV=%s|%s|%s\n' '$(LD65_LIB)' '$(LD65_OBJ)' '$(CC65_HOME)'; \
for f in $(IP65_BUILD)/ip65_stub.s $(IP65_BUILD)/ip65.cfg $(IP65_LIBS); do \
(sha256sum $$f 2>/dev/null || shasum -a 256 $$f 2>/dev/null || echo "$$f MISSING"); \
done; }
IP65_BIN_STAMP := $(IP65_BUILD)/ip65-c64-bin.stamp
IP65_BIN_SHA := (sha256sum $(IP65_BIN) 2>/dev/null || shasum -a 256 $(IP65_BIN))
# Link outputs go only for a real goal; a maintenance-only goal (#220) keeps them.
IP65_RM_LINK = $(if $(STAMP_SKIP),,$(LINK_OUTPUTS))
IP65_STAMP_SKIP := $(if $(MAKECMDGOALS),$(if $(filter-out clean ip65-libs,$(MAKECMDGOALS)),,skip))

ifeq ($(BACKEND),ip65)
ifeq ($(IP65_STAMP_SKIP),)
ifeq ($(MAKE_DRY_RUN),)
_ := $(shell $(IP65_BLOB_STAMP_BODY) > $(IP65_BLOB_STAMP).tmp; \
if cmp -s $(IP65_BLOB_STAMP).tmp $(IP65_BLOB_STAMP); then \
rm -f $(IP65_BLOB_STAMP).tmp; \
else \
mv $(IP65_BLOB_STAMP).tmp $(IP65_BLOB_STAMP); \
rm -f $(IP65_BIN) $(IP65_BLOB_OBJ) $(IP65_RM_LINK); \
fi)
# The blob's own bytes, by content, for a blob changed OUTSIDE this rule (a
# byte flip, the documented provenance test): blob -> ip65_blob.o is an mtime
# edge, and a same-second flip left the object, and the PRG, stale. A change
# deletes the object and link outputs. A present blob with no stamp is only
# recorded (a pre-stamp tree). An ABSENT blob is rebuilt newer-or-equal to an
# object that may have been assembled from a flipped one, and the rule's own
# stamp then matches, so absence clears the object and link outputs too. An
# EMPTY blob (`make -t` touches one into existence) counts as absent. Last,
# a missing object always takes the link outputs with it: `make ip65-blob`
# (a maintenance goal, which keeps the PRG per #220) deletes only the object,
# and the PRG would otherwise outlive it; IP65_RM_LINK is empty for such goals.
_ := $(shell [ -s $(IP65_BIN) ] || rm -f $(IP65_BIN); \
if [ -f $(IP65_BIN) ]; then \
$(IP65_BIN_SHA) > $(IP65_BIN_STAMP).tmp; \
if [ -f $(IP65_BIN_STAMP) ] && ! cmp -s $(IP65_BIN_STAMP).tmp $(IP65_BIN_STAMP); then \
rm -f $(IP65_BLOB_OBJ) $(IP65_RM_LINK); \
fi; \
mv $(IP65_BIN_STAMP).tmp $(IP65_BIN_STAMP); \
else rm -f $(IP65_BLOB_OBJ) $(IP65_RM_LINK); \
fi; \
[ -f $(IP65_BLOB_OBJ) ] || rm -f $(IP65_RM_LINK))
else
ifneq ($(shell $(IP65_BLOB_STAMP_BODY) 2>/dev/null | cmp -s - $(IP65_BLOB_STAMP) >/dev/null 2>&1 || echo differs),)
$(warning DRY RUN (-$(MAKE_OPT_LETTERS)): ip65 blob inputs differ from $(IP65_BLOB_STAMP).)
$(warning A real build would delete $(IP65_BIN) $(IP65_BLOB_OBJ) $(IP65_RM_LINK). NOTHING was deleted.)
endif
ifneq ($(shell if [ -f $(IP65_BIN) ] && [ -f $(IP65_BIN_STAMP) ]; then $(IP65_BIN_SHA) 2>/dev/null | cmp -s - $(IP65_BIN_STAMP) >/dev/null 2>&1 || echo differs; fi),)
$(warning DRY RUN (-$(MAKE_OPT_LETTERS)): $(IP65_BIN) differs from $(IP65_BIN_STAMP).)
$(warning A real build would delete $(IP65_BLOB_OBJ) $(IP65_RM_LINK). NOTHING was deleted.)
endif
endif
endif
endif

# `+`: runs under -t/-n/-q too, so `make -t` fails by name instead of
# touching an empty file into existence where a lib should be.
$(IP65_LIBS):
+@echo "make: missing $@ -- run 'make ip65-libs' first (once per clone)." >&2; false

$(IP65_BIN): $(IP65_BUILD)/ip65_stub.s $(IP65_BUILD)/ip65.cfg $(IP65_LIBS)
cd $(IP65_BUILD) && $(CA65) -I ../$(IP65_DIR) ip65_stub.s -o ip65_stub.o
cd $(IP65_BUILD) && $(LD65) -C ip65.cfg -o ip65-c64.bin -m ip65-c64.map \
ip65_stub.o ../$(IP65_DIR)/ip65/ip65_tcp.lib \
../$(IP65_DIR)/drivers/ip65_c64.lib c64.lib
$(IP65_BIN_SHA) > $(IP65_BIN_STAMP)

run: $(PRG)
$(VICE) -autostart $(PRG)
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -542,7 +542,8 @@ with no intermediate step.

What `make` cannot do for you is build the ip65 `.lib` archives the blob
links against, so run `make ip65-libs` once per clone, as in "Before you
build or test" above; `make ip65-blob` exists only to force a rebuild. The
build or test" above; `make ip65-blob` builds it if stale (it does not force; flip a byte
of the blob to test provenance). The
build is deterministic: 6,951 B, sha256 `cf1a5ff7809af4e4655e385b378b936054f41046ff2b7604828af3240c2d90dd`.
`make clean` does not remove it, which is why the step is normally
invisible. The UCI backend does not use the blob at all.
Expand Down
14 changes: 9 additions & 5 deletions docs/engineering-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,17 @@ error above. The fix changes no output: the ip65 PRG hashes

What plain `make` still cannot do for you is build the ip65 `.lib`
archives — the submodule ships sources, not binaries. Skip
`make ip65-libs` and the blob rule runs and dies at its link:
`make ip65-libs` and (since #309) make dies before the link, naming the lib:

ld65: Error: Input file '../ip65/ip65/ip65_tcp.lib' not found
make: *** [ip65-build/ip65-c64.bin] Error 1
make: missing ip65/ip65/ip65_tcp.lib -- run 'make ip65-libs' first (once per clone).
make: *** [ip65/ip65/ip65_tcp.lib] Error 1

(Before #309 the libs were not prerequisites, and the blob rule died inside
its own ld65 line: `ld65: Error: Input file '../ip65/ip65/ip65_tcp.lib' not found`.)

So: `make ip65-libs` once per clone, then plain `make`. `make ip65-blob`
exists only to force a rebuild.
builds the blob if stale (it does not force a rebuild; #309 made a rebuilt
lib or a content edit of stub/cfg count as stale).

**Worktree trap — RETIRED by #116; the rule that survives it is
different.** Recorded in full because this section asserted the old rule
Expand Down Expand Up @@ -143,7 +147,7 @@ Targets:
- `make ip65-blob` — rebuild `ip65-build/ip65-c64.bin` from those
libraries. A plain `make` already builds the
blob on demand and then reuses it, so this
target is only for forcing a rebuild.
target only builds when stale (it does not force).

**`make clean` after a flag change — RETIRED by #159. The measurements
below are why it existed, and are kept for that reason.**
Expand Down
10 changes: 5 additions & 5 deletions tools/package/build_prgs.sh
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@
# into every .o header — but ld65 does not propagate it, so the PRG is
# deterministic and comparable.
#
# Also bootstraps the ip65 blob (`ip65-build/ip65-c64.bin`), which is a
# gitignored artifact a plain `make` will NOT build: a fresh clone dies in the
# ca65 `.incbin` before any link.
# Also bootstraps the ip65 libs and blob (`ip65-build/ip65-c64.bin`), a
# gitignored artifact whose libs a plain `make` will NOT build: a fresh clone
# dies in make, naming the missing ip65 .lib (#309).
#
# Writes dist/build-info.txt (git HEAD, submodule pins, per-variant args/size/
# sha256). write_manifest.sh consumes it.
Expand Down Expand Up @@ -95,8 +95,8 @@ git diff --quiet HEAD -- 2>/dev/null || GIT_DIRTY=" (working tree DIRTY)"

# --- ip65 blob bootstrap ------------------------------------------------------
IP65_BIN="$PROJECT_ROOT/ip65-build/ip65-c64.bin"
if [ ! -f "$IP65_BIN" ]; then
echo "[package] ip65 blob absent — bootstrapping (make ip65-libs && make ip65-blob)"
if [ ! -f "$IP65_BIN" ] || [ ! -f "$PROJECT_ROOT/ip65/ip65/ip65_tcp.lib" ] || [ ! -f "$PROJECT_ROOT/ip65/drivers/ip65_c64.lib" ]; then
echo "[package] ip65 blob or libs absent — bootstrapping (make ip65-libs && make ip65-blob)"
if [ ! -e "$PROJECT_ROOT/ip65/Makefile" ]; then
echo "ERROR: ip65 submodule not checked out. Run:" >&2
echo " git submodule update --init --recursive" >&2
Expand Down
Loading