xold/lib.rs
1//! xold: a maintainable, multi-threaded linker for ELF, Mach-O and COFF.
2//!
3//! The crate is organised around three observations from studying lld and mold:
4//!
5//! - Each binary format lives behind its own reader/writer module (`elf`,
6//! `macho`, `coff`) and produces a common view of sections, symbols and
7//! relocations consumed by the format-neutral core.
8//! - Per-architecture relocation handling is driven by a declarative table
9//! keyed on a shared [`RelExpr`] semantic enum, so the scan and apply phases
10//! are written once instead of copy-pasted per architecture.
11//! - All on-disk structures are read zero-copy from a memory-mapped file via
12//! `bytemuck`, with no `unsafe` in the parsing layer.
13//!
14//! # Deterministic output (hard requirement)
15//!
16//! The linked image is a pure function of the inputs. The same object files
17//! and the same command line produce the same bytes, on every run, on any
18//! machine, at any thread count. Treat this as a correctness property with the
19//! same standing as producing a runnable binary at all, because a build system
20//! that caches or compares link outputs depends on it.
21//!
22//! Most of the linker runs in parallel, so the rule has teeth:
23//!
24//! - **Nothing scheduling-dependent may reach the output.** A concurrent or
25//! sharded structure may decide *identity* -- which name is which symbol,
26//! whether two strings are equal -- but never *order*. Every ordering that
27//! reaches the image (symbol table order, member placement, GOT and PLT slot
28//! assignment, merged string layout) derives from input order (file index,
29//! then index within that file) or from content.
30//! - **Iteration order of a hash container is not an ordering.** It is stable
31//! for one insertion sequence and nothing more. Walk a dense index or an
32//! explicitly sorted list.
33//! - **Verify it rather than assuming it.** Link the same inputs at
34//! `RAYON_NUM_THREADS` of 1, 2, 4, 8 and 16 and compare hashes; a change
35//! exercised only at the default thread count has not been tested.
36//!
37//! Two places show what this costs and why it is worth it.
38//! [`symbol::SymbolTable`] assigns ids in first-seen input order, which is
39//! inherently serial, so the parallel fold in `symbol::bulk` reproduces that
40//! order rather than abandoning it. [`merge`] deduplicates through a hash map
41//! but emits pieces in first-seen order, never map order.
42//!
43//! The practical consequence for changes: a refactor or an optimisation must
44//! produce byte-identical output to the commit before it. That is a far
45//! stricter regression test than the suite, and it catches ordering mistakes
46//! the suite cannot. A change that is *meant* to alter the output should say
47//! so in its commit message and explain why the new bytes are correct.
48//!
49//! # Running under Miri
50//!
51//! `cargo +nightly miri test` interprets the readers, the relocation
52//! arithmetic and the plan builders, which is where a zero-copy parser would
53//! hide undefined behaviour. `.cargo/config.toml` carries the two flags the
54//! run needs and says why each is there.
55//!
56//! Miri neither spawns processes nor maps files, so the end-to-end tests --
57//! which compile with the host toolchain and link through a mapping -- are
58//! marked `ignore` under it and the harness reports them as such. What is left
59//! is every test that builds its input in memory.
60//!
61//! Those in-memory fixtures must be aligned. A `Vec<u8>` or a `[u8; N]` asks
62//! for alignment 1 and gets more only because a real allocator rounds up;
63//! Miri grants exactly what was asked, so a fixture handed straight to a
64//! reader is refused there and accepted everywhere else.
65//! [`input::AlignedBytes`] is the storage that makes the request explicit, and
66//! is what the tests use.
67
68#![warn(clippy::pedantic, clippy::nursery)]
69#![allow(
70 // Namespaced module prefixes on public items are clearer than the stripped
71 // form clippy suggests for a library surface.
72 clippy::module_name_repetitions,
73 // Doc strings are kept short; mandatory docs on every item is noise here.
74 clippy::missing_errors_doc,
75 clippy::missing_panics_doc,
76 clippy::missing_const_for_fn,
77 // The linker has many pure accessors; annotating each is noise without
78 // much safety gain in this codebase.
79 clippy::must_use_candidate
80)]
81
82pub mod archive;
83pub mod buildid;
84pub mod coff;
85pub mod comdat;
86pub mod debug;
87pub mod defsym;
88pub mod detach;
89pub mod dynamic;
90pub mod ehframe;
91pub mod elf;
92pub mod endian;
93pub mod error;
94pub mod gc;
95pub mod icf;
96pub mod input;
97pub mod layout;
98pub mod linker;
99#[cfg(feature = "lto")]
100pub mod lto;
101pub mod macho;
102pub mod merge;
103pub mod mmap_file;
104pub mod output;
105pub mod plt;
106pub mod pool;
107pub mod reloc;
108pub mod script;
109pub mod search;
110pub mod startlib;
111pub mod startstop;
112pub mod symbol;
113pub mod tls;
114pub mod util;
115pub mod versionscript;
116pub mod writer;
117
118pub use error::{Error, Result};