rucc_object/
lib.rs

1//! ELF, Mach-O and COFF object writers.
2//!
3//! Design: `spec/11-asm-objects-debug.md`. Layer rank 9, see `spec/18-package-layout.md`.
4//!
5//! # Status
6//!
7//! ELF, which is what Linux and the freestanding targets want and what M3 needs. A text section,
8//! the symbols that say where each function in it is and how long it is, the names it wanted that
9//! are not in it, the relocations that ask a linker to find them, and the marker whose absence
10//! makes the stack executable. An object this writes links with the system linker and runs.
11//!
12//! The variables a file defines are written too: the section each one goes in, the symbol that
13//! says where it is and how long it is, the binding that says who can see it, and the relocations
14//! an image asks for when it holds the address of something. A tentative definition is asked of
15//! the linker rather than put in a section, which is the one case where a variable has a symbol
16//! and no bytes anywhere.
17//!
18//! An [`Alias`] is written as a second symbol at the first one's section, value and size, with a
19//! binding of its own and no second copy of the bytes, which is what a file gets from
20//! `__attribute__((alias("target")))` and what makes one name reach another at no cost.
21//!
22//! [`Sections`] says whether each function and each variable gets a section to itself, which is
23//! what `-ffunction-sections` and `-fdata-sections` ask for and what makes `--gc-sections` able to
24//! drop anything: a linker can leave out a section nothing reaches and cannot leave out half of
25//! one. The names and the offsets are the same either way, so the only thing that moves is which
26//! section header a symbol points at.
27//!
28//! [`Property`] is what the file says it was built to have checked, which is what
29//! `-fcf-protection=` asks for. It is written as a note the linker keeps only the agreed part of
30//! and the loader reads out of the result, which is why a file that says nothing about it turns
31//! the check off for the whole program rather than only for itself.
32//!
33//! [`defines`] says which names a linker can find in what [`write`] wrote, which is what the symbol
34//! index of an archive is built from. It is here rather than worked out by whoever writes the
35//! archive because the index has to agree with the member, and the writer is the only thing that
36//! knows what it put in one.
37//!
38//! What it is given is [`Text`], [`Data`] and the aliases between them, which are here rather than
39//! beside the assembler that fills them in because they are what an object file is made of and
40//! because a writer cannot depend on the thing that produces its input without the layer graph
41//! going the wrong way round.
42//!
43//! Mach-O and COFF are not written yet. Both wait on the target that needs them.
44//!
45//! Every crate in the workspace is published, and publishing implies a promise. This one is
46//! tier 3: its Rust API is explicitly unstable and will change without a major version bump.
47//! Depend on the `rucc` binary's behaviour, not on this.
48
49#![doc(html_root_url = "https://docs.rs/rucc-object/0.10.26")]
50
51mod elf;
52mod section;
53
54pub use crate::elf::{Error, defines, write};
55pub use crate::section::{
56    Alias, Binding, Data, Extent, FUNC_ALIGN, Object, Output, Patch, Place, Property, Reference,
57    Reloc, Sections, Text, Unwind, Visibility,
58};
59
60/// The milestone in `spec/17-milestones.md` that fills this crate in.
61pub const MILESTONE: &str = "M3";
62
63#[cfg(test)]
64mod tests {
65    #[test]
66    fn milestone_is_recorded() {
67        assert!(super::MILESTONE.starts_with('M'));
68    }
69}
rucc_object/lib.rs

rucc_object/
lib.rs
