Module gimli::write[−][src]

Write DWARF debugging information.

API Structure

This module works by building up a representation of the debugging information in memory, and then writing it all at once. It supports two major use cases:

Use the DwarfUnit type when writing DWARF for a single compilation unit.
Use the Dwarf type when writing DWARF for multiple compilation units.

The module also supports reading in DWARF debugging information and writing it out again, possibly after modifying it. Create a read::Dwarf instance, and then use Dwarf::from to convert it to a writable instance.

Example Usage

Write a compilation unit containing only the top level DIE.

use gimli::write::{
    Address, AttributeValue, DwarfUnit, EndianVec, Error, Range, RangeList, Sections,
};

fn example() -> Result<(), Error> {
    // Choose the encoding parameters.
    let encoding = gimli::Encoding {
        format: gimli::Format::Dwarf32,
        version: 5,
        address_size: 8,
    };
    // Create a container for a single compilation unit.
    let mut dwarf = DwarfUnit::new(encoding);
    // Set a range attribute on the root DIE.
    let range_list = RangeList(vec![Range::StartLength {
        begin: Address::Constant(0x100),
        length: 42,
    }]);
    let range_list_id = dwarf.unit.ranges.add(range_list);
    let root = dwarf.unit.root();
    dwarf.unit.get_mut(root).set(
        gimli::DW_AT_ranges,
        AttributeValue::RangeListRef(range_list_id),
    );
    // Create a `Vec` for each DWARF section.
    let mut sections = Sections::new(EndianVec::new(gimli::LittleEndian));
    // Finally, write the DWARF data to the sections.
    dwarf.write(&mut sections)?;
    sections.for_each(|id, data| {
        // Here you can add the data to the output object file.
        Ok(())
    })
}

Structs

Attribute	An attribute in a `DebuggingInformationEntry`, consisting of a name and associated value.
CieId	An identifier for a CIE in a `FrameTable`.
CommonInformationEntry	A common information entry. This contains information that is shared between FDEs.
DebugAbbrev	A writable `.debug_abbrev` section.
DebugFrame	A writable `.debug_frame` section.
DebugInfo	A writable `.debug_info` section.
DebugInfoOffsets	The section offsets of all elements within a `.debug_info` section.
DebugLine	A writable `.debug_line` section.
DebugLineStr	A writable `.debug_line_str` section.
DebugLineStrOffsets	The section offsets of all strings within a `.debug_line_str` section.
DebugLoc	A writable `.debug_loc` section.
DebugLocLists	A writable `.debug_loclists` section.
DebugRanges	A writable `.debug_ranges` section.
DebugRngLists	A writable `.debug_rnglists` section.
DebugStr	A writable `.debug_str` section.
DebugStrOffsets	The section offsets of all strings within a `.debug_str` section.
DebuggingInformationEntry	A Debugging Information Entry (DIE).
DirectoryId	An identifier for a directory in a `LineProgram`.
Dwarf	Writable DWARF information for more than one unit.
DwarfUnit	Writable DWARF information for a single unit.
EhFrame	A writable `.eh_frame` section.
EndianVec	A `Vec<u8>` with endianity metadata.
Expression	The bytecode for a DWARF expression or location description.
FileId	An identifier for a file in a `LineProgram`.
FileInfo	Extra information for file in a `LineProgram`.
FrameDescriptionEntry	A frame description entry. There should be one FDE per function.
FrameTable	A table of frame description entries.
InitialLengthOffset	The offset at which an initial length should be written.
LineProgram	A line number program.
LineRow	A row in the line number table that corresponds to a machine instruction.
LineStringId	An identifier for a string in a `LineStringTable`.
LineStringTable	A table of strings that will be stored in a `.debug_line_str` section.
LocationList	A locations list that will be stored in a `.debug_loc` or `.debug_loclists` section.
LocationListId	An identifier for a location list in a `LocationListTable`.
LocationListOffsets	The section offsets of a series of location lists within the `.debug_loc` or `.debug_loclists` sections.
LocationListTable	A table of location lists that will be stored in a `.debug_loc` or `.debug_loclists` section.
RangeList	A range list that will be stored in a `.debug_ranges` or `.debug_rnglists` section.
RangeListId	An identifier for a range list in a `RangeListTable`.
RangeListOffsets	The section offsets of a series of range lists within the `.debug_ranges` or `.debug_rnglists` sections.
RangeListTable	A table of range lists that will be stored in a `.debug_ranges` or `.debug_rnglists` section.
Sections	All of the writable DWARF sections.
StringId	An identifier for a string in a `StringTable`.
StringTable	A table of strings that will be stored in a `.debug_str` section.
Unit	A unit’s debugging information.
UnitEntryId	An identifier for an entry in a `Unit`.
UnitId	An identifier for a unit in a `UnitTable`.
UnitTable	A table of units that will be stored in the `.debug_info` section.

Enums

Address	An address.
AttributeValue	The value of an attribute in a `DebuggingInformationEntry`.
CallFrameInstruction	An instruction in a frame description entry.
ConvertError	An error that occurred when converting a read value into a write value.
Error	An error that occurred when writing.
LineString	A string value for use in defining paths in line number programs.
Location	A single location.
Range	A single range.
Reference	A reference to a `.debug_info` entry.

Traits

Section	Functionality common to all writable DWARF sections.
Writer	A trait for writing the data to a DWARF section.

Type Definitions

ConvertResult	The result of a conversion.
Result	The result of a write.