dLua

A GDB-like dynamic debugger for Lua programs on Linux.

中文文档 (Chinese) | Detailed Usage Guide

---

Features

• Linux Platform Support: Designed for Linux environments.
• C++ Implementation: High performance with minimal overhead.
• Non-intrusive Dynamic Attach: Attaches directly to already running Lua processes without code modification.
• GDB-Style Debugging Interface:
  • Breakpoints: Line breakpoints, function breakpoints, and conditional breakpoints. Flexible syntax supporting spaces (e.g., b file.lua:10, b file.lua 10, b file.lua : 10).
  • Execution Control: Next line (n), step into (s), finish function (fin), continue (c).
  • Inspection & Evaluation: Stack backtrace (bt), view/switch stack frames (f), inspect expressions (p), print tables, list source code (l).
  • Runtime Modification: Set local/upvalue/global variables (set), execute arbitrary Lua snippets (r).
  • Breakpoint Management: Enable (en), disable (dis), delete (d), inspect breakpoints (i b).

---

Build & Installation

Prerequisites

• Linux OS (e.g., Ubuntu / Debian / CentOS)
• GCC / G++ supporting C++11 or higher
• GNU Readline development library (libreadline-dev)
• Lua 5.3+ headers and library

Build Steps

1. Clone the repository:

   git clone https://github.com/esrrhs/dLua.git
   cd dLua

2. Run build.sh to compile dlua (frontend CLI), dluaagent.so (debugger agent), and test_unit:

   ./build.sh

3. Run unit tests to verify:

   ./test_unit

4. Download or compile hookso (shared library injection utility), and place the hookso binary in the same directory as dlua and dluaagent.so.

---

Quick Start

1. Start your target Lua process:

   lua test.lua

   Assume PID is 1234.

2. Launch dlua and attach to the target PID:

   ./dlua 1234

   When connected:

   attach to 1234 ok, use ctrl+c to input command, eg: h
   

3. Press Ctrl+C to interrupt execution and enter commands. For example:

   (dlua) b test.lua 23
   (dlua) bt
   (dlua) p year
   (dlua) c
   (dlua) q
   

For full command references, detailed options, and examples, please see usage.md.

---

Related Projects

• lua-family-bucket
• hookso