gasm-sdk/docs/decisions.md

Deferred decisions

Design decisions deliberately postponed, with enough context to pick them up again without re-deriving the analysis. Each entry records what is deferred, why, the options on the table, and the trigger that should reopen it.

---

GOOBJ external (cross-package) symbol references

Status: resolved (v0.29.0+, 2026-08-07).

Approach taken. Instead of parsing the compiler's iexport data (which would have required either golang.org/x/tools or an in-house parser), the resolver reads the GOOBJ data directly from the target package's .a archive. The .a file contains a _go_.o member whose GOOBJ format is the same one gasm writes — the parser reuses the same layout (blkSymdef, blkNonpkgdef, the string table), so no new dependency was needed.

How it works.

1. go list -json -export <pkg> finds the target package's .a file.
2. extractGOOBJ reads the ar archive, finds the _go_.o member, skips the "go object …\n!\n" preamble and parses the GOOBJ header.
3. goobjFile.symbols() walks blkSymdef and blkNonpkgdef in definition order — the same order the linker uses — to build the symbol → index mapping.
4. resolveExternalSymbols wires the resolved {PkgIdx, SymIdx} into the GOOBJ emission.

The resolver is invoked automatically when img.Externals is non-empty; it runs go list as a subprocess (consistent with toolchainObjectPreamble which already calls go tool asm). All symbol data is cached per package for the lifetime of the GOOBJ emission.