Durin

Durin is a library for reading and writing the Dwarf debugging format.

It supports:

• Reading DWARF 4 and 5 from ELF and MachO object files.
• Writing DWARF 5 into GNU assembler-compatible assembly files.
• Writing DWARF 4 and 5 into object files.
• Split DWARF (.dwo files, .dwp package files, skeleton units).

It provides:

• Cross-platform: durin supports both ELF (Linux) and MachO (macOS) object files via the object library.
• Lazy: you can iterate compilation units without parsing their contents. Parse only as many debugging information entry (DIE) trees as you iterate over. durin also uses DW_AT_sibling references to avoid parsing a DIE's children to find its next sibling where possible.

Section Support

Install

To install durin as a dependency, run:

$ opam install durin

And add durin to your project's dune-project or *.opam files.

Documentation

• API reference on ocaml.org
• Explanation — conceptual background on DWARF:
  • DWARF 5 terminology (compilation units, DIEs, the root DIE, and the string offsets table)
  • Object files and sections (DWARF sections in ELF vs Mach-O)
• Example programs in example directory
  • A simple .debug_info parser
  • A simple .debug_line parser
  • A dwarfdump clone
  • An addr2line clone
  • A small utility dwprod to list the compilers used to create each compilation unit within a shared library or executable (via DW_AT_producer).
  • A dwarf-valiate clone, a program to validate the integrity of some DWARF information and the references between sections and compilation units.

Resources

• Apple Compact Unwinding Format is defined by the LLVM implementation.

  • https://github.com/llvm/llvm-project/blob/main/libunwind/include/mach-o/compact_unwind_encoding.h
  • https://faultlore.com/blah/compact-unwinding/
  • https://github.com/getsentry/symbolic/blob/master/symbolic-debuginfo/src/macho/compact.rs

• Vendor extensions from GCC https://sourceware.org/elfutils/DwarfExtensions

Future work / Known limitations

Big-endian is unsupported. Both read and write paths assume little-endian throughout. The Object.Buffer.Read functions are hardcoded LE, and all dwarf_write primitives are LE-only. This affects PowerPC 64, s390x, and big-endian MIPS targets. Fixing this requires coordinated changes: making Object.Buffer.Read endianness-aware, threading byte order through the encoding type, and adding _be write variants. All current targets (x86-64, ARM64 on Linux/macOS) are little-endian so this is low priority.