ossrules.md

opentui

Build terminal UIs with OpenTUI. Covers Core, frameworks, components, application APIs, testing, extensions, integrations, deployment, and public API lookup.

Install
npx skills add 'https://github.com/anomalyco/opentui/tree/main/packages/web/src/content'
Download bundle ↓
main · ac753b4 ↗Scanned 2026-09-15

Contributors

GitHub-linked commit authors for this SKILL.md at the saved revision. Co-authors and history before file renames are not included.

File history ↗

docs/test-and-debug/native-crashes.mdx

docs/test-and-debug/native-crashes.mdxBrowse 89 files
View on GitHub
504 tokens

2,194 bytes
Token encoding: o200k_base
Snapshot ac753b4

← Back to SKILL.md

title: Native crash debugging description: Resolve native crash addresses with matching release symbols

Native crash debugging

Download opentui-symbols-v<VERSION>-<platform>-<arch>[-musl].zip from the matching GitHub Release. Use the exact version, architecture, and Linux libc. Older releases may not have symbol archives. A separately compiled Debug build has different code and cannot substitute.

Load the symbols

  • Linux: place libopentui.so.debug beside the matching library or in its .debug subdirectory. GDB finds it through .gnu_debuglink; the ELF build IDs also match. Use gdb /path/to/executable /path/to/core for a core dump.
  • macOS: load libopentui.dylib.dSYM with LLDB's target symbols add /path/to/libopentui.dylib.dSYM. Check matching UUIDs with dwarfdump --uuid.
  • Windows: add the directory containing opentui.pdb to the debugger's symbol path and reload symbols. Its GUID and age must match the DLL's CodeView record.

Each archive's manifest.json records the version, target/ABI, source commit, binary identity, and symbol checksums. The binary checksum is before signing; Windows signing changes that checksum, not the PDB identity.

Report a crash

Include the OpenTUI and runtime versions, OS/architecture/libc, reproduction steps, and a native trace or core/minidump. Raw addresses need module identities and load addresses to account for ASLR. Symbols do not capture crashes or recover optimized-out variables. Inspect dumps before sharing: they can contain application data and secrets.

For contributors

build:native builds ReleaseFast once with debug information, saves separate symbols outside npm, and strips only the distribution copy. Linux uses binutils; macOS cross-builds use LLVM through LLVM_BIN=$(brew --prefix llvm)/bin plus Xcode tools. Windows uses LLVM's llvm-readobj and llvm-pdbutil. Generate dSYMs before deleting the Zig object cache. build:native:dev remains unstripped.

Release symbol archives stay attached to their GitHub Release, outside npm. PR and snapshot artifacts retain their short-lived CI retention policy.

← All OpenTUI skillsProject instructions →