Skip to content

Commit ec547b8

Browse files
RemcoSmitsDevAnthony-Eid
RemcoSmitsDev
and
Anthony-Eid
authored
Add debug configuration documentation (#96)
* Start adding docs for configurations and adapters * Update debugger setting files with settings, attach config, & themes I also ran prettier and typos on it too." --------- Co-authored-by: Anthony Eid <[email protected]>
1 parent 56abc60 commit ec547b8

File tree

1 file changed

+319
-17
lines changed

1 file changed

+319
-17
lines changed

‎docs/src/debugger.md

+319-17
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,194 @@
11
# Debugger
22

3-
## Debug Configuration
3+
Zed uses the Debug Adapter Protocol (DAP) to provide debugging functionality across multiple programming languages.
4+
DAP is a standardized protocol that defines how debuggers, editors, and IDEs communicate with each other.
5+
It allows Zed to support various debuggers without needing to implement language-specific debugging logic.
6+
This protocol enables features like setting breakpoints, stepping through code, inspecting variables,
7+
and more, in a consistent manner across different programming languages and runtime environments.
48

5-
To debug a program using Zed you must first create a debug configuration within your project located at `.zed/debug.json`
9+
## Supported Debug Adapters
10+
11+
Zed supports a variety of debug adapters for different programming languages:
12+
13+
- JavaScript (node): Enables debugging of Node.js applications, including setting breakpoints, stepping through code, and inspecting variables in JavaScript.
14+
15+
- Python (debugpy): Provides debugging capabilities for Python applications, supporting features like remote debugging, multi-threaded debugging, and Django/Flask application debugging.
16+
17+
- LLDB: A powerful debugger for C, C++, Objective-C, and Swift, offering low-level debugging features and support for Apple platforms.
18+
19+
- GDB: The GNU Debugger, which supports debugging for multiple programming languages including C, C++, Go, and Rust, across various platforms.
20+
21+
- Go (dlv): Delve, a debugger for the Go programming language, offering both local and remote debugging capabilities with full support for Go's runtime and standard library.
22+
23+
- PHP (xdebug): Provides debugging and profiling capabilities for PHP applications, including remote debugging and code coverage analysis.
24+
25+
- Custom: Allows you to configure any debug adapter that supports the Debug Adapter Protocol, enabling debugging for additional languages or specialized environments not natively supported by Zed.
26+
27+
These adapters enable Zed to provide a consistent debugging experience across multiple languages while leveraging the specific features and capabilities of each debugger.
28+
29+
## How To Get Started
30+
31+
To start a debug session, we added few default debug configurations for each supported language that supports generic configuration options. To see all the available debug configurations, you can use the command palette `debugger: start` action, this should list all the available debug configurations.
32+
33+
### Configuration
34+
35+
To create a custom debug configuration you have to create a `.zed/debug.json` file in your project root directory. This file should contain an array of debug configurations, each with a unique label and adapter the other option are optional/required based on the adapter.
636

737
```json
838
[
939
{
40+
// The label for the debug configuration and used to identify the debug session inside the debug panel
1041
"label": "Example Start debugger config"
11-
// The debug adapter to use
12-
// Zed supports javascript, python, lldb, go, and custom out of the box
42+
// The debug adapter that Zed should use to debug the program
1343
"adapter": "custom",
14-
// request: defaults to launch
15-
// - launch: Zed will launch the program to be debugged
16-
// - attach: Zed will attach to a running program to debug it
44+
// Request: defaults to launch
45+
// - launch: Zed will launch the program if specified or shows a debug terminal with the right configuration
46+
// - attach: Zed will attach to a running program to debug it or when the process_id is not specified we will show a process picker (only supported for node currently)
1747
"request": "launch",
18-
// cwd: defaults to the current working directory of your project
19-
// The current working directory to start the debugger from
20-
// accepts zed task variables e.g. $ZED_WORKTREE_ROOT
48+
// cwd: defaults to the current working directory of your project ($ZED_WORKTREE_ROOT)
49+
// this field also supports task variables e.g. $ZED_WORKTREE_ROOT
2150
"cwd": "$ZED_WORKTREE_ROOT",
22-
// program: The program to debug
23-
// accepts zed task variables
51+
// program: The program that you want to debug
52+
// this fields also support task variables e.g. $ZED_FILE
53+
// Note: this field should only contain the path to the program you want to debug
2454
"program": "path_to_program",
25-
// Additional initialization arguments to be sent on DAP initialization
55+
// initialize_args: This field should contain all the adapter specific initialization arguments that are directly send to the debug adapter
2656
"initialize_args": {
27-
57+
// "stopOnEntry": true // e.g. to stop on the first line of the program (These args are DAP specific)
2858
}
2959
}
3060
]
3161
```
3262

63+
### Using Attach [WIP]
64+
65+
Only javascript supports starting a debug session using attach.
66+
67+
When using the attach request with a process ID the syntax is as follows:
68+
69+
```json
70+
{
71+
"label": "Attach to Process",
72+
"adapter": "javascript",
73+
"request": {
74+
"attach": {
75+
"process_id": "12345"
76+
}
77+
}
78+
}
79+
```
80+
81+
Without process ID the syntax is as follows:
82+
83+
```json
84+
{
85+
"label": "Attach to Process",
86+
"adapter": "javascript",
87+
"request": {
88+
"attach": {}
89+
}
90+
}
91+
```
92+
93+
#### JavaScript Configuration
94+
95+
##### Debug Active File
96+
97+
This configuration allows you to debug a JavaScript file in your project.
98+
99+
```json
100+
{
101+
"label": "JavaScript: Debug Active File",
102+
"adapter": "javascript",
103+
"program": "$ZED_FILE",
104+
"request": "launch",
105+
"cwd": "$ZED_WORKTREE_ROOT"
106+
}
107+
```
108+
109+
##### Debug Terminal
110+
111+
This configuration will spawn a debug terminal where you could start you program by typing `node test.js`, and the debug adapter will automatically attach to the process.
112+
113+
```json
114+
{
115+
"label": "JavaScript: Debug Terminal",
116+
"adapter": "javascript",
117+
"request": "launch",
118+
"cwd": "$ZED_WORKTREE_ROOT",
119+
// "program": "$ZED_FILE", // optional if you pass this in, you will see the output inside the terminal itself
120+
"initialize_args": {
121+
"console": "integratedTerminal"
122+
}
123+
}
124+
```
125+
126+
#### PHP Configuration
127+
128+
##### Debug Active File
129+
130+
This configuration allows you to debug a PHP file in your project.
131+
132+
```json
133+
{
134+
"label": "PHP: Debug Active File",
135+
"adapter": "php",
136+
"program": "$ZED_FILE",
137+
"request": "launch",
138+
"cwd": "$ZED_WORKTREE_ROOT"
139+
}
140+
```
141+
142+
#### Python Configuration
143+
144+
##### Debug Active File
145+
146+
This configuration allows you to debug a Python file in your project.
147+
148+
```json
149+
{
150+
"label": "Python: Debug Active File",
151+
"adapter": "python",
152+
"program": "$ZED_FILE",
153+
"request": "launch",
154+
"cwd": "$ZED_WORKTREE_ROOT"
155+
}
156+
```
157+
158+
#### GDB Configuration
159+
160+
**NOTE:** This configuration is for Linux systems only & intel macbooks.
161+
162+
##### Debug Program
163+
164+
This configuration allows you to debug a program using GDB e.g. Zed itself.
165+
166+
```json
167+
{
168+
"label": "GDB: Debug program",
169+
"adapter": "gdb",
170+
"program": "$ZED_WORKTREE_ROOT/target/debug/zed",
171+
"request": "launch",
172+
"cwd": "$ZED_WORKTREE_ROOT"
173+
}
174+
```
175+
176+
#### LLDB Configuration
177+
178+
##### Debug Program
179+
180+
This configuration allows you to debug a program using LLDB e.g. Zed itself.
181+
182+
```json
183+
{
184+
"label": "LLDB: Debug program",
185+
"adapter": "lldb",
186+
"program": "$ZED_WORKTREE_ROOT/target/debug/zed",
187+
"request": "launch",
188+
"cwd": "$ZED_WORKTREE_ROOT"
189+
}
190+
```
191+
33192
## Breakpoints
34193

35194
Zed currently supports these types of breakpoints
@@ -41,8 +200,151 @@ Standard breakpoints can be toggled by left clicking on the editor gutter or usi
41200

42201
Log breakpoints can also be edited/added through the edit log breakpoint action
43202

44-
## Starting a Debugger Session
203+
## Settings
204+
205+
- `stepping_granularity`: Determines the stepping granularity.
206+
- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
207+
- `button`: Whether to show the debug button in the status bar.
208+
- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
209+
- `log_dap_communications`: Whether to log messages between active debug adapters and Zed
210+
- `format_dap_log_messages`: Whether to format dap messages in when adding them to debug adapter logger
211+
212+
### Stepping granularity
213+
214+
- Description: The Step granularity that the debugger will use
215+
- Default: line
216+
- Setting: debugger.stepping_granularity
217+
218+
**Options**
219+
220+
1. Statement - The step should allow the program to run until the current statement has finished executing.
221+
The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
222+
For example 'for(int i = 0; i < 10; i++)' could be considered to have 3 statements 'int i = 0', 'i < 10', and 'i++'.
223+
224+
```json
225+
{
226+
"debugger": {
227+
"stepping_granularity": "statement"
228+
}
229+
}
230+
```
231+
232+
2. Line - The step should allow the program to run until the current source line has executed.
233+
234+
```json
235+
{
236+
"debugger": {
237+
"stepping_granularity": "line"
238+
}
239+
}
240+
```
241+
242+
3. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
243+
244+
```json
245+
{
246+
"debugger": {
247+
"stepping_granularity": "instruction"
248+
}
249+
}
250+
```
251+
252+
### Save Breakpoints
253+
254+
- Description: Whether the breakpoints should be saved across Zed sessions.
255+
- Default: true
256+
- Setting: debugger.save_breakpoints
257+
258+
**Options**
259+
260+
`boolean` values
261+
262+
```json
263+
{
264+
"debugger": {
265+
"save_breakpoints": true
266+
}
267+
}
268+
```
269+
270+
### Button
271+
272+
- Description: Whether the button should be displayed in the debugger toolbar.
273+
- Default: true
274+
- Setting: debugger.show_button
275+
276+
**Options**
277+
278+
`boolean` values
279+
280+
```json
281+
{
282+
"debugger": {
283+
"show_button": true
284+
}
285+
}
286+
```
287+
288+
### Timeout
289+
290+
- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
291+
- Default: 2000ms
292+
- Setting: debugger.timeout
293+
294+
**Options**
295+
296+
`integer` values
297+
298+
```json
299+
{
300+
"debugger": {
301+
"timeout": 3000
302+
}
303+
}
304+
```
305+
306+
### Log Dap Communications
307+
308+
- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
309+
- Default: false
310+
- Setting: debugger.log_dap_communications
311+
312+
**Options**
313+
314+
`boolean` values
315+
316+
```json
317+
{
318+
"debugger": {
319+
"log_dap_communications": true
320+
}
321+
}
322+
```
323+
324+
### Format Dap Log Messages
325+
326+
- Description: Whether to format dap messages in when adding them to debug adapter logger. (Used for DAP development)
327+
- Default: false
328+
- Setting: debugger.format_dap_log_messages
329+
330+
**Options**
331+
332+
`boolean` values
333+
334+
```json
335+
{
336+
"debugger": {
337+
"format_dap_log_messages": true
338+
}
339+
}
340+
```
341+
342+
## Theme
343+
344+
The Debugger supports the following theme options
45345

46-
A debugger session can be started by the Start Debugging action or clicking the "Choose Debugger" button in the debugger panel when there are no active sessions.
346+
/// Color used to accent some of the debuggers elements
347+
/// Only accent breakpoint & breakpoint related symbols right now
47348

48-
Zed supports having multiple sessions
349+
**debugger.accent**: Color used to accent breakpoint & breakpoint related symbols
350+
**editor.debugger_active_line.background**: Background color of active debug line

0 commit comments

Comments
 (0)