rucc_debug/
lib.rs

1//! DWARF 5 generation.
2//!
3//! Design: `spec/11-asm-objects-debug.md`. Layer rank 10, see `spec/18-package-layout.md`.
4//!
5//! # Status
6//!
7//! The line table and nothing else. [`write()`] takes one unit's worth of addresses and the places
8//! in the source they came from and gives back the sections that say so, which is enough for
9//! `addr2line` to answer a program counter with a file and a line and not enough for a debugger to
10//! print a variable. The rest of M8 is tamnd/rucc#9.
11//!
12//! The reason that part came first is tamnd/rucc#1558. A report from the safety monitor carries a
13//! program counter and deliberately carries no source location, because
14//! `spec/safe-memory/06-instrumentation.md` section 6.5 would rather have one line table than two
15//! that can disagree, and that only works once there is one. Until there was, every report out of a
16//! corpus run had to be read backwards out of a disassembly.
17//!
18//! Every crate in the workspace is published, and publishing implies a promise. This one is
19//! tier 3: its Rust API is explicitly unstable and will change without a major version bump.
20//! Depend on the `rucc` binary's behaviour, not on this.
21//!
22//! # Two things still waiting
23//!
24//! `Options::prefix_map` in `rucc-session` holds a `debug` list, which is what
25//! `-fdebug-prefix-map=` and `-ffile-prefix-map=` put there. Every path that reaches [`Unit`] has
26//! already been through `PrefixMap::apply`, because that is the whole reason a distribution passes
27//! those flags and because a build is only reproducible if all of the paths in it are rewritten
28//! rather than most. The rewriting is the driver's rather than this crate's for one reason: the
29//! driver is where a path is still a path, and by the time one arrives here it is a string in a
30//! table that nothing is allowed to reinterpret.
31//!
32//! `Options::compress` is the other, and it is what `-gz` put there. Every debug section this
33//! crate hands to the object writer has to be compressed the way that field says, which for
34//! `Compress::ZlibGnu` also means the section is named `.zdebug_info` rather than `.debug_info`
35//! and carries a `ZLIB` tag and a length instead of an `Elf64_Chdr`. Compressing the sections is
36//! worth more than anything else a distribution shipping debug symbols passes, so a build that
37//! asked for it and got a file twice the size it expected has a real complaint. Nothing reads it
38//! yet, and on a line table alone the saving is smaller than it will be.
39
40#![doc(html_root_url = "https://docs.rs/rucc-debug/0.10.74")]
41
42mod line;
43
44pub use crate::line::{Error, Function, Row, Unit, write};
45
46/// The milestone in `spec/17-milestones.md` that fills this crate in.
47pub const MILESTONE: &str = "M8";
48
49#[cfg(test)]
50mod tests {
51    #[test]
52    fn milestone_is_recorded() {
53        assert!(super::MILESTONE.starts_with('M'));
54    }
55}
rucc_debug/lib.rs

rucc_debug/
lib.rs
