Module write

Expand description

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.
Relocation: A relocation to be applied to a 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.
RelocationTarget: The target of a relocation.

Traits§

RelocateWriter: A Writer which also records relocations.
Section: Functionality common to all writable DWARF sections.
Writer: A trait for writing the data to a DWARF section.

Type Aliases§

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