Skip to content

debugging.md

Latest commit

 

History

History
84 lines (65 loc) · 2.9 KB

debugging.md

File metadata and controls

84 lines (65 loc) · 2.9 KB

Debugging Aburiscript

Working on a compiler can be complex. This playbook provides repeatable command paths for diagnosing parser, semantic, ABI, and code generation issues when contributing to Aburiscript.

Fast Triage by Symptom

  1. Wrong preprocessor output:
    • Run the compiler with -E to inspect the transformed text.
  2. Parser diagnostic mismatch or recovery bug:
    • Inspect parser/parser.cpp or parser/parser_cxx.cpp.
    • Reproduce the failure with the smallest possible source file.
  3. Name lookup or overload mismatch:
    • Inspect collect/decl_context.cpp, collect/lookup_engine.cpp, or collect/collect_decl.cpp.
    • Reduce the input until the wrong lookup is obvious in a single file.
  4. Link/mangling collision:
    • Inspect abi/mangle.cpp and abi/abi_policy.cpp.
    • Compare the emitted symbols or IR for a minimal reproducer.
  5. Compiles but runtime result is wrong:
    • The issue is likely in ast2llvm/ast2llvm.cpp, ast2llvm/flow.cpp, or ast2llvm/arith.cpp.
    • Write a minimal reproducer C file and emit the LLVM IR (see below) to check how ast2llvm lowered your AST.

Useful Repro Commands

Assuming you built the compiler into a build/ directory:

1. Preprocess Only

To see exactly what the parser sees (after macros and #includes are expanded):

./build/aburi input.c -E

2. Emit LLVM IR

This is the most critical command for debugging backend/codegen bugs. It outputs the human-readable LLVM Intermediate Representation.

./build/aburi input.c --emit-llvm -o out.ll

3. Emit Assembly

./build/aburi input.c -S -o out.s

4. Compile Object Only

Stops before invoking the system linker.

./build/aburi input.c -c -o out.o

5. AST Memory Report

Useful for verifying that AST nodes are being constructed and tracked correctly in side-tables.

./build/aburi input.c -c --ast-memory-report

Running Focused Tests

The public repository ships with a small runtime smoke suite under public_tests/.

# Configure with public tests enabled
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DLLVM_DIR=/path/to/llvm-18/lib/cmake/llvm -DABURI_BUILD_PUBLIC_TESTS=ON

# Run the public runtime smoke suite
ctest --test-dir build -R public_tests_runtime --output-on-failure

Crash Triage

If the Aburiscript compiler itself segfaults, you can run it through lldb (or gdb):

lldb -batch -o "run -- input.c -c" -k "bt" -k "quit" ./build/aburi

The Minimal Bug-Fix Loop

  1. Reproduce the bug with the smallest possible source file.
  2. Add or update a focused sample in public_tests/ when the bug belongs in the public smoke suite.
  3. Fix the bug in the smallest subsystem that owns the behavior (e.g., parser/, collect/, or ast2llvm/).
  4. Run the relevant compiler command directly on the reproducer.
  5. Run ctest -R public_tests_runtime if the change affects the public smoke suite.