CLAUDE.md

Guidance to Claude Code when working in this repository. The parent armfortas/CLAUDE.md governs the compiler and applies here too; this file adds linker-specific discipline on top.

Repository Context

afs-ld is a git submodule of ARMFORTAS, the bespoke ARM64 Fortran compiler. It is the standalone ARM64 Mach-O linker: reads MH_OBJECT from afs-as, static archives (.a), binary dylibs, and TAPI TBD text stubs; emits MH_EXECUTE and MH_DYLIB.

It knows nothing about Fortran. The boundary with the compiler is the CLI — an ld-compatible flag surface.

Rust standard library only. No clap, serde, byteorder, object, goblin, memmap2, yaml-rust. Hand-roll parsers, serializers, and the tiny YAML subset TBD files need. Adding a dependency requires a discussion, a CLAUDE.md update, and a justification.

Build, Test, Lint

cargo build -p afs-ld                          # build linker crate
cargo test  -p afs-ld                          # full suite
cargo clippy -p afs-ld --all-targets -- -D warnings

cargo test --lib -p afs-ld                     # unit tests only
cargo test --test <name> -p afs-ld             # one integration test file
cargo test --test parity_matrix                # vs Apple `ld` across the corpus (Sprint 27)
cargo test --test hello_world                  # executable end-to-end (Sprint 18)
cargo test --test hello_library                # dylib end-to-end (Sprint 18.5)
cargo test --test reader_corpus_round_trip     # afs-as corpus → byte-identity
cargo test --test archive_runtime              # libarmfortas_rt.a reality check
cargo test --test dylib_integration            # clang-built dylib → DylibFile
cargo test -p afs-ld -- <substring>            # filter by test name

Integration tests shell out to xcrun as, xcrun clang, ld, otool, nm, codesign. They require macOS on Apple Silicon and a working Xcode command-line toolchain. Do not stub or skip them — the differential against the system tools is the entire point of the suite. If xcrun is missing, tests emit skipping: ... and return cleanly. Never rewrite a test to always pass.

The --dump* CLI modes exist for manual inspection:

afs-ld --dump         input.o        # Mach-O header, load commands, sections, symbols, relocs
afs-ld --dump-archive libfoo.a       # flavor, members, symbol index
afs-ld --dump-dylib   libfoo.dylib   # install_name, dependencies, rpaths, export trie

Every time a new decoder lands, extend the relevant --dump* output.

Target

• Architecture: arm64 only. Not arm64e, not arm64_32. Not x86_64.
• OS: macOS. Mach-O file format, Apple AAPCS64 calling convention.
• Goal: parity with Apple ld for the binaries armfortas produces and the fortsh milestone. Not a toy. Not a subset. The full Mach-O/dyld contract for our use cases.

Design Philosophy

• Bespoke. We write every decoder, encoder, and layout pass. No object, no goblin, no mach-object. When something breaks, we read our code.
• Byte-level round-trip is the invariant. For every wire structure (header, load commands, sections, symbols, strings, relocations, archive members, export-trie nodes), parse(write(x)) == x and write(parse(bytes)) == bytes on every corpus fixture. If a structure can't round-trip, it's not done.
• Total control. ld has bugs we can't fix, behaviors we can't observe, and refactors we can't predict. Owning the linker closes the loop on every binary armfortas produces.
• No hidden state. Every transformation between raw wire form and linker-side form is explicit. Raw bits are preserved until the writer phase reshapes them; Raw { cmd, cmdsize, data } is a legitimate forever-variant for load commands we don't decode yet.

Architecture

Pipeline, end-to-end:

args → inputs → resolve → atomize → layout → apply relocs → synth sections → write → sign
 │        │        │         │        │            │              │            │       │
