🥮 mooncakes.io
    Sign in

    dwarfscope

    MoonBit DWARF debug info parser, symbol resolver, stack unwinder, and crash reporter for MCU, Linux, and WebAssembly.

    dwarf
    elf
    debug
    embedded
    symbol
    Download zip
    Version
    0.1.1
    License
    Apache-2.0
    Repository
    Last updated
    2 months ago
    Downloads
    31

    #moonbit-dwarfscope

    CI License

    moonbit-dwarfscope is a pure-MoonBit ELF and DWARF analysis library with a native command-line entrypoint. It is designed for firmware, embedded Linux, and WebAssembly toolchains that need symbol lookup, source mapping, call-frame data, and crash-report generation without binding this project to a C runtime.

    #What it provides

    • ELF32 and ELF64 header, program-header, section, symbol, relocation, and note parsing with little- and big-endian readers.
    • DWARF line-program decoding, DIE trees and attributes, location-expression evaluation, location lists, and common call-frame information.
    • Indexed address-to-symbol resolution with correct half-open symbol ranges.
    • High-level DebugImage summaries, backtrace symbolization, source locations, symbol-table diffs, and Markdown/JSON crash reports.
    • A native dwarfscope entrypoint for summary output, section/symbol inspection, and address lookup.

    The core parser is implemented in MoonBit. The native CLI uses moonbitlang/x/fs only for reading the input file.

    #Package layout

    PackagePurpose
    src/binary_readerBounds-checked byte, endian, string, and LEB128 readers
    src/elfELF structures, parsing, symbols, relocations, notes, and demangling
    src/dwarf_lineLine headers, state machine, v5 descriptors, and lookup
    src/dwarf_dieAbbreviations, DIE trees, attributes, ranges, variables, and types
    src/dwarf_locLocation opcodes, stack evaluation, and location lists
    src/frameCIE/FDE parsing, CFI execution, and unwind lookup
    src/modelDebugImage, indexes, summaries, diffs, and reports
    src/cli_coreTestable CLI argument, batch, exporter, and rendering logic
    src/cliNative executable entrypoint

    #Requirements

    • MoonBit stable toolchain. The local verification record was produced with MoonBit 0.1.20260819 and compiler v0.10.9+6e6c44045.
    • A native C toolchain when building the native CLI or running native tests.

    #Library usage

    Add the module as a dependency in your MoonBit project and import the package you need:

    import {
  "wuhaiting321/dwarfscope/src/model",
}

fn analyze(bytes : Bytes) -> String raise {
  let image = @model.DebugImage::parse("firmware.elf", bytes)
  let summary = image.summary()
  summary.to_markdown()
}

    DebugImage::parse accepts bytes so callers can obtain them from their own filesystem, embedded-resource, or network layer. Parsing failures use MoonBit's checked-error mechanism.

    #Command-line usage

    The executable is native because file access is platform-specific:

    moon run src/cli --target native -- --help
moon run src/cli --target native -- --format text firmware.elf
moon run src/cli --target native -- --format markdown firmware.elf
moon run src/cli --target native -- --format json firmware.elf
moon run src/cli --target native -- --addr 0x8000 firmware.elf
moon run src/cli --target native -- --header --sections --symbols firmware.elf

    Supported options include --help, --version, --header, --sections, --symbols, --addr VALUE, and --format text|markdown|json. Invalid addresses, formats, unknown options, and multiple input paths are reported before file parsing.

    #Benchmark

    Run the deterministic native parser benchmark locally:

    moon run benchmarks --target native --release

    The benchmark reports iteration count, successful operations, input size, elapsed milliseconds, and operations per second for both parsing and a 1,024-symbol index build/lookup workload. These are deterministic small workloads and should not be generalized to large debug images. The recorded local result and environment details are in docs/benchmarks/2026-08-24-native.md.

    #Development

    Run the same core checks locally:

    moon fmt --check
moon check --deny-warn
moon check --target all
moon test --deny-warn
moon test --target native --deny-warn
moon info
moon build --release --target native

    moon info regenerates the package interface summaries. Review any pkg.generated.mbti change as a public-API change; do not edit generated files by hand.

    GitHub Actions runs the formatting, deny-warn, cross-target check, native tests, coverage summary, interface-diff, and native release-build gates on pushes and pull requests.

    #License

    Copyright 2026 wuhaiting321. This project is distributed under the Apache License 2.0.

    #中文说明

    moonbit-dwarfscope 是一个纯 MoonBit 实现的 ELF/DWARF 分析库，并 提供原生命令行入口，适用于固件、嵌入式 Linux 和 WebAssembly 工具链中的 符号解析、源码定位、调用帧信息和崩溃报告生成。

    项目包含边界检查的二进制读取器、ELF 解析器、DWARF 行号/DIE/位置表达式/ 调用帧模块，以及面向使用者的 DebugImage 摘要、地址索引、符号 差异分析和 Markdown/JSON 报告接口。原生 CLI 负责读取文件，核心解析器仍 由 MoonBit 实现。

    常用命令：

    moon run src/cli --target native -- --help
moon run src/cli --target native -- --format json firmware.elf
moon run src/cli --target native -- --addr 0x8000 firmware.elf
moon fmt --check
moon check --deny-warn
moon test --target native --deny-warn

    许可证为 Apache License 2.0，详见 LICENSE。

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io