Guide to building a debugger from scratch using Rust for Windows usermode debugging

Introduction to Debugger Development

A new guide outlines the process of creating a debugger from the ground up. The author, with prior experience on the Microsoft Debugger Platform team, initiated this project to deepen their understanding of Rust and to provide an educational resource on how debuggers function.

The project emphasizes using Rust due to its ecosystem of crates that handle complex tasks like symbol resolution and disassembly, allowing the guide to concentrate on fundamental debugging principles. The initial focus is on live usermode debugging specifically for Windows operating systems.

What is a Debugger?

The guide defines a debugger as a tool capable of analyzing either a running system or a static snapshot, such as a core file or crash dump. While many tools assist in debugging, a debugger typically refers to software like GDB, LLDB, Visual Studio, or WinDbg, which perform these core analysis functions.

The core concepts discussed are broadly applicable across different operating systems, with the primary variations being the specific OS APIs used for process debugging and the terminology employed for various concepts.

Windows Debugging APIs

For Windows, the guide highlights the specific APIs that provide the necessary functionality for debugger implementation. These APIs are documented on MSDN's Debugging Functions page and are the same ones utilized by established debuggers like Visual Studio and WinDbg.

The guide distinguishes these from higher-level APIs, such as those of WinDbg's DbgEng engine, which offer advanced features like stack unwinding, symbol analysis, and flow control through interfaces like IDebugClient.

Learning Resources and Code Access

While the guide does not extensively detail Rust code, it focuses on core concepts and APIs that are language-agnostic, making it accessible even to those with limited Rust knowledge. For Rust novices, the official Rust language website is recommended as a starting point.

The code for the initial part of the debugger project is available in a 'part1' branch on GitHub. Readers are encouraged to clone the repository and use an IDE with the rust-analyzer plugin for an optimal follow-along experience.