🥮 mooncakes.io

    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
    last month
    Downloads
    7

    Dependencies

    #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