docs: Improve docs for debugger (around breakpoints and doc structure) (#31962)
Closes #ISSUE Release Notes: - N/A
This commit is contained in:
Piotr Osiewicz
GitHub
parent
3e6435eddc
commit
a9d99d8347
1 changed files with 137 additions and 27 deletions
|
|
@ -34,7 +34,16 @@ For more advanced use cases, you can create debug configurations by directly edi
|
|||
|
||||
You can then use the `New Session Modal` to select a configuration and start debugging.
|
||||
|
||||
### Configuration
|
||||
### Launching & Attaching
|
||||
|
||||
Zed debugger offers two ways to debug your program; you can either _launch_ a new instance of your program or _attach_ to an existing process.
|
||||
Which one you choose depends on what you are trying to achieve.
|
||||
|
||||
When launching a new instance, Zed (and the underlying debug adapter) can often do a better job at picking up the debug information compared to attaching to an existing process, since it controls the lifetime of a whole program. Running unit tests or a debug build of your application is a good use case for launching.
|
||||
|
||||
Compared to launching, attaching to an existing process might seem inferior, but that's far from truth; there are cases where you cannot afford to restart your program, because e.g. the bug is not reproducible outside of a production environment or some other circumstances.
|
||||
|
||||
## Configuration
|
||||
|
||||
While configuration fields are debug adapter-dependent, most adapters support the following fields:
|
||||
|
||||
|
|
@ -58,22 +67,91 @@ While configuration fields are debug adapter-dependent, most adapters support th
|
|||
]
|
||||
```
|
||||
|
||||
#### Tasks
|
||||
|
||||
All configuration fields support task variables. See [Tasks Variables](./tasks.md#variables)
|
||||
|
||||
Zed also allows embedding a task that is run before the debugger starts. This is useful for setting up the environment or running any necessary setup steps before the debugger starts.
|
||||
### Build tasks
|
||||
|
||||
See an example [here](#build-binary-then-debug)
|
||||
|
||||
#### Python Examples
|
||||
|
||||
##### Python Active File
|
||||
Zed also allows embedding a Zed task in a `build` field that is run before the debugger starts. This is useful for setting up the environment or running any necessary setup steps before the debugger starts.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"label": "Active File",
|
||||
"label": "Build Binary",
|
||||
"adapter": "CodeLLDB",
|
||||
"program": "path_to_program",
|
||||
"request": "launch",
|
||||
"build": {
|
||||
"command": "make",
|
||||
"args": ["build", "-j8"]
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Build tasks can also refer to the existing tasks by unsubstituted label:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"label": "Build Binary",
|
||||
"adapter": "CodeLLDB",
|
||||
"program": "path_to_program",
|
||||
"request": "launch",
|
||||
"build": "my build task" // Or "my build task for $ZED_FILE"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Automatic scenario creation
|
||||
|
||||
Given a Zed task, Zed can automatically create a scenario for you. Automatic scenario creation also powers our scenario creation from gutter.
|
||||
Automatic scenario creation is currently supported for Rust, Go and Python. Javascript/TypeScript support being worked on.
|
||||
|
||||
### Example Configurations
|
||||
|
||||
#### JavaScript
|
||||
|
||||
##### Debug Active File
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"label": "Debug with node",
|
||||
"adapter": "JavaScript",
|
||||
"program": "$ZED_FILE",
|
||||
"request": "launch",
|
||||
"console": "integratedTerminal",
|
||||
"type": "pwa-node"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
##### Attach debugger to a server running in web browser (`npx serve`)
|
||||
|
||||
Given an externally-ran web server (e.g. with `npx serve` or `npx live-server`) one can attach to it and open it with a browser.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"label": "Inspect ",
|
||||
"adapter": "JavaScript",
|
||||
"type": "pwa-chrome",
|
||||
"request": "launch",
|
||||
"url": "http://localhost:5500", // Fill your URL here.
|
||||
"program": "$ZED_FILE",
|
||||
"webRoot": "${ZED_WORKTREE_ROOT}"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
##### Debug Active File
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"label": "Python Active File",
|
||||
"adapter": "Debugpy",
|
||||
"program": "$ZED_FILE",
|
||||
"request": "launch"
|
||||
|
|
@ -85,16 +163,20 @@ See an example [here](#build-binary-then-debug)
|
|||
|
||||
For a common Flask Application with a file structure similar to the following:
|
||||
|
||||
- .venv/
|
||||
- app/
|
||||
- **init**.py
|
||||
- **main**.py
|
||||
- routes.py
|
||||
- templates/
|
||||
- index.html
|
||||
- static/
|
||||
- style.css
|
||||
- requirements.txt
|
||||
```
|
||||
.venv/
|
||||
app/
|
||||
init.py
|
||||
main.py
|
||||
routes.py
|
||||
templates/
|
||||
index.html
|
||||
static/
|
||||
style.css
|
||||
requirements.txt
|
||||
```
|
||||
|
||||
the following configuration can be used:
|
||||
|
||||
```json
|
||||
[
|
||||
|
|
@ -154,18 +236,46 @@ For a common Flask Application with a file structure similar to the following:
|
|||
]
|
||||
```
|
||||
|
||||
#### TypeScript
|
||||
|
||||
##### Attach debugger to a server running in web browser (`npx serve`)
|
||||
|
||||
Given an externally-ran web server (e.g. with `npx serve` or `npx live-server`) one can attach to it and open it with a browser.
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"label": "Launch Chromee (TypeScript)",
|
||||
"adapter": "JavaScript",
|
||||
"type": "pwa-chrome",
|
||||
"request": "launch",
|
||||
"url": "http://localhost:5500",
|
||||
"program": "$ZED_FILE",
|
||||
"webRoot": "${ZED_WORKTREE_ROOT}",
|
||||
"sourceMaps": true,
|
||||
"build": {
|
||||
"command": "npx",
|
||||
"args": ["tsc"]
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Breakpoints
|
||||
|
||||
Zed currently supports these types of breakpoints:
|
||||
To set a breakpoint, simply click next to the line number in the editor gutter.
|
||||
Breakpoints can be tweaked dependending on your needs; to access additional options of a given breakpoint, right-click on the breakpoint icon in the gutter and select the desired option.
|
||||
At present, you can:
|
||||
|
||||
- Standard Breakpoints: Stop at the breakpoint when it's hit
|
||||
- Log Breakpoints: Output a log message instead of stopping at the breakpoint when it's hit
|
||||
- Conditional Breakpoints: Stop at the breakpoint when it's hit if the condition is met
|
||||
- Hit Breakpoints: Stop at the breakpoint when it's hit a certain number of times
|
||||
- Add a log to a breakpoint, which will output a log message whenever that breakpoint is hit.
|
||||
- Make the breakpoint conditional, which will only stop at the breakpoint when the condition is met. The syntax for conditions is adapter-specific.
|
||||
- Add a hit count to a breakpoint, which will only stop at the breakpoint after it's hit a certain number of times.
|
||||
- Disable a breakpoint, which will prevent it from being hit while leaving it visible in the gutter.
|
||||
|
||||
Standard breakpoints can be toggled by left-clicking on the editor gutter or using the Toggle Breakpoint action. Right-clicking on a breakpoint or on a code runner symbol brings up the breakpoint context menu. This has options for toggling breakpoints and editing log breakpoints.
|
||||
Some debug adapters (e.g. CodeLLDB and JavaScript) will also _verify_ whether your breakpoints can be hit; breakpoints that cannot be hit are surfaced more prominently in the UI.
|
||||
|
||||
Other kinds of breakpoints can be toggled/edited by right-clicking on the breakpoint icon in the gutter and selecting the desired option.
|
||||
All breakpoints enabled for a given project are also listed in "Breakpoints" item in your debugging session UI. From "Breakpoints" item in your UI you can also manage exception breakpoints.
|
||||
The debug adapter will then stop whenever an exception of a given kind occurs. Which exception types are supported depends on the debug adapter.
|
||||
|
||||
## Settings
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue