Toy Debugger

This project demonstrates how to use the LLDB C++ API to build a very basic debugger.

https://github.com/user-attachments/assets/5c336eb0-6b9b-4e89-8c59-6a9be5004b21

Requirements

[!IMPORTANT] You need to have llvm version 21 installed. You can install it with your package manager. Include paths in Makefile are specific for this version and have been tested on Void Linux and macOS.

# Void Linux
sudo xbps-install -S lldb21-devel clang llvm llvm-devel
# macOS
brew install llvm

After you clone the repository build the debugger and a sample program with make all -B.

How to use

Run the debugger with: ./tdbg <target_executable>

Example with arguments and environment variables:

./tdbg ./example arg1 arg2 arg3
./tdbg ./example -e MYENV=qwe -- arg1 arg2 arg3

Example with breakpoints:

./tdbg ./example -b main
./tdbg ./example -b example.c:54 -b example.c:60

Example with auto run:

./tdbg -run ./example
./tdbg -run ./example arg1 arg2 arg3
./tdbg -run ./example -e MYENV=qwe -- arg1 arg2 arg3

Interactive Commands

Input Mode

When adding breakpoints or printing variables:

• Enter: Confirm input
• Esc: Cancel and return to normal mode

Tips & Troubleshooting

• Logs: The debugger redirects stderr to tdbg.log. Check this file if something isn't working as expected.
• Missing Source: If the debugger enters a function without source (like a library call), it will fallback to disassembly. Use n (Step Over) or o (Step Out) to get back to your code.

Type mappings

[!NOTE] Some symbols are shared (e.g., s for both Short and Struct, c for both Char and Class).

Acknowledgment

• https://github.com/termbox/termbox2