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