yenru0/zed
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Apply documentation standards across all docs (#49177)

Browse Source 
## Summary

Comprehensive remediation of 146 documentation files to align with Zed's
documentation conventions and brand voice guidelines.

## Changes

### YAML Frontmatter
- Added `title` and `description` frontmatter to all docs missing it

### Settings UI Pattern
- Updated 48+ files to show Settings Editor before JSON examples
- Pattern: `Configure X in Settings ({#kb zed::OpenSettings}), or add to
your settings file:`
- Added `([how to edit](./configuring-zed.md#settings-files))` links for
JSON-only settings

### Brand Voice Fixes
- Removed exclamation points (command-palette, key-bindings, repl,
privacy-and-security, etc.)
- Simplified em dash chains to parentheticals (environment,
troubleshooting, agent-panel, etc.)
- Fixed marketing language (yarn.md intro, development/linux.md)

### Terminology Alignment
- `settings UI` -> `Settings Editor`
- `sidebar` -> specific panel names (Project Panel, Collab Panel)
- `directory` -> `folder` in non-technical contexts
- `workspace` -> `project` in non-LSP contexts
- `Command Palette` -> `command palette` (lowercase)

### Callout Standardization
- Converted various callout formats to standard `> **Note:**` pattern

## Related

Depends on conventions established in #49176.

Release Notes:

- N/A
This commit is contained in:
morgankrey authored and GitHub committed 2026-02-17 20:58:17 -06:00
1 parent 9743fe7dfd
commit 6daa541e77
142 files changed
+1947 -489
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/src/development/debuggers.md
+36 -36
View File
@@ -1,38 +1,42 @@
---
title: Using a debugger
description: "Guide to using a debugger for Zed development."
---
# Using a debugger
> **DISCLAIMER**: This is not documentation for [configuring Zed's debugger](../debugger.md).
> Rather, it is intended to provide information on how to use a debugger while developing Zed itself to both Zed employees and external contributors.
> This page is not about [configuring Zed's debugger](../debugger.md).
> It covers how to use a debugger while developing Zed itself.
## Using Zed's built-in debugger
While the Zed project is open you can open the `New Process Modal` and select the `Debug` tab. There you can see two debug configurations to debug Zed with, one for GDB and one for LLDB. Select the configuration you want and Zed will build and launch the binary.
Please note, GDB isn't supported on arm Macbooks
GDB is not supported on Apple Silicon Macs.
## Release build profile considerations
By default, builds using the release profile (release is the profile used for production builds, i.e. nightly, preview, and stable) include limited debug info.
By default, builds using the release profile (the profile used for nightly, preview, and stable) include limited debug info.
This is done by setting the `profile.(release).debug` field in the root `Cargo.toml` field to `"limited"`.
The official documentation for the `debug` field can be found [here](https://doc.rust-lang.org/cargo/reference/profiles.html#debug).
But the TLDR is that `"limited"` strips type and variable level debug info.
The official documentation for the `debug` field is [here](https://doc.rust-lang.org/cargo/reference/profiles.html#debug).
In short, `"limited"` strips type-level and variable-level debug info.
In release builds, this is done to reduce the binary size, as type and variable level debug info is not required, and does not impact the usability of generated stack traces.
In release builds, this reduces binary size. Type-level and variable-level debug info is not required for useful stack traces.
However, while the type and variable level debug info is not required for good stack traces, it is very important for a good experience using debuggers,
as without the type and variable level debug info, the debugger has no way to resolve local variables, inspect them, format them using pretty-printers, etc.
However, this data matters when you are actively debugging. Without it, debuggers cannot resolve local variables, inspect values, or format output with pretty-printers.
Therefore, in order to use a debugger to it's fullest extent when debugging a release build, you must compile a new Zed binary, with full debug info.
To get the full debugger experience on a release build, compile a Zed binary with full debug info.
The simplest way to do this, is to use the `--config` flag to override the `debug` field in the root `Cargo.toml` file when running `cargo run` or `cargo build` like so:
The simplest way is to use `--config` to override the `debug` field in the root `Cargo.toml` when running `cargo run` or `cargo build`:
```sh
cargo run --config 'profile.release.debug="full"'
cargo build --config 'profile.release.debug="full"'
```
> If you wish to avoid passing the `--config` flag on every invocation of `cargo`. You may also change the section in the [root `Cargo.toml`](https://github.com/zed-industries/zed/blob/main/Cargo.toml)
> If you do not want to pass `--config` on every `cargo` command, you can also change the section in the [root `Cargo.toml`](https://github.com/zed-industries/zed/blob/main/Cargo.toml)
>
> from
>
@@ -48,66 +52,62 @@ cargo build --config 'profile.release.debug="full"'
> debug = "full"
> ```
>
> This will ensure all invocations of `cargo run --release` or `cargo build --release` will compile with full debug info.
> This makes all invocations of `cargo run --release` or `cargo build --release` compile with full debug info.
>
> **WARNING:** Make sure to avoid committing these changes!
> **Warning:** Do not commit these changes.
## Running Zed with a shell debugger GDB/LLDB
### Background
When installing rust through rustup, (the recommended way to do so when developing Zed, see the documentation for getting started on your platform [here](../development.md))
a few additional scripts are installed and put on your path to assist with debugging binaries compiled with rust.
When you install Rust through rustup (the recommended setup for Zed development; see your platform guide [here](../development.md)), rustup also installs helper scripts for debugging Rust binaries.
These are `rust-gdb` and `rust-lldb` respectively.
These scripts are `rust-gdb` and `rust-lldb`.
You can read more information about these scripts and why they are useful [here](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html) if you are interested.
You can read more about these scripts [here](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html).
However, the summary is that they are simple shell scripts that wrap the standard `gdb` and `lldb` commands, injecting the relevant commands and flags to enable additional
rust-specific features such as pretty-printers and type information.
They are wrapper scripts around `gdb` and `lldb` that inject commands and flags for Rust-specific features such as pretty-printers and type info.
Therefore, in order to use `rust-gdb` or `rust-lldb`, you must have `gdb` or `lldb` installed on your system. If you don't have them installed, you will need to install them in a manner appropriate for your platform.
To use `rust-gdb` or `rust-lldb`, install `gdb` or `lldb` on your system.
According to the [previously linked article](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html), "The minimum supported debugger versions are GDB 7.7 and LLDB 310. However, the general rule is: the newer the better." Therefore, it is recommended to install the latest version of `gdb` or `lldb` if possible.
The [linked article](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html) notes that the minimum supported versions are GDB 7.7 and LLDB 310. In practice, newer versions are usually better.
> **Note**: `rust-gdb` is not installed by default on Windows, as `gdb` support for windows is not very stable. It is recommended to use `lldb` with `rust-lldb` instead on Windows.
> **Note**: `rust-gdb` is not installed by default on Windows because `gdb` support there is unstable. Use `rust-lldb` instead.
If you are unfamiliar with `gdb` or `lldb`, you can learn more about them [here](https://www.gnu.org/software/gdb/) and [here](https://lldb.llvm.org/) respectively.
If you are new to these tools, see the `gdb` docs [here](https://www.gnu.org/software/gdb/) and the `lldb` docs [here](https://lldb.llvm.org/).
### Usage with Zed
After following the steps above for including full debug info when compiling Zed,
You can either run `rust-gdb` or `rust-lldb` on the compiled Zed binary after building it with `cargo build`, by running one of the following commands:
After enabling full debug info and building with `cargo build`, run `rust-gdb` or `rust-lldb` against the compiled Zed binary:
```
rust-gdb target/debug/zed
rust-lldb target/debug/zed
```
Alternatively, you can attach to a running instance of Zed (such as an instance of Zed started using `cargo run`) by running one of the following commands:
You can also attach to a running Zed process (for example, one started with `cargo run`):
```
rust-gdb -p <pid>
rust-lldb -p <pid>
```
Where `<pid>` is the process ID of the Zed instance you want to attach to.
`<pid>` is the process ID of the Zed instance you want to attach to.
To get the process ID of a running Zed instance, you can use your systems process management tools such as `Task Manager` on windows or `Activity Monitor` on macOS.
To find the PID, use your system's process tools, such as Task Manager on Windows or Activity Monitor on macOS.
Alternatively, you can run the `ps aux | grep zed` command on macOS and Linux or `Get-Process | Select-Object Id, ProcessName` in an instance of PowerShell on Windows.
You can also run `ps aux | grep zed` on macOS and Linux, or `Get-Process | Select-Object Id, ProcessName` in PowerShell on Windows.
#### Debugging Panics and Crashes
Debuggers can be an excellent tool for debugging the cause of panics and crashes in all programs, including Zed.
Debuggers are useful for finding the cause of panics and crashes, including in Zed.
By default, when a process that `gdb` or `lldb` is attached to hits an exception such as a panic, the debugger will automatically stop at the point of the panic and allow you to inspect the state of the program.
By default, when a process attached to `gdb` or `lldb` hits an exception such as a panic, the debugger stops at that point so you can inspect program state.
Most likely, the point at which the debugger stops will be deep in the rust standard library panic or exception handling code, so you will need to navigate up the stack trace to find the actual cause of the panic.
The initial stop point is often in Rust standard library panic or exception handling code, so you usually need to walk up the stack to find the root cause.
This can be accomplished using the `backtrace` command in combination with the `frame select` command in `lldb`, with similar commands available in `gdb`.
In `lldb`, use `backtrace` with `frame select`. `gdb` provides equivalent commands.
Once the program is stopped, you will not be able to continue execution as you can before an exception is hit. However, you can jump around to different stack frames, and inspect the values of variables and expressions
within each frame, which can be very useful in identifying the root cause of the crash.
After the program stops on the exception, you usually cannot continue normal execution. You can still move between stack frames and inspect variables and expressions, which is often enough to identify the crash cause.
You can find additional information on debugging Zed crashes [here](./debugging-crashes.md).