args.rs  input.rs resolve.rs atom.rs layout.rs  reloc/arm64.rs  synth/*.rs  macho/   synth/
                 symbol.rs                                                   writer    code_sig

Module responsibilities

• src/args.rs — CLI parser. Hand-rolled, streaming argv scan. No clap.
• src/macho/ — Mach-O 64 read/write.
  • constants.rs: LC_*, MH_*, S_*, N_*, ARM64_RELOC_*, EXPORT_SYMBOL_FLAGS_*, PLATFORM_*. Numeric literals mirroring Apple's <mach-o/loader.h> / <nlist.h> / <reloc.h> / <arm64/reloc.h>. Duplicated from afs-as rather than cross-crate coupled — each submodule owns its copy so they stay independent.
  • reader.rs: MachHeader64, LoadCommand enum, per-command structs (Segment64, Section64Header, SymtabCmd, DysymtabCmd, BuildVersionCmd, DylibCmd, RpathCmd, DyldInfoCmd, LinkEditDataCmd). Every variant has parse(cmdsize, payload) and write(&mut Vec<u8>) paired as round-trip.
  • dylib.rs: DylibFile::parse — pulls LC_ID_DYLIB, dependency chain, rpaths, and routes export-trie bytes through to exports.rs.
  • exports.rs: ExportTrie, ExportKind, cycle-safe walker with MAX_DEPTH=128.
  • writer.rs: emits MH_EXECUTE / MH_DYLIB (lands at Sprint 10+).
  • tbd.rs: TAPI TBD v4 YAML-subset parser (Sprint 6).
• src/archive.rs — BSD + SysV + GNU-thin static archives. Lazy member fetch via fetch_object_defining(name).
• src/input.rs — ObjectFile aggregate: header + load commands + sections + symbols + strings + dysymtab. Sprint 4 adds archive fetching; Sprint 7 introduces InputFile enum.
• src/symbol.rs — RawNlist (wire form, round-trip) + InputSymbol accessors (kind, ext, weak_ref/def, common size/alignment, library ordinal, indirect strx).
• src/string_table.rs — owned StringTable with suffix-dedup-aware strx → &str lookup.
• src/section.rs — SectionKind taxonomy (code / data / zerofill / TLS / literals / stubs / GOT / compact-unwind / eh_frame) derived from (segname, sectname, flags); InputSection with data + raw-reloc slices.
• src/reloc/ — ARM64 relocs.
  • mod.rs: RawRelocation (bit-packed), Reloc (fused; ADDEND / SUBTRACTOR prefixes folded into primaries), parse_relocs / write_relocs (reversible), validate_relocs (bounds, referent range, kind-vs-length-vs-pcrel).
  • arm64.rs: reloc application against final addresses (Sprint 11).
  • loh.rs: LOH preservation / relaxation (Sprint 25).
• src/leb.rs — ULEB128/SLEB128 codec reused by export trie, function-starts deltas, dyld opcode streams, chained fixups.
• src/diag.rs — diagnostics. Path + byte offset + caret, matching afs-as/src/diag*.rs style. Deterministic output: no wall clock, no pid, no thread-id in error text.
• src/dump.rs — --dump* inspection modes. Every time a reader decodes something new, extend the dump.
• src/driver.rs — orchestrator (Sprint 20).

Coding Conventions

• Rust, idiomatic. Use enums for wire structures and linker models. Exhaustive pattern matching everywhere — no catch-all _ arms outside tests. When a new LoadCommand variant lands, every match that inspects LoadCommand has to grow a new arm; the compiler enforces this and that's the point.
• unsafe only where genuinely required. The one known case is libc::mmap for large input files (Sprint 28). Keep blocks small, comment the invariant, and never let unsafe leak across module boundaries.
• Byte-level round-trip for every wire structure. Don't add a parser without its writer. Don't add a writer without a test that proves write(parse(x)) == x. See src/macho/reader.rs for the template.
• Raw wire form stays accessible. A Reloc kind that can't losslessly re-emit its ADDEND prefix is broken. A Name16 stored as String instead of [u8; 16] loses null padding and breaks byte-identity. Preserve the wire.
• Constants duplicated, not imported. afs-ld/src/macho/constants.rs mirrors Apple's headers numerically. Do not depend on afs-as at a type level. Submodule independence matters more than deduplication.
• Diagnostics cite input + offset + caret. Every parser error goes through ReadError / ArchiveError variants with explicit at_offset / context / reason. No String::from("something broke") noise.
• Commit discipline: terse imperative messages, no co-authors, per-file / per-chunk commits, never monoliths. No sprint-number references in commit subjects. Commit often — "if I had to bisect this sprint, which revision would I want to land on?" is the granularity.
• Tests alongside code. Every new decoder lands with unit tests in the same commit. Every bug fix gets a regression test. Integration tests that assemble/link real fixtures at test time always skip cleanly when xcrun is unavailable — never hard-fail on missing toolchain.
• No "stubs pass silently." Placeholder code that returns wrong answers is worse than code that panics. If a kind is "not yet implemented", say so with a hard error and a pointer to the sprint that'll finish it. Tests must catch the stub, not paper over it.
• Don't cut corners without stopping to discuss. If you find yourself about to skip a round-trip test, hardcode a "good enough" offset, or silently accept a malformed input, stop and talk it through. We are not building a toy linker.
• Avoid rushing through sprints to get to an audit. The hard work of each sprint is the point of the sprint. The audit is the downstream check, not the goal.
• Always opt for the robust solution. If you find yourself saying "the simple solution is X", stop and ask whether a production linker uses the simple solution or digs deeper. The simple one might be right — but we have to be sure this is not a toy.
• When unsure, consult .refs/. .refs/llvm/lld/MachO/ is the primary architectural reference; .refs/ld64/src/ is Apple's authoritative implementation for parity edge cases; .refs/mold/src/ informs performance choices. Read before inventing.
• Run long test jobs judiciously. Think about the grep/filter before you launch — cargo test -p afs-ld -- reader_ beats cargo test --workspace when you only touched the reader. The corpus round-trip is fast (~1s); the parity matrix (Sprint 27) won't be.

Test Architecture

Layered, not a single golden path. Each layer catches a different class of regression:

Corpus fixtures live in tests/corpus/. Every new relocation kind, section kind, or CLI flag lands a corpus entry in the same sprint.

Audit Discipline

After each sprint, a brutally honest audit:

• Assume nothing works until proven otherwise. Test every claim. Re-run the whole test suite, not just the freshly-written tests.
• "Placeholder" and "stub" are synonyms for "broken." Wrong answers silently produced are worse than crashes.
• Check against the Mach-O ABI spec, not just "does it link." Wrong output corrupts dyld's bind/rebase state at runtime; the kernel or loader will tell you, hours later, in ways that are hard to bisect.
• Don't soften findings. Major means "produces wrong binaries." Critical means "silent corruption that dyld will accept."
• No deferred items unless they genuinely require a later sprint. Fix it now if it can be fixed now. A deferred item accumulates debt with compound interest.
• The audit is not a formality. It is the last line of defense before bad linker output gets merged and ships bad binaries downstream.

Completeness Philosophy

Every Mach-O feature modern dyld consumes is in scope. When implementing a decoder or encoder:

• Implement it fully, not just the subset armfortas or fortsh happens to exercise. Every ARM64_RELOC_* kind, every EXPORT_SYMBOL_FLAGS_* terminal form, every LC_*_DYLIB variant.
• Don't defer features with "fortsh doesn't use this." Other Mach-O binaries do, and the parity gate (Sprint 27) will surface what we missed.
• The Mach-O spec + dyld source are the spec. ld behavior is a useful reference, not gospel. Where ld and the documented format disagree, match ld's actual output and document the deviation in the diff-tolerance allowlist.
• Don't modify tests that reveal real bugs to suit incorrect afs-ld behavior. Fix afs-ld.

Key Technical Decisions

• No LLVM, no ld64 fork. We own the stack. .refs/llvm/lld/MachO/ is architectural inspiration; we do not link against it.
• Both LC_DYLD_INFO_ONLY (classic) and LC_DYLD_CHAINED_FIXUPS (modern). Classic first (Sprint 15) so hello-world works on macOS 11+; chained immediately after (Sprint 15.5) so we match the Apple default on macOS 12+. Gate via -fixup_chains / -no_fixup_chains; default depends on -platform_version.
• Dylib output from day one. The writer is dylib-aware from Sprint 10; the hello-library milestone is Sprint 18.5, not Sprint 25 as originally scoped.
• Ad-hoc code signing is mandatory. macOS 11+ kills unsigned arm64 binaries at exec time. Sprint 22 ships our own SHA-256 code-signature emitter; we do not shell out to codesign.
• Owned bytes over borrowed slices, for now. InputSection::data, StringTable::raw, and their peers are Vec<u8>. Input buffers can drop after ObjectFile::parse returns. mmap + borrowed slices arrive in Sprint 28 if profiling justifies the complexity.
• Ordinals from load-command order. Two-level-namespace ordinals are 1-based positions in LC_*_DYLIB appearance order. Do not renumber on re-export or umbrella expansion.
• Per-test unique scratch dirs. Cargo runs integration tests in parallel within one process. Two tests writing to /tmp/afs-ld-corpus-{pid}/ race. Use an AtomicUsize counter per test or process-id + thread-id composite. See tests/reader_corpus_round_trip.rs::tempdir for the pattern.

Practical Gotchas

Lessons carved out of actually building the first few sprints:

• Never rm -rf a directory containing .docs/ without triple-verification. During Sprint 0 we had a near-miss extracting afs-ld into its own repo. Before any destructive operation that touches .docs/, keep a safety copy outside the operation scope, verify the snapshot has the expected file count, and only then proceed. The user has been burned; don't burn them again.
• Submodule work is three-step. Commit inside afs-ld → push origin/trunk → back in armfortas, git add afs-ld && git commit to bump the pin. Never stop after step one unless explicitly asked.
• Every new LoadCommand variant needs exhaustive-match updates in at least three places: cmd(), cmdsize(), and src/dump.rs::write_command. The compiler will tell you — listen.
• #[allow(dead_code)] is a short-lived bridge, not a marker. When a helper is unused because the caller lands in the next commit, #[allow(dead_code)] is acceptable with a comment naming the caller. Remove the allow as soon as the caller lands.
• Clippy's manual_is_multiple_of / identity_op / unusual_byte_groupings lints fire often on bit-field code. Use .is_multiple_of(8), avoid x | (0 << n), and use constants for unusual bit masks.
• Integration tests must skip cleanly on missing toolchain. If xcrun as / xcrun clang isn't available, eprintln!("skipping: …") and return. CI on a non-Mac runner must not fail.
• ASCII helpers for ar_hdr must accept empty → 0. Apple's ar writes all-space date/uid/gid/mode fields on anonymized archives; ascii_decimal returns Ok(0) for an all-whitespace slice.

Key References

• .refs/llvm/lld/MachO/ — primary architectural reference.
  • Driver.cpp — pipeline shape.
  • InputFiles.cpp — object/archive/dylib parsing.
  • SymbolTable.cpp — resolution and coalescing rules.
  • SyntheticSections.cpp — GOT/stubs/binding opcodes.
  • Arch/ARM64.cpp — reloc arithmetic.
  • Writer.cpp — layout and emission.
• .refs/ld64/src/ — Apple authoritative. src/ld/ + src/mach_o/.
• .refs/mold/src/ — performance techniques (mostly ELF; patterns apply).
• Apple <mach-o/loader.h>, <mach-o/nlist.h>, <mach-o/reloc.h>, <mach-o/arm64/reloc.h> — mirrored numerically in src/macho/constants.rs.
• dyld open source — bind/rebase/lazy-bind opcode semantics and chained-fixups format.
• ARM Architecture Reference Manual (ARMv8-A), section C4 — encoding of relocated instructions (ADRP, ADD, LDR, B/BL).

Sprint Roadmap

.docs/sprints/index.md — 32 sprints across 10 phases. Each has an individual markdown file with prerequisites, deliverables, testing strategy, and definition of done. Current completion is in each commit's parent-repo pin bump message.