rust-lang/rust

Codegen backends

Once MIR is final and monomorphization has produced a list of codegen units, a backend lowers them to machine code. rustc supports three backends in tree.

Backends in this repo

Backend	Crate	Status	Use case
LLVM	`rustc_codegen_llvm`	Default, production	Release builds, all major platforms
Cranelift	`rustc_codegen_cranelift`	Stable for debug builds	Faster compile, debug-mode codegen
GCC (libgccjit)	`rustc_codegen_gcc`	Experimental	Targets where LLVM is unavailable; alternate codegen

All three are loaded as dynamic libraries at compiler startup. The active backend is selected by -Zcodegen-backend=… (defaulting to llvm).

The rustc_codegen_cranelift and rustc_codegen_gcc crates are excluded from the main workspace (Cargo.toml) because they have their own dependencies and build configurations.

Shared layer: `rustc_codegen_ssa`

rustc_codegen_ssa is the backend-agnostic layer. It does:

Linking — driving the system linker (ld, lld, link.exe) with the right flags
Crate output management — handling rlibs, dylibs, staticlibs, executables, cdylibs
Debuginfo emission — DWARF/PDB metadata, source mapping
Target spec handling — using rustc_target to know about the platform
MIR-to-IR-style traversal — generic pseudo-code that backends fill in via traits

A backend implements traits like BuilderMethods, BackendTypes, LayoutTypeMethods from rustc_codegen_ssa::traits and gets to reuse the entire MIR-walking machinery for free.

graph TD
    Mono[(monomorphized MIR<br/>+ CGU plan)]
    Mono --> SSA[rustc_codegen_ssa]
    SSA -->|fill in via traits| LLVMBack[rustc_codegen_llvm]
    SSA -->|fill in via traits| CL[rustc_codegen_cranelift]
    SSA -->|fill in via traits| GCC[rustc_codegen_gcc]
    LLVMBack --> Linker
    CL --> Linker
    GCC --> Linker
    Linker --> Output[object<br/>lib<br/>executable]

LLVM backend

rustc_codegen_llvm is the production backend. Architecture:

rustc_llvm (compiler/rustc_llvm/) — raw FFI bindings to the in-tree LLVM at src/llvm-project/ (a submodule). Includes hand-written C++ glue when LLVM's C API is missing pieces.
rustc_codegen_llvm itself implements the SSA traits and translates MIR → LLVM IR via the FFI bindings.
LLVM is then asked to emit object code, which the linker step in rustc_codegen_ssa consumes.

The "in-tree LLVM" is updated periodically: a maintainer bumps the submodule pin and tests the resulting compiler against the full CI matrix. New target features and ISA support typically come from LLVM upstream.

For platforms where users want the system LLVM instead, bootstrap.toml's [llvm] section provides options (link static/dynamic, use system include paths, etc.).

Cranelift backend

rustc_codegen_cranelift targets the Cranelift code generator. Its strength is compile speed: Cranelift compiles much faster than LLVM, at the cost of less aggressive optimization. For debug builds, this can mean meaningful wall-clock improvements.

It has its own README/build instructions and isn't built by default; build with ./x build --stage 1 codegen-backends/cranelift after enabling it in bootstrap.toml.

GCC backend

rustc_codegen_gcc targets GCC's libgccjit library. Use cases:

Architectures GCC supports but LLVM doesn't (e.g., some embedded targets)
Bringing GCC-style optimizations to Rust for benchmarking and research
Bootstrapping Rust where only GCC is available

Linking

rustc_codegen_ssa::back::link is one of the largest files outside the type checker — linking on Linux, macOS, Windows, BSDs, embedded, and wasm targets requires a lot of platform-conditional code. Things it has to handle:

Static vs. dynamic linking
.rlib, .so/.dylib/.dll, .staticlib, .exe
Frameworks on macOS
link.exe vs. lld-link on Windows
wasm-ld for wasm targets
Cross-compile linker selection
Dead-code stripping (/OPT:REF, --gc-sections)
Debug-info copying (objcopy, dsymutil)

Metadata and crate types

rustc_metadata reads/writes .rmeta files (HIR + types) for dependency crates. Encoded format details live in rustc_metadata::rmeta. The encoder uses rustc_serialize for the binary format.

Crate types affect what gets emitted:

rlib — Rust's native library format (.rlib); contains compiled objects + metadata
dylib — Shared library exporting Rust ABI
cdylib — Shared library exporting C ABI (no Rust metadata)
staticlib — Static library exporting C ABI
bin — Executable
lib — Same as rlib (default)
proc-macro — Procedural macro shared library

Symbol mangling

rustc_symbol_mangling implements two mangling schemes:

Legacy mangling — historic; still default
v0 mangling — designed by RFC 2603 to be reversible and stable; opt-in via -Csymbol-mangling-version=v0

Mangled symbols encode the DefId path plus type substitutions; the demangler in rustc-demangle reverses both schemes.

Sanitizers

rustc_sanitizers wires up runtime sanitizers (ASan, MSan, TSan, LSan, KASAN, KMSAN, KCFI, ShadowCallStack, …) to LLVM's instrumentation passes. Selected via -Zsanitizer=…. Sanitizers are only available on tier 1 / tier 2 platforms.

Target specs

rustc_target holds:

The list of built-in targets (spec/targets/...)
The Target struct describing pointer width, default linker, ABI, available features
Target-feature parsing

rustc_abi holds the type-layout parts of the target spec — Layout, LayoutS, Abi, calling convention info — separate so they can be reused by tools like Miri without pulling in the full target list.

Custom targets are JSON files that match the Target schema; rustc parses them with --target=path/to/target.json.

Entry points for modification

New backend feature in LLVM → rustc_codegen_llvm
New ABI/layout → rustc_abi + rustc_target + the relevant codegen backend
New target → add a Target definition under compiler/rustc_target/src/spec/targets/
Linker behavior → rustc_codegen_ssa::back::link
Sanitizer support → rustc_sanitizers
Symbol mangling change → rustc_symbol_mangling (and a corresponding rustc-demangle PR)