Toy Debugger — A simple debugger built using the LLDB…

Pitch

Description

Comments

About this project

Toy Debugger is an educational tool demonstrating the use of the LLDB C++ API to create a basic debugger. Perfect for those looking to learn about debugging with a hands-on project, it includes essential commands and setup tips, making it easy to get started.

The Toy Debugger project is a practical demonstration of utilizing the LLDB C++ API to construct a basic debugging tool. Designed for simplicity and ease of use, this debugger allows developers to step through code, set breakpoints, and inspect variable states while running a target executable.

Key Features:

Interactive Commands: Users can easily navigate through their code with intuitive keyboard commands to run programs, add breakpoints, print variable values, and control execution flow. The available commands include:

Key	Action
`r`	Run the program (automatically breaks on `main` if no breakpoints are set)
`b`	Add a breakpoint (specify in the format name/file:line)
`p`	Print the value of a variable
`n`	Step over the current line
`s`	Step into a function
`o`	Step out of the current function
`c`	Continue executing the program
`q`	Quit the debugger

Input Mode: A user-friendly interface facilitates the process of adding breakpoints and printing variables. Users can confirm inputs with the Enter key or cancel actions with the Esc key.
Logs and Troubleshooting: The debugger redirects stderr output to a log file, tdbg.log, which assists in diagnosing issues. In cases where the debugger cannot locate the source of a function, it defaults to displaying the assembly code, ensuring users can continue debugging with commands like step over or step out.
Type Mappings: The debugger recognizes various data types, allowing for easy interactions among pointers, references, arrays, and different number types. This includes built-in mappings such as:

Type	Mapping
Pointer	`p`
Integer (int)	`i`
Float	`f`
Bool	`b`
Struct	`s`

This mapping, coupled with overlapping symbols for types such as Short and Struct, maintains a streamlined workflow while debugging.

Requirements:

A functional build requires LLVM version 21. Installation instructions for Void Linux and macOS are provided in the README. After cloning the repository, users can compile the debugger and a sample program with a simple make command.

For further detailed insights into the project's capabilities and usage, refer to the full README. This tool serves as a foundational resource for developers looking to explore debugging through the LLDB C++ API.