1# Toy Debugger
2
3This project demonstrates how to use the LLDB C++ API to build a very basic
4debugger.
5
6https://github.com/user-attachments/assets/5c336eb0-6b9b-4e89-8c59-6a9be5004b21
7
8## Requirements
9
10> [!IMPORTANT]
11> You need to have `llvm` version 21 installed. You can install it with your
12> package manager. Include paths in `Makefile` are specific for this version
13> and have been tested on Void Linux and macOS.
14
15```sh
16# Void Linux
17sudo xbps-install -S lldb21-devel clang llvm llvm-devel
18# macOS
19brew install llvm
20```
21
22After you clone the repository build the debugger and a sample program with
23`make all -B`.
24
25## How to use
26
27Run the debugger with: `./tdbg <target_executable>`
28
29Example with arguments and environment variables:
30
31```sh
32./tdbg ./example arg1 arg2 arg3
33./tdbg ./example -e MYENV=qwe -- arg1 arg2 arg3
34```
35
36Example with breakpoints:
37
38```sh
39./tdbg ./example -b main
40./tdbg ./example -b example.c:54 -b example.c:60
41```
42
43Example with auto run:
44
45```sh
46./tdbg -run ./example
47./tdbg -run ./example arg1 arg2 arg3
48./tdbg -run ./example -e MYENV=qwe -- arg1 arg2 arg3
49```
50
51### Interactive Commands
52
53| Key | Action |
54| :----------- | :---------------------------------------------------------------- |
55| `r` | Run the program (auto-breaks on `main` if no breakpoints set) |
56| `b` | Add a breakpoint (enter name/file:line) |
57| `p` | Print variable value |
58| `n` | Step over |
59| `s` | Step into |
60| `o` | Step out |
61| `c` | Continue execution |
62| `w` | Watch expression |
63| `h` | Toggle help view |
64| `Ctrl+Left` | Increases sidebar width |
65| `Ctrl+Right` | Reduces sidebar width |
66| `Ctrl+Up` | Increases log height |
67| `Ctrl+Down` | Reduces log height |
68| `q` | Quit debugger |
69
70### Input Mode
71
72When adding breakpoints or printing variables:
73- `Enter`: Confirm input
74- `Esc`: Cancel and return to normal mode
75
76### Tips & Troubleshooting
77
78- **Logs**: The debugger redirects `stderr` to `tdbg.log`. Check this file if
79 something isn't working as expected.
80- **Missing Source**: If the debugger enters a function without source (like a
81 library call), it will fallback to disassembly. Use `n` (Step Over) or `o`
82 (Step Out) to get back to your code.
83
84### Type mappings
85
86| Type | Mapping |
87| :------------ | :------------------------ |
88| Pointer | `p` |
89| Reference | `&` |
90| Array | `a` |
91| Integer (int) | `i` |
92| Char | `c` |
93| Float | `f` |
94| Double | `d` |
95| Bool | `b` |
96| Long | `l` |
97| Short | `s` |
98| Struct | `s` |
99| Class | `c` |
100| Void | `v` |
101| Enumeration | `e` |
102| Default | First letter of type name |
103
104> [!NOTE]
105> Some symbols are shared (e.g., `s` for both Short and Struct, `c` for both
106> Char and Class).
107
108## Acknowledgment
109
110- https://github.com/termbox/termbox2
111