This document covers Zed's debugging system, which provides integration with the Debug Adapter Protocol (DAP) to enable interactive debugging of applications. The debugger allows users to set breakpoints, step through code, inspect variables, and control program execution.
For details on UI session management and the lifecycle of debug states, see Debug Panel and Sessions. For an explanation of the Debug Adapter Protocol client and event handling, see DAP Communication. For details on the persistence and synchronization of breakpoints, see Breakpoint Management.
The debugger system is organized into three primary layers: the UI layer (debugger_ui crate), the project layer (project::debugger module), and the DAP protocol layer.
Sources: crates/debugger_ui/src/debugger_panel.rs59-74 crates/project/src/debugger/session.rs155-173 crates/project/src/debugger/dap_store.rs94-102
The DebugPanel serves as the primary UI container, managing multiple DebugSession instances crates/debugger_ui/src/debugger_panel.rs59-67 At the project layer, DapStore manages the lifecycle of Session entities, which handle DAP protocol communication crates/project/src/debugger/dap_store.rs94-102
Debug sessions progress through distinct states from initialization to termination, managed by the SessionState enum crates/project/src/debugger/session.rs155-161
Sources: crates/project/src/debugger/session.rs155-161 crates/debugger_ui/src/debugger_panel.rs177-195
DapStore creates a Session entity with a unique SessionId crates/project/src/debugger/dap_store.rs94-102DebugPanel::start_session() creates corresponding UI components and handles adapter registration via DapRegistry crates/debugger_ui/src/debugger_panel.rs177-195SessionState::Booting manages async tasks, including resolving the DebugAdapterBinary crates/project/src/debugger/session.rs155-160SessionState::Running and establishes a DebugAdapterClient crates/project/src/debugger/session.rs161-173Sessions can spawn child sessions, often seen in JavaScript/Node.js debugging. The DebugPanel::sessions_with_children field maintains this hierarchy as an IndexMap<Entity<DebugSession>, Vec<WeakEntity<DebugSession>>> crates/debugger_ui/src/debugger_panel.rs66-68
The DebugPanel is the main UI entry point, managing session selection and displaying the active session's state through various specialized sub-views.
Sources: crates/debugger_ui/src/debugger_panel.rs60-75 crates/debugger_ui/src/session/running/variable_list.rs190-205 crates/debugger_ui/src/session/running/memory_view.rs31-41
| Component | Purpose | Implementation |
|---|---|---|
VariableList | Inspects variables and scopes | VariableList crates/debugger_ui/src/session/running/variable_list.rs190 |
StackFrameList | Call stack navigation | StackFrameList crates/debugger_ui/src/session/running/stack_frame_list.rs35 |
BreakpointList | Management of all breakpoints | BreakpointList crates/debugger_ui/src/session/running/breakpoint_list.rs49 |
MemoryView | Hex/ASCII memory inspection | MemoryView crates/debugger_ui/src/session/running/memory_view.rs31 |
Communication with debug adapters follows the Debug Adapter Protocol specification. Requests are abstracted through the DapCommand trait crates/project/src/debugger/dap_command.rs37-58
StepCommand, NextCommand, PauseCommand, ContinueCommand crates/project/src/debugger/dap_command.rs109-158StackTraceCommand, ScopesCommand, VariablesCommand crates/project/src/debugger/session.rs4-11ReadMemory, WriteMemoryArguments crates/project/src/debugger/session.rs14-33The DebugAdapterClient handles the low-level transport (stdio or TCP) and message dispatch crates/project/src/debugger/session.rs212-220
Breakpoints are managed via the BreakpointStore, which handles synchronization between the editor and active debug sessions crates/project/src/debugger/breakpoint_store.rs1-25
The BreakpointList UI component allows users to toggle states (Enabled/Disabled) and set conditions or log messages crates/debugger_ui/src/session/running/breakpoint_list.rs174-203
Debug sessions track thread state through the ThreadStatus enum crates/project/src/debugger/session.rs99-107:
| Status | Label | Description |
|---|---|---|
Running | "Running" | Thread is executing code |
Stopped | "Stopped" | Thread hit a breakpoint or was paused |
Stepping | "Stepping" | Thread is performing a step operation |
Exited | "Exited" | Thread has terminated |
Sources: crates/project/src/debugger/session.rs109-119
The Thread struct maintains the current StackFrame hierarchy for each active thread crates/project/src/debugger/session.rs122-127
The MemoryView provides a specialized interface for low-level memory inspection, allowing users to view raw bytes in hex and ASCII formats crates/debugger_ui/src/session/running/memory_view.rs165-187
UniformList for efficient rendering of large memory ranges crates/debugger_ui/src/session/running/memory_view.rs201-208Sources: crates/debugger_ui/src/session/running/memory_view.rs1-41
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.