lld

lld/ is the LLVM linker — a from-scratch implementation of a cross-platform link editor. It reads object files and libraries, resolves symbols, applies relocations, performs LTO, and writes an executable, shared library, or object file. It is significantly faster than GNU ld and gold on the workloads it targets.

Purpose

LLD provides a single linker that ports cleanly across operating systems and object file formats. It exists primarily to make LLVM toolchains self-hosting (no external linker required), to deliver substantially faster link times on large C++ codebases, and to serve as a clean reference implementation of modern linker semantics for ELF, COFF, Mach-O, and WebAssembly.

Directory layout

lld/
├── ELF/             # ELF port — Linux, BSD, Solaris, embedded
├── COFF/            # COFF port — Windows
├── MachO/           # Mach-O port — macOS, iOS, watchOS, tvOS
├── wasm/            # WebAssembly port
├── MinGW/           # Tiny shim that drives the COFF port for MinGW toolchains
├── Common/          # Shared support code
├── include/lld/     # Public headers
├── tools/lld/       # The lld driver executable
├── test/            # lit regression tests
├── unittests/
├── docs/
└── README.md

Each port is independently buildable and largely independent in implementation. They share only the small Common/ library.

How drivers are selected

The lld executable looks at argv[0] to pick its port:

Driver name	Port
ld.lld	ELF
lld-link	COFF
ld64.lld	Mach-O
wasm-ld	WebAssembly
lld (no platform hint)	dispatches by -flavor= flag

CMake installs symlinks for each driver name pointing at the same binary. Toolchain integration is then a matter of telling the compiler driver to invoke the appropriate name (e.g., -fuse-ld=lld).

Key abstractions

Type	File	Role
lld::elf::Driver	lld/ELF/Driver.h	ELF link orchestrator
lld::coff::LinkerDriver	lld/COFF/Driver.h	COFF link orchestrator
lld::macho::Driver	lld/MachO/Driver.h	Mach-O link orchestrator
lld::wasm::LinkerDriver	lld/wasm/Driver.cpp	WebAssembly link orchestrator
Symbol / InputSection / OutputSection	per-port headers	Symbol table and section graph

How it works

graph LR
    in[Object files,<br/>archives, shared libs] --> read[Reader]
    read --> sym[Symbol resolution]
    sym --> lto[ThinLTO / LTO?]
    lto -->|optional| codegen[LLVM codegen]
    codegen --> sym
    sym --> sect[Section layout]
    sect --> reloc[Relocation application]
    reloc --> write[Writer]
    write --> out[Output binary]

A typical link:

1. Parse the command line. Map flags to a Configuration struct.
2. Read all object files, archives, and (where applicable) shared libraries. Build the global symbol table.
3. Resolve undefined references; pull in archive members as needed; remember which sections are live.
4. If LTO bitcode files were present, run an LLVM-internal compile pipeline to produce real object code, then re-resolve.
5. Lay out sections into segments (or PE sections, or Mach-O segments).
6. Apply relocations.
7. Write the output, generate any auxiliary files (e.g., .so.debug).

ThinLTO and DTLTO

LLD is the linker that drives LLVM's ThinLTO. When the linker sees bitcode object files, it runs the codegen for them across all available CPU cores and integrates the resulting machine code into the link. Distributed ThinLTO (DTLTO) extends this across a build farm; LLD's role is to orchestrate the bitcode handoff.

Integration points

• Compiler drivers (clang, gcc-with--fuse-ld=lld) invoke LLD via the ld.lld / lld-link / ld64.lld / wasm-ld names.
• LLVM core (llvm) provides the LTO codegen path that LLD invokes.
• Object-format support (llvm/lib/Object, llvm/lib/BinaryFormat) is reused for parsing input files.

Entry points for modification

• Adding an ELF flag or behavior: ELF driver lives in lld/ELF/Driver.cpp; flag definitions in lld/ELF/Options.td.
• Implementing a relocation: per-arch relocation handling under lld/ELF/Arch/. Each architecture (X86_64, AArch64, RISCV, ARM, PowerPC, Mips, etc.) has its own *.cpp.
• Mach-O changes: the most actively evolving port at the time of this snapshot. Driver entry in lld/MachO/Driver.cpp, section/atom layout in lld/MachO/SyntheticSections.cpp.
• Wasm changes: lld/wasm/ — the smallest of the four ports.

Reference

• LLD documentation
• LLD ELF flags