gsym/convert/mod.rs
1//!
2//! [`ElfConverter`](crate::convert::ElfConverter) reads an ELF image, imports
3//! its `STT_FUNC` symbols and DWARF subprogram information, and returns a
4//! populated [`GsymBuilder`](crate::GsymBuilder) rather than finished bytes, so
5//! the model can be inspected or edited before an encoding is chosen.
6//!
7//! ```no_run
8//! use gsym::convert::ElfConverter;
9//!
10//! let report = ElfConverter::default().convert_path("./app")?;
11//! std::fs::write("./app.gsym", report.builder.to_bytes()?)?;
12//! # Ok::<(), gsym::Error>(())
13//! ```
14//!
15//! [`convert_path`](crate::convert::ElfConverter::convert_path) also searches
16//! for separate debug files: `.gnu_debuglink` targets validated by CRC,
17//! build-ID trees, debuginfod when it is configured, embedded
18//! `.gnu_debugdata`, supplementary `.gnu_debugaltlink` objects, and split
19//! DWARF. [`convert`](crate::convert::ElfConverter::convert) takes
20//! caller-supplied [`ElfInputs`](crate::convert::ElfInputs) instead and
21//! searches for nothing.
22//!
23//! Conversion is lenient. Anything unusable is skipped, counted in
24//! [`ConversionStats`](crate::convert::ConversionStats), and explained in a
25//! [`ConversionWarning`](crate::convert::ConversionWarning), so one bad
26//! compilation unit does not fail the whole file. Errors are reserved for input
27//! that cannot be used at all, such as a malformed image or a companion file
28//! belonging to a different build.
29//!
30//! See [`docs::conversion`](crate::docs::conversion) for the full guide.
31
32mod diagnostic;
33mod dwarf;
34mod elf;
35
36use object::{ObjectSection, SectionKind};
37
38pub use diagnostic::ConversionWarning;
39pub use elf::{
40 ConversionOptions, ConversionReport, ConversionStats, DiscoveryEvent, DiscoveryPolicy,
41 DwarfImportOptions, ElfConverter, ElfInputs,
42};
43
44fn is_debug_section(section: &object::Section<'_, '_>) -> bool {
45 section.kind() == SectionKind::Debug
46 || section
47 .name_bytes()
48 .is_ok_and(|name| name.starts_with(b".debug_") || name.starts_with(b".zdebug_"))
49}