Crate symbolic_debuginfo

Abstractions for dealing with object files and debug information.

This module defines the Object type, which is an abstraction over various object file formats used in different platforms. Also, since executables on MacOS might contain multiple object files (called a “Fat MachO”), there is an Archive type, that provides a uniform interface with access to an objects iterator in all platforms.

Most processing of object files will happen on the Object type or its concrete implementation for one platform. To allow abstraction over this, there is the ObjectLike trait. It defines common attributes and gives access to a DebugSession, which can be used to perform more stateful handling of debug information.

See Object for the full API, or use one of the modules for direct access to the platform-dependent data.

Background

The functionality of symbolic::debuginfo is conceptionally similar to the object crate. However, there are key differences that warranted a separate implementation:

• object has a stronger focus on executable formats, while symbolic focusses on debugging information. This is why symbolic also includes a variant for PDBs and Breakpad objects, where object instead has a WASM variant.
• object contains far more generic access to the data within objects at the cost of performance. symbolic tries to optimize for debugging scenarios at the cost of generic usage.
• symbolic contains an abstraction for multi-object files (Archive), which is not easily possible in object due to the use of lifetimes on the object::Object trait.

Modules

• breakpad
  Support for Breakpad ASCII symbols, used by the Breakpad and Crashpad libraries.
• dwarf
  Support for DWARF debugging information, common to ELF and MachO. In rare cases, PE’s may contain it as well.
• elf
  Support for the Executable and Linkable Format, used on Linux.
• function_builder
  Contains FunctionBuilder, which can be used to create a Function with inlinees and line records in the right structure.
• js
  Utilities specifically for working with JavaScript specific debug info.
• macho
  Support for Mach Objects, used on macOS and iOS.
• pdb
  Support for Program Database, the debug companion format on Windows.
• pe
  Support for Portable Executables, an extension of COFF used on Windows.
• ppdb
  Support for Portable PDB Objects.
• sourcebundle
  Support for Source Bundles, a proprietary archive containing source code.
• wasm
  Support for WASM Objects (WebAssembly).

Structs

• Archive
  A generic archive that can contain one or more object files.
• FileEntry
  File information comprising a compilation directory, relative path and name.
• FileInfo
  File information referred by LineInfo comprising a directory and name.
• Function
  Debug information for a function.
• LineInfo
  File and line number mapping for an instruction address.
• ObjectError
  An error when dealing with any kind of Object.
• ObjectIterator
  An iterator over Objects in an Archive.
• Symbol
  A symbol from a symbol table.
• SymbolMap
  A sorted list of symbols, suitable for quick lookups.
• UnknownFileFormatError
  An error returned for unknown or invalid FileFormats.
• UnknownObjectKindError
  An error returned for unknown or invalid ObjectKinds.

Enums

• FileFormat
  Represents the physical object file format.
• Object
  A generic object file providing uniform access to various file formats.
• ObjectDebugSession
  A generic debugging session.
• ObjectFileIterator
  An iterator over source files in an Object.
• ObjectFunctionIterator
  An iterator over functions in an Object.
• ObjectKind
  Represents the designated use of the object file and hints at its contents.
• SymbolIterator
  A generic symbol iterator

Traits

• DebugSession
  A stateful session for interfacing with debug information.
• ObjectLike
  An object containing debug information.

Functions

• peek
  Tries to infer the object type from the start of the given buffer.

Type Aliases

• DynIterator
  A dynamically dispatched iterator over items with the given lifetime.
• SymbolMapIter
  IntoIterator type for SymbolMap.