Makefile

# Makefile — ca65/ld65 build for c64-https
#
# Targets:
#   make              — default, produces build/c64-https.prg + build/labels.txt
#   make clean        — remove build artifacts
#   make run          — launch the PRG in VICE x64sc
#   make ip65-libs    — build ip65 object libraries from the submodule
#                       (required once per fresh clone, BACKEND=ip65 only)
#   make ip65-blob    — rebuild ip65-build/ip65-c64.bin (requires ip65-libs first)
#
# Variables:
#   BACKEND=ip65|uci  — select networking backend config (default: ip65)
#   CA65, LD65        — ca65 / ld65 binaries (default: cc65 toolchain in PATH)
#   VICE              — VICE binary for `make run` (default: x64sc)


# General hygiene: drop any target whose recipe wrote it and then failed, so
# a half-written generated file is never mistaken for a good one.
#
# NOTE this does NOT cover the case issue #128 turned up, and it was tried
# there first. `.DELETE_ON_ERROR` deletes a target only if the recipe CHANGED
# it, and ld65 on a memory-area overflow writes nothing at all — so the old
# PRG's mtime is untouched and make correctly declines to delete it
# (verified: file identical, same timestamp, after a deliberately overflowing
# link). The link rule below therefore removes its own target up front.
.DELETE_ON_ERROR:

CA65      ?= ca65
LD65      ?= ld65
VICE      ?= x64sc
BACKEND   ?= ip65
CFG       := cfg/c64-https-$(BACKEND).cfg

# --- Sibling X25519 integration (Phase C.5, c64-x25519 v0.4.0) ---
# `USE_X25519_SIBLING=1` swaps in `build/lib/x25519.a` for the in-tree
# `src/crypto/fe25519.s` + `src/crypto/x25519.s` + in-tree X25519 data
# buffers from `src/data.s`. Default OFF — the in-tree implementation
# stays the shipped default until the supervisor + validator sign off
# on the sibling drop-in. The flag is read at link time; both code
# paths coexist on the branch so an A/B comparison is `make` vs
# `make USE_X25519_SIBLING=1`.
USE_X25519_SIBLING ?= 0

IP65_DIR     := ip65
IP65_BUILD   := ip65-build
IP65_BIN     := $(IP65_BUILD)/ip65-c64.bin

CA65FLAGS := -I src -I src/inc -I src/crypto/shared -I src/net -I src/net/$(BACKEND) -I build --debug-info
# Binary-include search roots for `.incbin` (issue #116).
#
# `-I` above does NOT feed `.incbin` — that is a separate search path in ca65,
# and pointing `-I` at a blob directory fails with "Cannot open include file"
# even though the file is right there (measured, ca65 V2.18). Binary includes
# need `--bin-include-dir`.
#
# Why this exists at all: ca65 resolves a relative `.incbin` operand against
# the CURRENT DIRECTORY FIRST, falling back to the including source file's
# directory only if that misses. Every `.incbin` here used to be spelled
# `../../../<dir>/<file>` on the belief that source-relative was the rule. From
# the repo root those two interpretations coincide, so it worked — but an agent
# worktree lives at `.claude/worktrees/<name>/`, exactly three levels down, so
# `../../../` climbed straight out into the PRIMARY checkout and every worktree
# build silently embedded the primary's blob. The worktree's own freshly-built
# copy was never read, by anything, while make's dependency graph tracked it.
#
# ABSOLUTE paths, not relative: a relative root would be cwd-relative and would
# re-acquire the same class of bug the moment any recipe assembles from a
# subdirectory. `$(abspath ...)` pins these to make's own working directory.
# The operands in the sources are then written WITHOUT any `../`, so there is
# no escape hatch left to resolve. A missing blob now fails the assemble
# loudly instead of quietly resolving somewhere else.
CA65FLAGS += --bin-include-dir $(abspath $(IP65_BUILD))
CA65FLAGS += --bin-include-dir $(abspath build)
# Which backend is selected, as a ca65 define. Sources that must name a
# cfg-level symbol need this, because the two cfgs give the same region
# different names: the crypto code+rodata region is CRYPTO_HOT under UCI and
# CRYPTO_RESIDENT under ip65, so the ld65-published __<AREA>_SIZE__ symbol an
# `.import` has to spell differs by backend (src/contract_footprint_asserts.s
# is the current consumer). The `-I src/net/$(BACKEND)` path above cannot
# serve this: it carries net tuning, and region naming is a cfg property, not
# a networking one.
ifeq ($(BACKEND),uci)
CA65FLAGS += -D BACKEND_UCI=1
# Issue #135: server name validation (src/x509_name.s) is UCI-only.
#
# Not a scope judgement — a size one, and the numbers are why. The routine is
# 491 B. ip65's largest free block is 170 B (NET_CODE tail); its other regions
# hold 40 B (CRYPTO_RESIDENT), 22 B (CRYPTO_OVERLAY) and 16 B (LOADER). There
# is nowhere to put it without a memory-map restructure, and ip65 cannot reach
# a real internet server anyway (~36 min/handshake against ~45-100 s of server
# patience), so the check has the least to do exactly where it does not fit.
# Documented in README and tracked on #135 rather than left to be discovered.
CA65FLAGS += -D X509_VERIFY_NAME=1
else
CA65FLAGS += -D BACKEND_IP65=1
endif
# Optional HTTPS target-port override (src/boot.s defaults to 443).
# `make HTTPS_PORT=4433` lets a test rig's TLS listener bind unprivileged.
ifdef HTTPS_PORT
CA65FLAGS += -D HTTPS_PORT=$(HTTPS_PORT)
endif
# W4 REU body sink: HTTPS_BODY_TO_REU=1 makes boot.s's do_https_get set
# http_body_sink=1, streaming the HTTP response body into the REU at
# HTTP_REU_BODY_BASE (default $10:0000 = bank 16 — needs a 16 MB REU;
# see src/constants.inc).  UCI-only: the sink code is compiled out of
# ip65 builds, so the flag is only honored under BACKEND=uci.
ifeq ($(BACKEND),uci)
ifdef HTTPS_BODY_TO_REU
CA65FLAGS += -D HTTPS_BODY_TO_REU=1
endif
endif
# Optional HTTPS target-host override (default www.foo.invalid — RFC 2606 /
# RFC 6761 reserved, so a default build cannot dial anything real).
# `make HTTPS_HOST=github.com` retargets the GET + SNI + DNS lookup.
# ca65's -D accepts numeric values only, so the hostname travels via a
# generated include (build/https_host.inc, reached through `-I build`).
# The generator rule is content-compared: changing HTTPS_HOST= rebuilds
# boot.o with no `make clean`, and an unchanged value touches nothing.
# This value is BAKED INTO THE SHIPPED PRG. It must stay under a TLD the
# DNS can never answer for: pressing G on a default build dials it, on
# whatever LAN the machine is on. `.bar` (the predecessor) is a live gTLD.
# tools/test_reserved_test_host.py fails if this stops being true, and it
# tracks the property, not the spelling — `foo.baz` fails it too.
HTTPS_HOST ?= www.foo.invalid
# Companion request-path override (default "/"), same mechanism/caveats.
# e.g. make HTTPS_PATH='/w/index.php?title=Commodore_64&action=raw'
HTTPS_PATH ?= /
# Debug knob: present a DIFFERENT SNI than the connect host (default:
# SNI = host, unchanged). Lets the C64 dial a local TCP relay while the
# ClientHello names the real origin — e.g. tcpdump forensics via
#   make HTTPS_HOST=10.43.23.99 HTTPS_PORT=8443 HTTPS_SNI=en.wikipedia.org
# UCI-only, off unless set; empty means no override.
HTTPS_SNI ?=
ifneq ($(strip $(HTTPS_SNI)),)
CA65FLAGS += -D HTTPS_SNI_OVERRIDE=1
endif
# Optional REU document-base override, shared by the http.s body sink
# and the Lane G viewer (both read the HTTP_REU_BODY_BASE equate /
# runtime var; defaults to $10:0000 = 1048576). VICE tests use a
# 512 KB REU, so they build with a base inside it:
# `make BACKEND=uci HTTP_REU_BODY_BASE=196608` ($03:0000; decimal —
# ca65 -D does not take 0x, and $ needs shell quoting).
ifdef HTTP_REU_BODY_BASE
CA65FLAGS += -D HTTP_REU_BODY_BASE=$(HTTP_REU_BODY_BASE)
endif
# Viewer test helpers (viewer_test_blit RAM->REU blit + viewer_scroll_up).
# Test-image only; never set for a shipping build.
ifdef VIEWER_TEST_HELPERS
CA65FLAGS += -D VIEWER_TEST_HELPERS=1
endif
# VIC-II blanking around the CPU-bound crypto primitives (src/vic.s).
# ON by default and that is what ships; `make VIC_BLANK=0` degrades
# vic_blank/vic_unblank to bare RTS so the badline tax can be measured
# A/B with everything else in the image identical. That control build is
# a measurement tool, not a shipping configuration — see the "VIC-II
# blanking" section of CLAUDE.md for the numbers it produced.
ifeq ($(VIC_BLANK),0)
CA65FLAGS += -D NO_VIC_BLANK=1
endif
# W1 streaming handshake-message deframer (src/tls_deframe.s + the
# TLS_STREAM_DEFRAME paths in src/tls13.s / tls_cert.s /
# tls_keyschedule.s). Lets the client process a real server's encrypted
# flight where handshake messages do not align with TLS records (one
# message spanning several records; several messages sharing one
# record). Default ON under UCI, OFF under ip65: the ip65 image has
# neither the code headroom nor any BSS slack for the deframer state +
# carry buffer (~330 B). Override with TLS_STREAM_DEFRAME=0|1 —
# forcing it on under ip65 is expected to overflow the link.
ifeq ($(BACKEND),uci)
TLS_STREAM_DEFRAME ?= 1
else
TLS_STREAM_DEFRAME ?= 0
endif
ifeq ($(TLS_STREAM_DEFRAME),1)
CA65FLAGS += -D TLS_STREAM_DEFRAME=1
endif
# Lazy (=) so the USE_NISTCURVES_ONCHIP_COMB block below can retarget
# CFG to the cfg variant after this line.
LD65FLAGS = -C $(CFG) -Ln build/labels.txt -m build/c64-https.map --dbgfile build/c64-https.dbg

