Linkers

Active contributors: andrewrk, jakub-konka, jacobly, lemonboy

Purpose

src/link/ contains an in-tree linker for every output format the compiler natively supports. A linker here is more than a ld-style tool: each one knows how to merge per-decl artifacts emitted by codegen, resolve relocations, lay out sections, and write the final binary in a single pass. When the LLVM backend is selected, linking can also be delegated to LLD via src/link/Lld.zig.

Linkers in the tree

Format	File / directory	Notes
ELF (Linux/BSD/etc.)	src/link/Elf.zig (~159 KB), src/link/Elf/	The current production ELF linker. Subdirectory holds atom, archive, object, and synthetic-section modules.
ELF (rewrite)	src/link/Elf2.zig (~158 KB)	An in-progress alternative ELF linker living side-by-side with Elf.zig.
Mach-O (macOS / iOS)	src/link/MachO.zig (~196 KB), src/link/MachO/	Native Mach-O linker including code signing, dyld info, dylib handling.
COFF/PE (Windows)	src/link/Coff.zig (~94 KB)	Windows linker.
WebAssembly	src/link/Wasm.zig (~167 KB), src/link/Wasm/	Wasm module/object linker.
SPIR-V	src/link/SpirV.zig, src/link/SpirV/	SPIR-V module emission.
C (passthrough)	src/link/C.zig (~30 KB)	"Linker" that concatenates C output for the C backend.
LLD fallback	src/link/Lld.zig (~67 KB)	Drives LLD as an external process for the LLVM path.
DWARF	src/link/Dwarf.zig (~274 KB)	Debug info emission shared by the native linkers.
TAPI	src/link/tapi/, src/link/tapi.zig	Apple .tbd text API stubs.
Helpers	src/link/MappedFile.zig, src/link/Queue.zig, src/link/StringTable.zig, src/link/aarch64.zig, src/link/riscv.zig, src/link/table_section.zig, src/link/LdScript.zig	Cross-format utilities.

Anatomy of link/Elf/

The ELF directory is the cleanest example of how a self-hosted linker is decomposed:

src/link/Elf/
├── Archive.zig           # `.a` archive parsing
├── Atom.zig              # the per-symbol Atom abstraction
├── AtomList.zig          # ordered list of atoms
├── LinkerDefined.zig     # synthesized linker symbols
├── Merge.zig             # SHF_MERGE handling
├── Object.zig            # ELF object reader/writer
├── SharedObject.zig      # `.so` reader
├── Symbol.zig            # symbol table entries
├── Thunk.zig             # PLT/range-extension thunks
├── ZigObject.zig         # the in-memory "Zig" object emitted by codegen
├── eh_frame.zig          # `.eh_frame` rewriting
├── file.zig              # generic file-handle helper
├── gc.zig                # `--gc-sections`
├── relocatable.zig       # `-r` (linker-relocatable) mode
├── relocation.zig        # relocation handling
└── synthetic_sections.zig # `.dynsym`, `.dynstr`, `.hash`, etc.

MachO/ follows the same shape, with extra modules for code signing (CodeSignature.zig), unwind info (UnwindInfo.zig), and dyld metadata (dyld_info/).

Dispatch

graph LR
  Comp["src/Compilation.zig"] --> Link["src/link.zig"]
  Link -->|target=ELF| ELF["link/Elf.zig"]
  Link -->|target=MachO| MO["link/MachO.zig"]
  Link -->|target=COFF| CO["link/Coff.zig"]
  Link -->|target=Wasm| WASM["link/Wasm.zig"]
  Link -->|target=SPIRV| SP["link/SpirV.zig"]
  Link -->|backend=C| C["link/C.zig"]
  Link -->|use_lld| LLD["link/Lld.zig"]
  ELF --> Out["binary"]
  MO --> Out
  CO --> Out
  WASM --> Out
  SP --> Out
  C --> Out
  LLD --> Out

src/link.zig (~93 KB) defines the abstract link.File interface and dispatches per output_mode + object_format.

Tests

test/link/ carries integration tests for the in-tree linkers:

• test/link/elf/, test/link/macho/, test/link/coff/, test/link/wasm/.
• build.zig registers them as test-link; the package alias for the suite is declared in build.zig.zon (link_test_cases).

Key source files

File	Purpose
src/link.zig	Linker dispatch / link.File interface.
src/link/Elf.zig	ELF linker.
src/link/Elf2.zig	ELF rewrite (in progress).
src/link/MachO.zig	Mach-O linker.
src/link/Coff.zig	COFF/PE linker.
src/link/Wasm.zig	Wasm linker.
src/link/SpirV.zig	SPIR-V emission.
src/link/C.zig	C output passthrough.
src/link/Lld.zig	LLD invocation.
src/link/Dwarf.zig	DWARF debug info.
src/link/MappedFile.zig, src/link/Queue.zig, src/link/StringTable.zig, src/link/LdScript.zig	Shared helpers.

See Code generation backends for what produces the per-decl artifacts these linkers consume.