# Source inventory.
TOP_SRCS    := $(wildcard src/*.s)
# Crypto sources: wildcard-discovered. In-tree src/crypto/x25519.s +
# src/crypto/fe25519.s are used under both backends; the Phase C.1
# libs/x25519/ overlay integration was rolled back after it broke the
# TLS handshake under BACKEND=uci at 48 MHz — see the commit that
# removed libs/x25519 for details.
# Phase C.4: the in-tree P-256 primitives (ecdsa_{curve,fp,mod,points}.s)
# were replaced by the sibling `libs/nistcurves/` P-256 integration
# (build/lib/nistcurves-p256.a). The now-unused files were physically
# deleted in Phase G. ecdsa_verify.s stays — rewritten as a thin
# dispatcher that packs the BE struct + calls ecdsa_verify_256.
CRYPTO_SRCS_ALL := $(wildcard src/crypto/*.s)
# Shared crypto infrastructure introduced in Phase C.0: canonical ZP map,
# overlay swap dispatcher, init orchestrator, shared sqtab stub. Always
# linked; sibling-lib integration (Phase C.3) hangs off these.
CRYPTO_SHARED_SRCS := $(wildcard src/crypto/shared/*.s)
IP65_SRCS   := src/net/ip65/ip65_blob.s src/net/ip65/net.s src/net/ip65/net_banner.s src/net/ip65/exports.s src/net/ip65/net_manifest.s
UCI_SRCS    := src/net/uci/net.s src/net/uci/uci_cmd.s src/net/uci/net_manifest.s

# Sibling-lib archive set. Phase C.3's nistcurves-p384 archive remains an
# external overlay image (see below), not linked into the main PRG.
# Phase C.4 adds nistcurves-p256.a which IS linked in, always-resident,
# for BOTH backends (replaces the in-tree ecdsa_{curve,fp,mod,points}.s).
#
# USE_NISTCURVES_ONCHIP=1 (issue #69 / nistcurves v0.5.0): swap in the
# FP_ONCHIP_MUL turbo-profile archive — fp_mul/fp_sqr generate multiply
# rows on-chip instead of REU DMA row fetches, removing the ~1 MHz-anchored
# DMA floor on turbo hosts (crossover ~30 MHz; see docs/engineering-notes.md "Why turbo
# stops paying"). Gates: data.s yields sqtab to the lib's $BC00 equates,
# poly1305.s provides the §8.3 canonical ct_mul_8x8 + SMC bake sites,
# boot.s skips reu_mul_init + yields the reu_fetch_mul_row export.
# USE_NISTCURVES_ONCHIP_COMB=1: comb-accelerated onchip profile — the
# comb ecdsa256 + points256_comb + Lim-Lee data replace the no-comb
# verifier (u1*G via 8-way fixed-base comb instead of a second
# variable-base ladder). Implies USE_NISTCURVES_ONCHIP; adds the
# ec_precompute_256 boot pass (REU bank 2 $0000-$3FFF anchors) and
# switches to the CRYPTO_HOT-relieving cfg variant.
ifeq ($(USE_NISTCURVES_ONCHIP_COMB),1)
USE_NISTCURVES_ONCHIP := 1
endif
ifeq ($(USE_NISTCURVES_ONCHIP),1)
ifeq ($(USE_X25519_SIBLING),1)
$(error USE_NISTCURVES_ONCHIP and USE_X25519_SIBLING are mutually exclusive for now: both archives export reu_fetch_mul_row)
endif
ifeq ($(USE_OVERLAY_P384_EMBED),1)
$(error USE_NISTCURVES_ONCHIP places LIB_NISTCURVES_MUL_CODE in CRYPTO_OVERLAY - mutually exclusive with USE_OVERLAY_P384_EMBED)
endif
ifeq ($(EMBED_P256_OVERLAY),1)
$(error USE_NISTCURVES_ONCHIP places LIB_NISTCURVES_MUL_CODE in CRYPTO_OVERLAY - mutually exclusive with EMBED_P256_OVERLAY)
endif
CA65FLAGS += -D USE_NISTCURVES_ONCHIP=1

ifeq ($(USE_NISTCURVES_ONCHIP_COMB),1)
SIBLING_LIB_ARCHIVES := build/lib/nistcurves-p256-onchip-comb.a
CA65FLAGS += -D USE_NISTCURVES_COMB=1
CFG := cfg/c64-https-$(BACKEND)-onchip.cfg
else
SIBLING_LIB_ARCHIVES := build/lib/nistcurves-p256-onchip.a
endif
else
SIBLING_LIB_ARCHIVES := build/lib/nistcurves-p256.a
endif

# Phase C.5 (USE_X25519_SIBLING=1): c64-x25519 v0.4.0 sibling, always-resident,
# replaces in-tree fe25519.s + x25519.s + X25519 buffers in src/data.s.
# Off by default.
ifeq ($(USE_X25519_SIBLING),1)
SIBLING_LIB_ARCHIVES += build/lib/x25519.a
# Propagate the flag to ca65 so src/data.s suppresses the in-tree X25519
# buffer declarations (the sibling's data_x25519_raw.s provides them).
CA65FLAGS += -D USE_X25519_SIBLING=1

# Split the sibling's code across CRYPTO_HOT and CRYPTO_OVERLAY. This is
# what makes USE_X25519_SIBLING=1 link at all under UCI, so it is a
# default rather than something the operator has to know.
#
# The sibling's 4,470 B of code (v0.16.0: 2,750 + 717 + 216 + 787) does
# not fit either region whole: CRYPTO_HOT has ~3.3 KB of room for it
# (measured), and CRYPTO_OVERLAY has ~3.7 KB once the sibling's own
# 3,840 B of tables and BSS are in there -- that is 2,304 B of RODATA
# plus 1,536 B of BSS, and it is NOT the 3840 in the overflow warning
# below, which is X25519_RODATA's linked size. The collision is a
# coincidence; do not read one for the other. Leaving the ladder (717 B)
# and the boot-only table init (787 B) in CRYPTO_OVERLAY satisfies
# both. Under USE_X25519_SIBLING=1 that
# region is not a paged overlay -- both embed flags that page it are
# mutually exclusive with this one -- so it is plain resident RAM.
#
# X25519_RODATA is the wrong NAME for executable code; it is used only
# because it is the one segment both backend cfgs already route into
# CRYPTO_OVERLAY. The clean form is a cfg declaring the SPEC §4 names
# (LIB_X25519_CODE / LIB_X25519_INIT_CODE / LIB_X25519_DATA); at that
# point these two lines and the wrapper's sed both go away.
#
# NEITHER BACKEND LINKS under USE_X25519_SIBLING=1, and each dies on a
# different segment. Figures below are the literal ld65 warning, measured
# at submodule pin v0.16.0 and identical at v0.13.0:
#
#   ip65  Segment 'X25519_RODATA' overflows memory area 'CRYPTO_OVERLAY'
#         by 3840 bytes   (cfg/c64-https-ip65.cfg:103)
#   uci   Segment 'X25519_BSS'    overflows memory area 'CRYPTO_OVERLAY'
#         by 1536 bytes   (cfg/c64-https-uci.cfg:120)
#
# ip65's CRYPTO_OVERLAY is 4,212 B and already holds TLS_CODE +
# CRYPTO_AUX_CODE + HTTP_AUX_CODE; uci's is 7.5 KB but already holds
# TLS_DEFRAME_CODE + CERT_BUF_BSS + HTTPS_TARGET_RODATA + x509_name.
#
# NEITHER NUMBER IS A TOTAL DEFICIT. ld65 does not stop at the first area
# it cannot fill -- it walks every memory area and warns ONCE PER AREA,
# on the first segment whose placement pushes that area past its size,
# reporting the overflow at that instant. Every segment routed into the
# same area afterwards is uncounted: ip65's 3840 omits X25519_BSS
# entirely. Relink against an enlarged CRYPTO_OVERLAY and X25519_BSS ends
# at $74FF against an area ending at $5FFF -- a real shortfall of $1500,
# 5,376 B.
#
# The 3840 IS X25519_RODATA's linked size, exactly. Two reasons it is not
# the figure you get by summing per-source od65 rows (build_x25519.sh),
# and both need stating because they cancel:
#
#   1. INSIDE the segment: our own generated RODATA module is align=$100,
#      so ld65 inserts 32 B of fill ahead of it. The objects therefore
#      link as a larger segment than their sizes sum to (map: Offs=0002CD
#      + 000313 then Offs=000600 with Fill=0020).
#   2. BEFORE the segment: CRYPTO_OVERLAY ends on a page boundary ($5FFF)
#      and X25519_RODATA is page-aligned, so the alignment pad always
#      consumes exactly whatever headroom the prior tenants left --
#      HTTP_AUX_CODE ends at $5FE9, so 22 B here -- and the area is at
#      exactly 100% before the first X25519 byte is placed.
#
# So the prior tenants contribute ZERO to the reported overflow, and
# 3840 is not a "shrink X25519_RODATA by 3,840 B and it links" number.
# See build_x25519.sh, and docs/engineering-notes.md for the two relink
# experiments that established all of this.
export X25519_INIT_SEGMENT ?= X25519_RODATA
export X25519_SEG_LADDER   ?= X25519_RODATA
endif

# Phase C.5: under USE_X25519_SIBLING=1, evict the in-tree X25519
# implementation from the link line — the sibling archive
# (build/lib/x25519.a) provides byte-compatible exports for x25519_*
# and a richer fe25519_* surface than the in-tree fe_* symbols.
ifeq ($(USE_X25519_SIBLING),1)
CRYPTO_SRCS_EFFECTIVE := $(filter-out src/crypto/fe25519.s src/crypto/x25519.s,$(CRYPTO_SRCS_ALL))
else
CRYPTO_SRCS_EFFECTIVE := $(CRYPTO_SRCS_ALL)
endif

# ENABLE_P384_VERIFY=1 — re-arms the P-384 verify arm in
# src/crypto/ecdsa_verify.s. OFF BY DEFAULT AND UNSAFE ON ITS OWN.
#
# The arm calls crypto_swap_to_p384_sha384, which DMAs $1E00 bytes from REU
# banks that only reu_p384_overlay_init writes — and that routine is itself
# `.ifdef USE_OVERLAY_P384_EMBED`, which no shipped build sets and which
# cannot currently be built at all (the SHA-384 table overflows OVERLAY_REGION
# by 1,536 B; see "Known issues"). Setting this flag WITHOUT a working overlay
# reproduces the c64-https#128-era hazard on purpose: live resident code
# overwritten, machine hung.
#
# It exists so the guard can be mutation-tested — a safety gate nobody can
# switch off is a gate nobody can prove is load-bearing. Turning it on is
# expected to make tools/test_p384_overlay_hazard.py FAIL.
#
# TOP LEVEL ON PURPOSE. This block used to sit inside
# `ifeq ($(USE_NISTCURVES_ONCHIP),1)`, so the two REU-profile builds — plain
# `make` and `make BACKEND=uci` — dropped the -D silently and the flag did
# nothing at all. Measured at the previous commit, PRG sha256, ip65 REU
# profile:
#
#   make BACKEND=ip65                       d780f719fac82e07…
#   make BACKEND=ip65 ENABLE_P384_VERIFY=1  d780f719fac82e07…   <- identical
#
# and the same for BACKEND=uci (7c79a4e00a19685d… both ways). The mutation
# test that proves this gate is load-bearing was a no-op on two of the five
# configurations. The three onchip profiles were unaffected and their armed
# PRGs are byte-identical across this move.
#
# The two P-384-only objects are gated on the SAME flag, so the lane is one
# switch and not two half-switches:
#
#   src/crypto/ecdsa_verify_384.s  the TLS-side P-384 dispatcher. Its only
#                                  export is ecdsa_verify_384_tls, and the
#                                  only `.import` of that symbol anywhere is
#                                  the one inside ecdsa_verify.s's
#                                  `.ifdef ENABLE_P384_VERIFY`. ca65 emits no
#                                  import record for an .import nothing
#                                  references, so with the flag off the object
#                                  was linked and UNREACHABLE: it appears in
#                                  no Imports-list entry of any of the five
#                                  build/c64-https.map files, and od65
#                                  --dump-imports on ecdsa_verify.o does not
#                                  list it. It cost 299 B of CRYPTO_AUX_CODE +
#                                  33 B of CRYPTO_RODATA + 2 B of BSS in every
#                                  shipped image.
#   src/crypto/p384_force_link.s   already inert: its entire body is
#                                  `.ifdef USE_NISTCURVES_P384`, and nothing
#                                  defines that symbol today (the CA65FLAGS
#                                  line for it is commented out below). Zero
#                                  bytes either way; gated here so the lane's
#                                  file set lives in one place.
#
# What this does NOT do: it does not delete the P-384 lane. Both files stay in
# tree, as does every other piece of P-384 plumbing, on the same policy the
# retired EMBED_P256_OVERLAY follows. `ENABLE_P384_VERIFY=1` restores the
# previous link line; the three onchip profiles' armed PRGs are byte-identical
# to the pre-gating ones (b9f03169…, 3c271262…, cc555c19…).
P384_SRCS := src/crypto/ecdsa_verify_384.s src/crypto/p384_force_link.s
ifeq ($(ENABLE_P384_VERIFY),1)
CA65FLAGS += -D ENABLE_P384_VERIFY=1
else
CRYPTO_SRCS_EFFECTIVE := $(filter-out $(P384_SRCS),$(CRYPTO_SRCS_EFFECTIVE))
endif

# Per-backend source + object selection.
ifeq ($(BACKEND),ip65)
NET_SRCS := $(IP65_SRCS)
CRYPTO_SRCS := $(CRYPTO_SRCS_EFFECTIVE)
else ifeq ($(BACKEND),uci)
NET_SRCS := $(UCI_SRCS)
CRYPTO_SRCS := $(CRYPTO_SRCS_EFFECTIVE)

# --- W3 (RETIRED, see the guard below): EMBED_P256_OVERLAY=1 was meant
# to stage the P-256 verify .bin as a .incbin into CRYPTO_OVERLAY at
# PRG-load time, mutually exclusive with USE_OVERLAY_P384_EMBED (same
# slot at $4200).  The user-visible flag is `EMBED_P256_OVERLAY`; the
# ca65-level symbol `USE_OVERLAY_P256_EMBED` gates the .incbin in
# src/crypto/shared/p256_overlay_blobs.s and the boot stash in boot.s.
# Both default to 0 so the un-flagged UCI build is unchanged.
EMBED_P256_OVERLAY ?= 0
USE_OVERLAY_P256_EMBED ?= $(EMBED_P256_OVERLAY)

# Issue #118: the W3 P-256 overlay embed cannot be built and, if it could,
# would corrupt the running image. Fail here rather than three rules later
# with an error that names a library segment (c64-lib-contract §6.3: a knob
# naming an axis selects it or fails loudly; §6.3 was retired at contract
# v1.0.0 and resolves at tag v0.17.1). Two independent reasons,
# both measured at libs/nistcurves v0.11.2:
#   1. LIB_NISTCURVES_P256_CODE is 8,324 B; OVERLAY_REGION is 7,680 B.
#      The 644 B shortfall survived every pin from v0.7.0 to v0.11.2, so
#      it is structural, not drift.
#   2. CRYPTO_OVERLAY ($4200-$5FFF) is no longer a free paging slot: every
#      UCI build keeps TLS_DEFRAME_CODE, CERT_BUF_BSS, X509_NAME_CODE and
#      HTTPS_TARGET_RODATA resident there (~5 KB). crypto_swap_to_p256_verify
#      DMAs $1E00 bytes over that span - the same hazard class as the
#      P-384 overlay corruption fixed in v0.4.1.
# The resident P-256 verify in CRYPTO_HOT is what every shipped product
# uses; the overlay plumbing stays in tree for a future memory-map rework.
ifeq ($(EMBED_P256_OVERLAY),1)
$(error EMBED_P256_OVERLAY=1 is retired (issue #118): the P-256 verify image is 644 B larger than OVERLAY_REGION, and CRYPTO_OVERLAY now holds resident deframer/cert_buf/name-check code that the swap would overwrite. The resident verify in CRYPTO_HOT is the supported path)
endif
ifeq ($(USE_OVERLAY_P256_EMBED),1)
$(error USE_OVERLAY_P256_EMBED=1 is the ca65-level half of EMBED_P256_OVERLAY, which is retired (issue #118))
endif

# Phase 3: embed the two P-384 split overlay blobs in the PRG so boot
# can populate REU banks 6/7 at startup.  Gated to UCI (ip65 has no
# room for the SHA blob in main RAM) and to !USE_X25519_SIBLING (the
# sibling rodata occupies CRYPTO_OVERLAY at PRG load time, displacing
# the SHA blob).  Adds a build-order dep on the .bin files; a missing
# .bin causes the .incbin to fail, so we extend PRG_DEPS below.
ifneq ($(USE_X25519_SIBLING),1)
# Phase 5 Fix D: respect a command-line USE_OVERLAY_P384_EMBED=0 so the
# bootstrap rule below can do a no-overlay-embed prelim link to break
# the overlay-bin <-> labels.txt cycle on a clean tree.  Default is
# still 1 unless the operator explicitly disables it.  W3: also
# auto-turn-off when EMBED_P256_OVERLAY=1 (mutually-exclusive slot).
ifeq ($(EMBED_P256_OVERLAY),1)
USE_OVERLAY_P384_EMBED ?= 0
else
# W5 / libs/nistcurves cfa9085+ bump: PR #25's SHA-384 rotr LUTs
# (LIB_NISTCURVES_SHA384_TABLES, 3 KB page-aligned) push the SHA-384
# overlay-half archive above the 7.5 KB CRYPTO_OVERLAY slot limit by
# ~1.5 KB. Default flips to 0 until the SHA-384 LUTs are either:
#   - relocated out of the overlay slot (consumer-side path: route
#     LIB_NISTCURVES_SHA384_TABLES to a separate resident region and
#     teach the standalone overlay cfg to omit them from the .bin), or
#   - shrunk on the library side (eg by sharing rotr LUTs across the
#     8 shift amounts, or runtime-generating them at boot).
# Set USE_OVERLAY_P384_EMBED=1 explicitly to attempt the embed (will
# fail at link with an overflow until the SHA-384 LUTs are dealt with).
USE_OVERLAY_P384_EMBED ?= 0
endif
ifeq ($(USE_OVERLAY_P384_EMBED),1)
CA65FLAGS += -D USE_OVERLAY_P384_EMBED=1
endif
endif

# W3: propagate USE_OVERLAY_P256_EMBED to ca65 (the .incbin in
# src/crypto/shared/p256_overlay_blobs.s is gated on this).  The
# default-derivation from EMBED_P256_OVERLAY happens above.
ifeq ($(USE_OVERLAY_P256_EMBED),1)
CA65FLAGS += -D USE_OVERLAY_P256_EMBED=1
endif
# Phase C.3: add c64-nist-curves P-384 primitives as a REU overlay.
# Variable-base P-384 point ops (double/add/jacobian-to-affine) only —
# see tools/integration/build_nistcurves_p384.sh for the scope rationale.
# `USE_NISTCURVES_P384` toggles the `.ifdef` guard in
# src/crypto/p384_force_link.s so ld65 pulls the archive members into
# the final PRG. P-256 ECDSA stays in-tree under both backends.
# Phase C.3 is BLOCKED at the cfg level: the current CRYPTO_OVERLAY region
# (7.5 KB at $4200) can only hold one of OVERLAY_X25519 (3.4 KB) and
# OVERLAY_P384 (5.7 KB) at a time; ld65 lays them out sequentially and
# overflows by 1.6 KB. Architecturally max(x25519,p384)=5.7 KB ≤ 7.5 KB,
# so the slot is large enough — what's missing is the `run=CRYPTO_OVERLAY,
# load=<separate staging>` cfg plumbing plus a boot-time stash for both
# images. That restructure is out of scope for Phase C.3 and is gated on
# a supervisor OK. The archive + force-link stub are in place so the
# integration can be re-enabled by uncommenting the two lines below once
# the cfg is extended.
#CA65FLAGS += -D USE_NISTCURVES_P384=1
# Phase 1.5 split the monolithic nistcurves-p384.a into two halves
# (nistcurves-p384-sha384.a + nistcurves-p384-curve.a) since the
# combined image overflowed the live 7.5 KB CRYPTO_OVERLAY slot.
# Either-of approach for the production wire-up will be Phase 4a.
#SIBLING_LIB_ARCHIVES += build/lib/nistcurves-p384-sha384.a
#SIBLING_LIB_ARCHIVES += build/lib/nistcurves-p384-curve.a
else
$(error Unknown BACKEND=$(BACKEND); expected ip65 or uci)
endif

TOP_OBJS    := $(patsubst src/%.s,build/%.o,$(TOP_SRCS))
CRYPTO_OBJS := $(patsubst src/%.s,build/%.o,$(CRYPTO_SRCS))
CRYPTO_SHARED_OBJS := $(patsubst src/%.s,build/%.o,$(CRYPTO_SHARED_SRCS))
NET_OBJS    := $(patsubst src/%.s,build/%.o,$(NET_SRCS))

ALL_OBJS := $(TOP_OBJS) $(CRYPTO_OBJS) $(CRYPTO_SHARED_OBJS) $(NET_OBJS)

PRG    := build/c64-https.prg
LABELS := build/labels.txt

.PHONY: all link run clean ip65-libs ip65-blob package package-verify

all: $(PRG)

ifeq ($(BACKEND),ip65)
PRG_DEPS := $(ALL_OBJS) $(IP65_BIN) $(SIBLING_LIB_ARCHIVES)
else ifeq ($(BACKEND),uci)
PRG_DEPS := $(ALL_OBJS) $(SIBLING_LIB_ARCHIVES)
else
PRG_DEPS := $(ALL_OBJS)
endif

# Phase 3: when USE_OVERLAY_P384_EMBED is on, add the two .bin files
# to PRG_DEPS so make builds them before the .incbin in
# src/crypto/shared/p384_overlay_blobs.s tries to read them.
ifeq ($(USE_OVERLAY_P384_EMBED),1)
PRG_DEPS += build/lib/overlay-p384-sha384.bin build/lib/overlay-p384-curve.bin
PRG_DEPS += build/p384_overlay_equates.inc
build/crypto/shared/p384_overlay_blobs.o: build/lib/overlay-p384-sha384.bin build/lib/overlay-p384-curve.bin
endif

# W3: when USE_OVERLAY_P256_EMBED is on, add the P-256 verify .bin to
# PRG_DEPS so make builds it before the .incbin in
# src/crypto/shared/p256_overlay_blobs.s tries to read it.  The .bin
# rule below also has an order-only dep on build/labels.txt for the
# main-PRG label lookup (same bootstrap cycle as P-384).  Gated on the
# ca65-level USE_OVERLAY_P256_EMBED rather than EMBED_P256_OVERLAY so
# the bootstrap prelim link (with USE_OVERLAY_P256_EMBED=0) skips the
# .bin dep cleanly.
ifeq ($(USE_OVERLAY_P256_EMBED),1)
PRG_DEPS += build/lib/nistcurves-p256-verify.bin
build/crypto/shared/p256_overlay_blobs.o: build/lib/nistcurves-p256-verify.bin
endif

# Issue #128: the recipe removes the old image BEFORE linking. ld65 writes
# nothing when a memory area overflows, so without this a failed link silently
# leaves the PREVIOUS build/c64-https.prg on disk — and every rig loads that
# path by name (tools/uci/rig_https_wiki.py:135). The operator then runs a
# stale image carrying the OLD HTTPS_HOST and reports "the build knob did
# nothing" instead of "the build failed". Absence is the honest state after a
# failure.
#
# Kept OUT of the recipe deliberately: make echoes recipe comment lines, so
# prose sitting there lands in every build's stdout — and this prose contains
# the word "overflows", which is exactly what scripts grep the build output
# for. That cost me a full five-profile false FAIL while writing this.
$(PRG): $(PRG_DEPS)
	@mkdir -p build
	@rm -f $@
	$(LD65) $(LD65FLAGS) -o $@ $(ALL_OBJS) $(SIBLING_LIB_ARCHIVES)
	# Rewrite ca65 label format `al XXXXXX .name` -> VICE format `al C:XXXX .name`
	# so the c64-test-harness Labels.from_file() reader can parse it.
	sed -i '' 's/^al 00\([0-9a-fA-F]\{4\}\) /al C:\1 /' $(LABELS)
ifeq ($(USE_NISTCURVES_ONCHIP),1)
	# Onchip-profile invariant: the sibling's sqtab_lo/hi equates are
	# BAKED to $$BC00/$$BE00 (LIB_SHARED_SQTAB_BASE in the wrapper).
	# src/data.s owns sqtab_lo/hi, but the sibling reads the table through
	# its OWN equates derived from that base, so the two must agree on the
	# address. Drift is neither a link nor a boot failure — just every
	# multiply reading the wrong memory.
	@grep -q '^al C:BC00 \.sqtab_lo' $(LABELS) || \
		{ echo 'ERROR: sqtab_lo is not at $$BC00 — TABLES_BSS layout drifted; realign LIB_SHARED_SQTAB_BASE in tools/integration/build_nistcurves_p256.sh'; \
		  grep ' \.sqtab_lo$$' $(LABELS); exit 1; }
endif
ifeq ($(USE_X25519_SIBLING),1)
	# Same invariant, other sibling: build_x25519.sh bakes sqtab_lo/hi
	# into the sibling at X25519_SQTAB_BASE while in-tree sqtab_init
	# fills the real table wherever ld65 put it. Disagreement is neither
	# a link nor a boot failure, just a wrong shared secret. Rationale
	# and the $$B800-vs-$$BC00 history: tools/integration/build_x25519.sh.
	@grep -q '^al C:B800 \.sqtab_lo' $(LABELS) || \
		{ echo 'ERROR: sqtab_lo is not at $$B800 — TABLES_BSS layout drifted; realign X25519_SQTAB_BASE in tools/integration/build_x25519.sh'; \
		  grep ' \.sqtab_lo$$' $(LABELS); exit 1; }
endif

# Phase 5 Fix D: $(LABELS) is normally a side-effect of the $(PRG)
# link recipe; we don't add an explicit rule.  The overlay-bin rule
# below has an order-only dep on $(LABELS) so its lookup_label()
# resolves the main PRG's runtime mul_dma_lo / mul_dma_hi /
# mul_cached_a / reu_fetch_mul_row to real addresses (was: silent
# $0000 fallback that produced a curve overlay whose fp_mul_384
# read/wrote $0000 and silently corrupted downstream state).
#
# Bootstrap workflow (clean tree under USE_OVERLAY_P384_EMBED=1):
#   make BACKEND=uci USE_OVERLAY_P384_EMBED=0    # produce labels.txt
#   make BACKEND=uci                              # real link with overlays
# After this two-step bootstrap, plain `make BACKEND=uci` rebuilds
# incrementally without intervention.  The script
# tools/integration/build_nistcurves_p384_bin.sh prints a clear error
# pointing at this two-step procedure if it runs without labels.txt
# (vs the old silent $0000 stub fallback).


link: $(PRG)

build/%.o: src/%.s
	@mkdir -p $(dir $@)
	$(CA65) $(CA65FLAGS) -o $@ $<

# src/net/ip65/ip65_blob.s pulls the prebuilt ip65 image in with a ca65
# `.incbin`, which make's dependency graph cannot see. Without this edge
# make is free to assemble ip65_blob.s before the $(IP65_BIN) rule has
# run, and from a clean build/ it does exactly that — failing with
# "Cannot open include file '../../../ip65-build/ip65-c64.bin'" even
# though the very same `make` invocation builds the blob a few targets
# later. That is the fresh-clone failure in issue #89. Stating the edge
# explicitly forces the correct order; it changes no output bytes.
# (Only meaningful under BACKEND=ip65 — the UCI build never assembles
# this object, and never requests $(IP65_BIN).)
build/net/ip65/ip65_blob.o: $(IP65_BIN)

# build/flags.stamp — the whole build-flag set, as a tracked dependency.
#
# make tracks source mtimes, not the command line, so `make BACKEND=uci` on a
# tree assembled as ip65 rebuilt nothing and linked whatever objects were
# lying around. `make clean` after any flag change WAS the documented remedy,
# and it was a rule that only had to be forgotten once: the result is not an
# error but a MIXED LINK, with exit status 0. (That is the world this block
# replaced. CLAUDE.md and README.md now document the stamp instead, and no
# longer tell you to `make clean` after a flag change.)
#
# Measured 2026-08-30, from a UCI onchip tree with no `make clean`. The
# hashes are that day's tree and the then-current default host; they are the
# shape of the evidence, not values to reproduce today:
#
#     make BACKEND=uci USE_NISTCURVES_ONCHIP=1 HTTPS_SNI=www.foo.invalid
#       -> d1b63508...   (mixed)
#     make clean; make <the same flags>
#       -> a65fff60...   (correct)
#
# HTTPS_SNI= feeds two consumers: the string travels in build/https_host.inc
# below (which invalidates boot.o), and a non-empty value also adds
# -D HTTPS_SNI_OVERRIDE=1, which src/http.s reads. Nothing invalidated
# http.o, so the image carried the SNI string and never ran the override —
# indistinguishable from not passing the flag. The PRG hash changed and the
# name grepped out of the image, so only a diff against a cleaned build could
# see it; it cost a full false negative on issue #141 (whose narrower fix,
# adding build/http.o to the https_host.inc rm below, this subsumes).
#
# The mechanism is the one issue #128 already proved out for the target
# strings, widened to the flag set: write the flags to a stamp file, content-
# compare it during Makefile EXPANSION, and on a change DELETE the objects
# and the PRG. Parse time, not a recipe, and absence, not a timestamp —
# both for the reasons spelled out in the https_host.inc block below, which
# is the load-bearing part of this design and is worth reading before
# touching either block.
#
# What is stamped is the fully expanded ca65 and ld65 command lines, not a
# hand-kept list of knob names: every flag that reaches the toolchain does so
# through CA65FLAGS or LD65FLAGS (which carries $(CFG), hence BACKEND and the
# onchip/comb cfg variants), so a new knob added at the top of this file is
# covered on the day it is written. The archive list and the two exported
# X25519 segment names are added because they steer build inputs without
# appearing on either command line.
#
# NOT stamped, deliberately: HTTPS_HOST / HTTPS_PATH / HTTPS_SNI's string
# values. They reach ca65 through build/https_host.inc, which invalidates
# boot.o + http.o instead of the whole tree — issue #128's no-`make clean`
# ergonomic, which certificate pinning (#155) is about to depend on. A
# non-empty HTTPS_SNI does change CA65FLAGS, so the presence of the override
# is stamped even though the name in it is not.
#
# Cost of a false positive here is one full rebuild (~0.4 s); cost of a false
# negative is the incident above. tools/test_build_flags_stamp.py pins both
# directions.
#
# One consequence worth knowing: CA65FLAGS carries two $(abspath ...)
# `.incbin` roots, so the stamp is absolute-path-bearing and moving a
# checkout forces one rebuild. That is the honest answer — a moved tree IS a
# different `.incbin` root, which is the bug issue #116 chased through agent
# worktrees — and it is why the file is not comparable between machines.
FLAGS_STAMP := build/flags.stamp

# Issue #174: -n / -q / -t must not mutate the tree.
#
# Both invalidation blocks below run inside a $(shell ...) during PARSE, which
# is the whole point (see the comments on each) — but it also means -n cannot
# suppress them. `-n` suppresses RECIPES; it does not suppress $(shell). So
# `make -n` with a flag set that differed from the stamp used to delete every
# object and the PRG, exit 0, and say nothing. One such probe destroyed a
# working tree on 2026-08-31, and `make -npq` is what shell tab-completion runs
# to enumerate targets.
#
# Finding the single-letter options is the whole difficulty, and the obvious
# answer is WRONG. `$(firstword $(MAKEFLAGS))` holds the letter bundle only
# when no long option is present; long options arrive as their own `--word`s
# and push the letters elsewhere. Measured on GNU Make 3.81 (macOS):
#
#     make                              ->  []
#     make -n                           ->  [n]
#     make -q                           ->  [q]
#     make -t                           ->  [t]
#     make --dry-run                    ->  [n]
#     make -npq                         ->  [qpn]
#     make -s -n                        ->  [sn]
#     make BACKEND=uci HTTPS_HOST=en.host.invalid  ->  []
#     make --no-print-directory         ->  [ --no-print-directory]
#     make --warn-undefined-variables   ->  [ --warn-undefined-variables]
#     make -n --no-print-directory      ->  [ --no-print-directory -n]
#     make --no-print-directory --warn-undefined-variables
#                                       ->  [ --warn-undefined-variables - --no-print-directory]
#
# Two things the last four rows kill. `--no-print-directory` contains an `n`
# AND a `t`; `--warn-undefined-variables` contains an `n` — so searching the
# first word calls a REAL build a dry run, skips the invalidation, and the
# link reuses the previous profile's objects. That is the mixed link this
# whole mechanism exists to prevent, produced by the guard meant to protect
# it, and it is worse than the bug in #174: same PRG size, different hash,
# exit 0. And the letters are not first, nor undashed, when a long option is
# present, so `$(filter-out -%,$(firstword ...))` is not a fix either — it
# re-opens #174 on `make -n --no-print-directory`. Both were measured, both
# directions.
#
# So: take every word that is neither `--`-prefixed nor a `VAR=value`
# assignment (make 4.x appends those after a `--`), and strip one leading
# dash. A stray bare `-` word, as in the last row above, patsubsts to the
# empty string and drops out. 52/52 correct across the option matrix in
# tools/test_build_flags_stamp.py's two guard tests.
#
# Testing for `n` alone is not enough — `make -q` is equally destructive and
# equally a dry run, and `-t` is the third.
MAKE_OPT_LETTERS := $(patsubst -%,%,$(filter-out --% %=%,$(MAKEFLAGS)))
MAKE_DRY_RUN := $(strip \
    $(findstring n,$(MAKE_OPT_LETTERS)) \
    $(findstring q,$(MAKE_OPT_LETTERS)) \
    $(findstring t,$(MAKE_OPT_LETTERS)))

# Under a dry run each block below still runs its COMPARE — it just reports
# instead of acting, so `make -n` stays an honest answer to "what would a build
# do?" rather than silently printing "nothing to be done". The dry-run compare
# writes nothing at all: the body goes down a pipe into `cmp -`, so not even
# build/ is created. A missing stamp (or a missing build/) reads as "differs",
# which is correct — a real build would invalidate there too.
#
# The one thing a guard must NOT do is weaken #159. Every non-dry-run
# invocation is byte-for-byte unchanged, so the invalidation stays
# unconditional and immediate for real builds, and CLAUDE.md's #128
# no-`make clean` exemption for HTTPS_HOST/HTTPS_PATH stands as documented.

# One line, so it can serve both the parse-time compare and the recovery rule
# below. Single-quoted: no value here may contain a single quote.
FLAGS_STAMP_BODY := printf '%s\n' \
    'c64-https build flags. Generated by the Makefile; do not edit.' \
    'A change to any line deletes every object and the PRG at parse time.' \
    'Target strings (HTTPS_HOST/HTTPS_PATH/HTTPS_SNI) live in the separate' \
    'build/https_host.inc stamp, which invalidates less. See the Makefile.' \
    'CA65=$(CA65)' \
    'LD65=$(LD65)' \
    'BACKEND=$(BACKEND)' \
    'CA65FLAGS=$(CA65FLAGS)' \
    'LD65FLAGS=$(LD65FLAGS)' \
    'SIBLING_LIB_ARCHIVES=$(SIBLING_LIB_ARCHIVES)' \
    'X25519_INIT_SEGMENT=$(X25519_INIT_SEGMENT)' \
    'X25519_SEG_LADDER=$(X25519_SEG_LADDER)'

ifneq ($(MAKECMDGOALS),clean)
ifeq ($(MAKE_DRY_RUN),)
_ := $(shell mkdir -p build; \
             $(FLAGS_STAMP_BODY) > $(FLAGS_STAMP).tmp; \
             if cmp -s $(FLAGS_STAMP).tmp $(FLAGS_STAMP); then \
                 rm -f $(FLAGS_STAMP).tmp; \
             else \
                 mv $(FLAGS_STAMP).tmp $(FLAGS_STAMP); \
                 rm -f $(ALL_OBJS) $(PRG); \
             fi)
else
# -n / -q / -t: compare and report, mutate nothing. See MAKE_DRY_RUN above.
ifneq ($(shell $(FLAGS_STAMP_BODY) 2>/dev/null | cmp -s - $(FLAGS_STAMP) >/dev/null 2>&1 || echo differs),)
$(warning DRY RUN (-$(MAKE_OPT_LETTERS)): build flags differ from $(FLAGS_STAMP).)
$(warning   A real build would rewrite the stamp and delete every object and $(PRG))
$(warning   at parse time. NOTHING was deleted; the tree is untouched.)
endif
endif

# Order-only: the deletion above is what actually invalidates, and it has
# already happened by the time make reads this edge. The edge states the
# relationship for anyone reading the graph, and keeps the stamp from being
# a file the graph does not know about. A NORMAL prerequisite would make
# every object depend on the stamp's mtime — a 1-second-resolution
# comparison, which is exactly what this design exists not to rely on.
$(ALL_OBJS): | $(FLAGS_STAMP)
endif

# Recovery rule for the order-only edge. Normally unreachable: the block
# above writes the stamp during parse, so by the time make looks the file is
# there (and if it had been deleted by hand, the compare above already
# treated that as a change and cleared the objects). It exists so the edge
# can never fail a build with "no rule to make target" — the failure mode
# `make clean all` still has for build/https_host.inc, which predates this
# and is left alone.
$(FLAGS_STAMP):
	@mkdir -p build
	@$(FLAGS_STAMP_BODY) > $@

# src/boot.s pulls the HTTPS target hostname from this generated include
# (see the HTTPS_HOST block near the top). The content compare leaves the
# file's mtime alone when the value is unchanged, so boot.o is NOT rebuilt
# in that case.
#
# The "LINK step keeps the repo-wide same-second caveat ... check the PRG
# hash when a build matters" note that used to stand here is RETIRED for
# this flag: that caveat was the #128 bug, not a fact of life, and the
# parse-time invalidation below closes it. It is retired for BACKEND= and
# the rest of the flag set too, since build/flags.stamp above gives them the
# same hook — but the two stamps invalidate at different grains on purpose,
# and only this one is cheap enough to fire on every retarget.
# Issue #128: the target strings are resolved at PARSE time, not in a recipe.
#
# This flag is documented as not needing `make clean`, so it has to be right
# without one — and two earlier shapes of this rule were not:
#
#   1. Delete boot.o only. macOS ships GNU Make 3.81, which compares mtimes at
#      1-second resolution, so a boot.o rebuilt in the same second as the
#      previous link is NOT newer than the PRG and the link is skipped. `make`
#      then `make HTTPS_HOST=<other>` back-to-back printed nothing, exited 0,
#      and left a PRG still carrying the OLD host. That is precisely "the
#      wikipedia build still connects to the default host".
#
#   2. Delete boot.o AND the PRG from inside the recipe. Worse: make stats its
#      targets before this recipe runs and caches the result, so it used the
#      cached "PRG exists, same second" view and skipped the link anyway —
#      leaving NO PRG at all, still exit 0. Verified both times.
#
# Doing the compare-and-invalidate during Makefile expansion runs it before
# make builds its file database, so the deletion is visible to the dependency
# graph. Absence is not a timestamp comparison, which is the whole point:
# nothing here can be defeated by two files sharing a second.
HTTPS_TARGET_INC_BODY := printf '.define HTTPS_HOST_STR "%s"\n.define HTTPS_PATH_STR "%s"\n.define HTTPS_SNI_STR "%s"\n' \
                    '$(HTTPS_HOST)' '$(HTTPS_PATH)' '$(HTTPS_SNI)'

ifneq ($(MAKECMDGOALS),clean)
ifeq ($(MAKE_DRY_RUN),)
_ := $(shell mkdir -p build; \
             $(HTTPS_TARGET_INC_BODY) > build/https_host.inc.tmp; \
             if cmp -s build/https_host.inc.tmp build/https_host.inc; then \
                 rm -f build/https_host.inc.tmp; \
             else \
                 mv build/https_host.inc.tmp build/https_host.inc; \
                 rm -f build/boot.o build/http.o $(PRG); \
             fi)
else
# -n / -q / -t: compare and report, mutate nothing. See MAKE_DRY_RUN above.
ifneq ($(shell $(HTTPS_TARGET_INC_BODY) 2>/dev/null | cmp -s - build/https_host.inc >/dev/null 2>&1 || echo differs),)
$(warning DRY RUN (-$(MAKE_OPT_LETTERS)): target strings differ from build/https_host.inc.)
$(warning   A real build would delete build/boot.o, build/http.o and $(PRG) at parse)
$(warning   time. NOTHING was deleted; the tree is untouched.)
endif
endif
endif

# build/http.o joins boot.o here (issue #141). src/http.s is the second
# consumer of an HTTPS_SNI= change: it carries the .ifdef
# HTTPS_SNI_OVERRIDE prologue that copies https_sni_override into
# tls_hostname. It does NOT .include the generated header — the string
# itself is boot.s's, and http.s only .imports the label — so this edge is
# insurance, not the fix: what closed the mixed link is build/flags.stamp
# above, which moves on the empty -> non-empty transition because that
# transition adds -D HTTPS_SNI_OVERRIDE=1 to CA65FLAGS. The edge is here so
# that the two objects that KNOW about the target strings invalidate as a
# pair, whichever of them grows a direct dependency next.
build/boot.o build/http.o: build/https_host.inc

# Phase C.3: c64-nist-curves sibling archive (libs/nistcurves/ submodule).
# Phase 1.5 split: produces TWO archives, one per overlay half. The
# script writes both with a single invocation; the second target is a
# pseudo-rule that piggybacks on the first.
build/lib/nistcurves-p384-sha384.a build/lib/nistcurves-p384-curve.a:
	@mkdir -p build/lib
	bash tools/integration/build_nistcurves_p384.sh

# Phase C.4: c64-nist-curves P-256 archive — replaces the in-tree ECDSA
# P-256 primitives (ecdsa_{curve,fp,mod,points}.s) with the sibling's
# variable-base scalar mul + packaged ecdsa_verify_256. Always-resident;
# linked into the PRG under BOTH backends. See the build script for the
# full stripped-symbol list and the dispatcher (src/crypto/ecdsa_verify.s)
# for the 160-byte BE struct packing that bridges TLS to the sibling.
build/lib/nistcurves-p256.a:
	@mkdir -p build/lib
	bash tools/integration/build_nistcurves_p256.sh reu

# Onchip turbo-profile variant (issue #69). Same wrapper, onchip mode:
# builds upstream lib-p256-verify-onchip and rebuilds mul_8x8_onchip.o
# with the SHARED_* consumer defines + LIB_SHARED_SQTAB_BASE=$BC00.
build/lib/nistcurves-p256-onchip.a:
	@mkdir -p build/lib
	bash tools/integration/build_nistcurves_p256.sh onchip

# Comb-accelerated onchip variant: full onchip archive trimmed to the
# P-256 comb verify set (comb ecdsa256 + points256_comb + Lim-Lee data).
build/lib/nistcurves-p256-onchip-comb.a:
	@mkdir -p build/lib
	bash tools/integration/build_nistcurves_p256.sh onchip-comb

# Phase C.5: c64-x25519 v0.4.0 X25519 archive — replaces the in-tree
# fe25519.s + x25519.s + X25519 buffer declarations in src/data.s when
# USE_X25519_SIBLING=1. Linked into the PRG under BOTH backends. The
# sibling's reu_mul_init is called from src/boot.s in place of the
# in-tree REU mul table generator; sqtab_init is still served by the
# in-tree src/crypto/poly1305.s (sibling's mul_8x8.s is excluded from
# the archive to avoid duplicate-symbol with poly1305's mul_8x8).
build/lib/x25519.a:
	@mkdir -p build/lib
	bash tools/integration/build_x25519.sh

# Phase C.3b / Phase 1.5 split: P-384 overlay IMAGES + labels for
# harness-time use only.  The production PRG does NOT link
# nistcurves-p384-{sha384,curve}.a — these are smoke-test infrastructure.
# A future Phase 3 / Phase 4a harness will load both .bins into REU at
# test time, then DMA them into the live slot via two new swap entry
# points (crypto_swap_to_p384_sha384 / crypto_swap_to_p384_curve);
# the existing crypto_swap_to_p384 entry point is now stale -- see the
# comment block at the top of src/crypto/shared/crypto_swap.s.
#
# All four outputs (two .bins + two labels files) are produced by a
# single script invocation; the rule lists all four targets so make
# only runs the script once even when several are stale.
#
# Phase 5 Fix D: build/labels.txt is an ORDER-ONLY dependency.  The
# overlay-bin script's lookup_label() reads build/labels.txt to resolve
# mul_dma_lo / mul_dma_hi / mul_cached_a / reu_fetch_mul_row to the
# main PRG's runtime addresses (so the curve overlay's fp_mul_384
# reads/writes the right $BA00 / $BB00 / etc. cells).  On a clean
# build, build/labels.txt doesn't exist yet when this rule runs and the
# script falls back to $0000 stubs - silently producing an overlay
# image whose fp_mul_384 reads from $0000.  Order-only ('|') ensures
# labels.txt exists before the script runs but doesn't trigger an
# overlay rebuild on every main-PRG link.
build/lib/overlay-p384-sha384.bin build/lib/overlay-p384-curve.bin build/labels-p384-sha384.txt build/labels-p384-curve.txt: \
		build/lib/nistcurves-p384-sha384.a build/lib/nistcurves-p384-curve.a \
		cfg/p384-overlay-sha384.cfg cfg/p384-overlay-curve.cfg \
		tools/integration/build_nistcurves_p384_bin.sh \
		| build/labels.txt
	bash tools/integration/build_nistcurves_p384_bin.sh

.PHONY: p384-overlay
p384-overlay: build/lib/overlay-p384-sha384.bin build/lib/overlay-p384-curve.bin \
              build/labels-p384-sha384.txt build/labels-p384-curve.txt

# W3: P-256 verify overlay .bin (library-ingestion architecture).
# Mirrors the P-384 overlay .bin rule: depends on the P-256 sibling
# archive (build/lib/nistcurves-p256.a, already a default PRG dep) +
# the standalone overlay cfg.  Order-only dep on build/labels.txt for
# the lookup_label() fallback (same pattern as P-384 — see Fix D
# comment block above).
build/lib/nistcurves-p256-verify.bin build/labels-p256-verify.txt: \
		build/lib/nistcurves-p256.a \
		cfg/p256-overlay-verify.cfg \
		tools/integration/build_nistcurves_p256_bin.sh \
		| build/labels.txt
	bash tools/integration/build_nistcurves_p256_bin.sh

.PHONY: p256-overlay
p256-overlay: build/lib/nistcurves-p256-verify.bin build/labels-p256-verify.txt

# Phase 5 Fix C: regenerate the P-384 overlay-resident symbol equates
# (build/p384_overlay_equates.inc) from the overlay labels files so the
# TLS-side dispatcher (src/crypto/ecdsa_verify_384.s) picks up address
# changes via .include, with .assert pins catching drift.  Whenever
# either labels file is rebuilt, the .inc regenerates and the
# dispatcher .o is forced to rebuild.
build/p384_overlay_equates.inc: build/labels-p384-sha384.txt build/labels-p384-curve.txt \
                                tools/integration/gen_p384_overlay_equates.sh
	bash tools/integration/gen_p384_overlay_equates.sh \
	    build/labels-p384-sha384.txt build/labels-p384-curve.txt $@

# The dispatcher .o now depends on the generated equates file (via
# .include) AND on the overlay .bin files (PRG_DEPS already lists those
# under USE_OVERLAY_P384_EMBED).  Phase 5 Fix D: gate the .inc dep on
# USE_OVERLAY_P384_EMBED so the bootstrap rule for $(LABELS) (which
# sub-makes with USE_OVERLAY_P384_EMBED=0) can skip rebuilding the .inc
# from labels-p384-* (those depend on overlay-bins which depend on
# $(LABELS) -- cycle).  The bootstrap pre-creates a placeholder .inc
# before sub-making.
ifeq ($(USE_OVERLAY_P384_EMBED),1)
build/crypto/ecdsa_verify_384.o: build/p384_overlay_equates.inc
endif

# Build ip65 object libraries from the submodule. Required once per fresh
# clone — the submodule ships sources, and the ip65-blob link below needs
# the .lib archives this target produces. Re-run when the submodule moves.
ip65-libs:
	cd $(IP65_DIR) && $(MAKE) -C ip65 && $(MAKE) -C drivers

# Build the ip65 binary blob (ip65-build/ip65-c64.bin). The file is a
# gitignored build artifact (.gitignore: ip65-build/*.bin), NOT committed.
# `all` depends on it under BACKEND=ip65, so a normal `make` builds it once
# 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
	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

run: $(PRG)
	$(VICE) -autostart $(PRG)

clean:
	rm -rf build

# Release packaging: build the three shipped PRG variants (PACKAGE_VARIANTS in
# tools/package/_common.sh, which is the matrix -- do not restate it here),
# put each on its own D64, generate the single-file test listener, and write
# dist/MANIFEST.txt.  There are deliberately NO per-backend combo disks: the
# three-product lineup does not fit on a 664-block .d64, so one would have had
# to silently omit a product (tools/package/build_d64.sh:98).
#
# The scripts run `make clean` between flag combinations themselves, so
# `package` deliberately depends on no build artifact — and re-running it after
# a submodule bump regenerates everything with no edits anywhere. Order
# matters: build_prgs.sh writes dist/build-info.txt and build_d64.sh writes
# dist/d64-listings.txt, both of which write_manifest.sh consumes.
#
# PACKAGE_PYTHON must be an interpreter that can run the listener's own
# selftest — see `make package-verify`.
#
# build_prgs.sh is three-valued: 0 = all variants built, 2 = PARTIAL, 1 = none.
# On PARTIAL the pipeline deliberately runs to completion anyway, so a single
# broken variant still yields disks, a listener and a manifest that names what
# is missing and why — then the target fails, because a partial matrix must
# never be mistaken for a release. `-` on the first line lets make continue;
# the status is recovered from the build-info records rather than from $?,
# which `-` discards.
PACKAGE_PYTHON ?= python3
package:
	-bash tools/package/build_prgs.sh
	@grep -q 'result=OK' dist/build-info.txt 2>/dev/null \
	    || { echo "[package] no variant built at all — nothing to package" >&2; exit 1; }
	bash tools/package/build_d64.sh
	$(PACKAGE_PYTHON) tools/package/build_listener.py
	bash tools/package/write_manifest.sh
	@if grep -q '^failreason=' dist/build-info.txt; then \
	    echo ""; \
	    echo "[package] ***** INCOMPLETE: the following variants did NOT build *****"; \
	    grep '^failreason=' dist/build-info.txt | cut -d= -f2- | sed 's/^/[package]   /'; \
	    echo "[package] dist/ holds the variants that DID build; see MANIFEST.txt."; \
	    echo "[package] Do not tag a release from this."; \
	    exit 1; \
	fi

# Acceptance gate for the release artifacts: rebuild every PRG a second time
# and compare PRG hashes, boot every D64 in VICE and assert the banner, and run
# the built listener end to end against a Python ssl client. Measures; does not
# assert. Run it after `make package`.
#
# The gate's own verdict logic is unit-tested first, and that ordering is the
# point: verify_release.py shipped with a bug where it reported RELEASE
# ARTIFACTS VERIFIED having checked nothing, so "the gate said yes" is only
# worth something if the gate's yes still means what it should. The tests need
# no VICE and no build; they cost milliseconds. A failure here stops the run
# rather than letting a broken verdict bless a release.
#
# tools/run_all_tests.py deliberately does not carry these: it allocates a VICE
# instance per suite and dispatches `run_tests(transport, labels, seed)`, a
# shape a pure-logic test does not fit. The gate is the right home for them.
package-verify:
	$(PACKAGE_PYTHON) tools/test_package_verify.py
	$(PACKAGE_PYTHON) tools/package/verify_release.py