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).
docs/src/development/debugging-crashes.md
+11 -6
View File
@@ -1,20 +1,25 @@
---
title: Debugging Crashes
description: "Guide to debugging crashes for Zed development."
---
# Debugging Crashes
When Zed panics or otherwise crashes, Zed sends a message to a sidecar process which inspects the memory of the crashing editor to create a [minidump](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/getting_started_with_breakpad.md#the-minidump-file-format) file in `~/Library/Logs/Zed` or `$XDG_DATA_HOME/zed/logs`. This minidump can be used to generate backtraces for the stacks of all threads.
When Zed panics or crashes, it sends a message to a sidecar process that inspects the editor's memory and creates a [minidump](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/getting_started_with_breakpad.md#the-minidump-file-format) in `~/Library/Logs/Zed` or `$XDG_DATA_HOME/zed/logs`. You can use this minidump to generate backtraces for all thread stacks.
If you have enabled Zed's telemetry these will be uploaded to us when you restart the app. They end up in a [Slack channel](https://zed-industries.slack.com/archives/C0977J9MA1Y) and in [Sentry](https://zed-dev.sentry.io/issues) (both of which are Zed-staff-only).
If telemetry is enabled, Zed uploads these reports when you restart the app. Reports are sent to a [Slack channel](https://zed-industries.slack.com/archives/C0977J9MA1Y) and to [Sentry](https://zed-dev.sentry.io/issues) (both are Zed-staff-only).
These crash reports contain rich information; but they are hard to read because they don't contain spans or symbol information. You can still work with them locally by downloading sources and an unstripped binary (or separate symbols file) for your Zed release and running:
These crash reports include useful data, but they are hard to read without spans or symbol information. You can still analyze them locally by downloading source and an unstripped binary (or separate symbols file) for your Zed release, then running:
```sh
zstd -d ~/.local/share/zed/<uuid>.dmp -o minidump.dmp
minidump-stackwalk minidump.dmp
```
Alongside the minidump file in your logs dir, there should be a `<uuid>.json` which contains additional metadata like the panic message, span, and system specs.
Alongside the minidump in your logs directory, you should also see a `<uuid>.json` file with metadata such as the panic message, span, and system specs.
## Using a Debugger
If you can reproduce the crash consistently, a debugger can be used to inspect the state of the program at the time of the crash, often providing useful insights into the cause of the crash.
If you can reproduce the crash consistently, use a debugger to inspect program state at the crash point.
You can read more about setting up and using a debugger with Zed, and specifically for debugging crashes [here](./debuggers.md#debugging-panics-and-crashes)
For setup details, see [Using a debugger](./debuggers.md#debugging-panics-and-crashes).
docs/src/development/freebsd.md
+7 -2
View File
@@ -1,6 +1,11 @@
---
title: Building Zed for FreeBSD
description: "Guide to building zed for freebsd for Zed development."
---
# Building Zed for FreeBSD
Note, FreeBSD is not currently a supported platform, and so this is a work-in-progress.
FreeBSD is not currently a supported platform, so this guide is a work in progress.
## Repository
@@ -40,7 +45,7 @@ cargo run -p cli
### WebRTC Notice
Currently, building `webrtc-sys` on FreeBSD fails due to missing upstream support and unavailable prebuilt binaries. As a result, some collaboration features (audio calls and screensharing) that depend on WebRTC are temporarily disabled.
Building `webrtc-sys` on FreeBSD currently fails due to missing upstream support and unavailable prebuilt binaries. As a result, collaboration features that depend on WebRTC (audio calls and screen sharing) are temporarily disabled.
See [Issue #15309: FreeBSD Support] and [Discussion #29550: Unofficial FreeBSD port for Zed] for more.
docs/src/development/glossary.md
+23 -19
View File
@@ -1,8 +1,13 @@
---
title: Zed Development: Glossary
description: "Guide to zed development: glossary for Zed development."
---
# Zed Development: Glossary
These are some terms and structures frequently used throughout the zed codebase.
This page defines terms and structures used throughout the Zed codebase.
This is a best effort list and a work in progress.
It is a best-effort list and a work in progress.
<!--
TBD: Glossary Improvement
@@ -15,33 +20,32 @@ Questions:
## Naming conventions
These are generally true for the whole codebase. Note that Name can be anything
here. An example would be `AnyElement` and `LspStore`.
These are common naming patterns across the codebase. `Name` is a placeholder
for any type name, such as `AnyElement` or `LspStore`.
- `AnyName`: A type erased version of _name_. Think `Box<dyn NameTrait>`.
- `AnyName`: A type-erased version of _name_. Think `Box<dyn NameTrait>`.
- `NameStore`: A wrapper type which abstracts over whether operations are running locally or on a remote.
## GPUI
### State management
- `App`: A singleton which holds the full application state including all the entities. Crucially: `App` is not `Send`, which means that `App` only exists on the thread that created it (which is the main/UI thread, usually). Thus, if you see a `&mut App`, know that you're on UI thread.
- `Context`: A wrapper around the `App` struct with specialized behavior for a specific `Entity`. Think of it as `(&mut App, Entity<V>)`. The specialized behavior is surfaced in the API surface of `Context`. E.g., `App::spawn` takes an `AsyncFnOnce(AsyncApp) -> Ret`, whereas `Context::spawn` takes an `AsyncFnOnce(WeakEntity<V>, AsyncApp) -> Ret`.
- `AsyncApp`: An owned version of `App` for use in async contexts. This type is _still_ not `Send` (so `AsyncApp` = you're on the main thread) and any use of it may be fallible (to account for the fact that the `App` might've been terminated by the time this closure runs).
The convenience of `AsyncApp` lies in the fact that you usually interface with `App` via `&mut App`, which would be inconvenient to use with async closures; `AsyncApp` is owned, so you can use it in async closures with no sweat.
- `AppContext` A trait which abstracts over `App`, `AsyncApp` & `Context` and their Test versions.
- `Task`: A future running or scheduled to run on the background or foreground
executor. In contradiction to regular Futures Tasks do not need `.await` to start running. You do need to await them to get the result of the task.
- `App`: A singleton that holds full application state, including all entities. `App` is not `Send`, so it exists only on the thread that created it (usually the main/UI thread). If you see `&mut App`, you are on the UI thread.
- `Context`: A wrapper around `App` with specialized behavior for a specific `Entity`. You can think of it as `(&mut App, Entity<V>)`. For example, `App::spawn` takes `AsyncFnOnce(AsyncApp) -> Ret`, while `Context::spawn` takes `AsyncFnOnce(WeakEntity<V>, AsyncApp) -> Ret`.
- `AsyncApp`: An owned version of `App` for async contexts. It is still not `Send`, so it still runs on the main thread, and operations may fail if the `App` has already terminated.
`AsyncApp` exists because `App` is usually accessed as `&mut App`, which is awkward to hold across async boundaries.
- `AppContext`: A trait that abstracts over `App`, `AsyncApp`, `Context`, and their test variants.
- `Task`: A future running (or scheduled to run) on a background or foreground executor. Unlike regular futures, tasks do not need `.await` to start. You still need to await them to read their result.
- `Executor`: Used to spawn tasks that run either on the foreground or background thread. Try to run the tasks on the background thread.
- `BackgroundExecutor`: A threadpool running `Task`s.
- `ForegroundExecutor`: The main thread running `Task`s.
- `Entity`: A strong, well-typed reference to a struct which is managed by gpui. Effectively a pointer/map key into the `App::EntityMap`.
- `WeakEntity`: A runtime checked reference to an `Entity` which may no longer exist. Similar to [`std::rc::Weak`](https://doc.rust-lang.org/std/rc/struct.Weak.html).
- `Global`: A singleton type which has only one value, that is stored in the `App`.
- `Event`: A datatype which can be send by an `Entity` to subscribers
- `Event`: A data type that can be sent by an `Entity` to subscribers.
- `Action`: An event that represents a user's keyboard input that can be handled by listeners
Example: `file finder: toggle`
- `Observing`: reacting entities notifying they've changed
- `Observing`: Reacting to notifications that entities have changed.
- `Subscription`: An event handler that is used to react to the changes of state in the application.
1. Emitted event handling
2. Observing `{new,release,on notify}` of an entity
@@ -71,14 +75,14 @@ h_flex()
## Zed UI
- `Window`: A struct in zed representing a zed window in your desktop environment (see image below). There can be multiple if you have multiple zed instances open. Mostly passed around for rendering.
- `Window`: A struct representing a Zed window in your desktop environment (see image below). You can have multiple windows open. This is mostly passed around for rendering.
- `Modal`: A UI element that floats on top of the rest of the UI
- `Picker`: A struct representing a list of items floating on top of the UI (Modal). You can select an item and confirm. What happens on select or confirm is determined by the picker's delegate. (The 'Modal' in the image below is a picker.)
- `PickerDelegate`: A trait used to specialize behavior for a `Picker`. The `Picker` stores the `PickerDelegate` in the field delegate.
- `Center`: The middle of the zed window, the center is split into multiple `Pane`s. In the codebase this is a field on the `Workspace` struct. (see image below).
- `Pane`: An area in the `Center` where we can place items, such as an editor, multi-buffer or terminal (see image below).
- `Panel`: An `Entity` implementing the `Panel` trait. These can be placed in a `Dock`. In the image below we see the: `ProjectPanel` in the left dock, the `DebugPanel` in the bottom dock, and `AgentPanel` in the right dock. Note `Editor` does not implement `Panel` and hence is not a `Panel`.
- `Dock`: A UI element similar to a `Pane` which can be opened and hidden. There can be up to 3 docks open at a time, left right and below the center. A dock contains one or more `Panel`s not `Pane`s. (see image).
- `Panel`: An `Entity` implementing the `Panel` trait. Panels can be placed in a `Dock`. In the image below: `ProjectPanel` is in the left dock, `DebugPanel` is in the bottom dock, and `AgentPanel` is in the right dock. `Editor` does not implement `Panel`.
- `Dock`: A UI element similar to a `Pane` that can be opened and hidden. Up to three docks can be open at once: left, right, and bottom. A dock contains one or more `Panel`s, not `Pane`s.
<img width="1921" height="1080" alt="Screenshot for the Pane and Dock features" src="https://github.com/user-attachments/assets/2cb1170e-2850-450d-89bb-73622b5d07b2" />
@@ -93,7 +97,7 @@ h_flex()
## Editor
- `Editor`: _The_ text editor, nearly everything in zed is an `Editor`, even single line inputs. Each pane in the image above contains one or more `Editor` instances.
- `Editor`: The text editor type. Most editable surfaces in Zed are an `Editor`, including single-line inputs. Each pane in the image above contains one or more `Editor` instances.
- `Workspace`: The root of the window
- `Entry`: A file, dir, pending dir or unloaded dir.
- `Buffer`: The in-memory representation of a 'file' together with relevant data such as syntax trees, git status and diagnostics.
@@ -108,7 +112,7 @@ h_flex()
## Debugger
- `DapStore`: Is an entity that manages debugger sessions
- `debugger::Session`: Is an entity that manages the lifecycle of a debug session and communication with DAPS
- `debugger::Session`: An entity that manages the lifecycle of a debug session and communication with DAPs.
- `BreakpointStore`: Is an entity that manages breakpoints states in local and remote instances of Zed
- `DebugSession`: Manages a debug session's UI and running state
- `RunningState`: Directly manages all the views of a debug session
docs/src/development/linux.md
+26 -23
View File
@@ -1,8 +1,13 @@
---
title: Building Zed for Linux
description: "Guide to building zed for linux for Zed development."
---
# Building Zed for Linux
## Repository
Clone down the [Zed repository](https://github.com/zed-industries/zed).
Clone the [Zed repository](https://github.com/zed-industries/zed).
## Dependencies
@@ -18,9 +23,9 @@ Clone down the [Zed repository](https://github.com/zed-industries/zed).
### Linkers {#linker}
On Linux, Rust's default linker is [LLVM's `lld`](https://blog.rust-lang.org/2025/09/18/Rust-1.90.0/). Alternative linkers, especially [Wild](https://github.com/davidlattimore/wild) and [Mold](https://github.com/rui314/mold) can significantly improve clean and incremental build time.
On Linux, Rust's default linker is [LLVM's `lld`](https://blog.rust-lang.org/2025/09/18/Rust-1.90.0/). Alternative linkers, especially [Wild](https://github.com/davidlattimore/wild) and [Mold](https://github.com/rui314/mold), can improve clean and incremental build times.
At present Zed uses Mold in CI because it's more mature. For local development Wild is recommended because it's 5-20% faster than Mold.
Zed currently uses Mold in CI because it is more mature. For local development, Wild is recommended because it is typically 5-20% faster than Mold.
These linkers can be installed with `script/install-mold` and `script/install-wild`.
@@ -73,7 +78,7 @@ You can install a local build on your machine with:
./script/install-linux
```
This will build zed and the cli in release mode and make them available at `~/.local/bin/zed`, installing .desktop files to `~/.local/share`.
This builds `zed` and the `cli` in release mode, installs the binary at `~/.local/bin/zed`, and installs `.desktop` files to `~/.local/share`.
> **_Note_**: If you encounter linker errors similar to the following:
>
@@ -92,12 +97,12 @@ This will build zed and the cli in release mode and make them available at `~/.l
> ```
>
> **Cause**:
> this is caused by known bugs in aws-lc-rs(doesn't support GCC >= 14): [FIPS fails to build with GCC >= 14](https://github.com/aws/aws-lc-rs/issues/569)
> This is caused by known bugs in aws-lc-rs (no GCC >= 14 support): [FIPS fails to build with GCC >= 14](https://github.com/aws/aws-lc-rs/issues/569)
> & [GCC-14 - build failure for FIPS module](https://github.com/aws/aws-lc/issues/2010)
>
> You can refer to [linux: Linker error for remote_server when using script/install-linux](https://github.com/zed-industries/zed/issues/24880) for more information.
>
> **Workarounds**:
> **Workaround**:
> Set the remote server target to `x86_64-unknown-linux-gnu` like so `export REMOTE_SERVER_TARGET=x86_64-unknown-linux-gnu; script/install-linux`
## Wayland & X11
@@ -106,7 +111,7 @@ Zed supports both X11 and Wayland. By default, we pick whichever we can find at
## Notes for packaging Zed
Thank you for taking on the task of packaging Zed!
This section is for distribution maintainers packaging Zed.
### Technical requirements
@@ -122,16 +127,14 @@ Zed has two main binaries:
### Other things to note
At Zed, our priority has been to move fast and bring the latest technology to our users. We've long been frustrated at having software that is slow, out of date, or hard to configure, and so we've built our editor to those tastes.
Zed moves quickly, and distribution maintainers often have different constraints and priorities. The points below describe current trade-offs:
However, we realize that many distros have other priorities. We want to work with everyone to bring Zed to their favorite platforms. But there is a long way to go:
- Zed is a fast-moving early-phase project. We typically release 2-3 builds per week to fix user-reported issues and release major features.
- Zed is a fast-moving project. We typically publish 2-3 builds per week to address reported issues and ship larger changes.
- There are a couple of other `zed` binaries that may be present on Linux systems ([1](https://openzfs.github.io/openzfs-docs/man/v2.2/8/zed.8.html), [2](https://zed.brimdata.io/docs/commands/zed)). If you want to rename our CLI binary because of these issues, we suggest `zedit`, `zeditor`, or `zed-cli`.
- Zed automatically installs the correct version of common developer tools in the same way as rustup/rbenv/pyenv, etc. We understand this is contentious, [see here](https://github.com/zed-industries/zed/issues/12589).
- We allow users to install extensions locally and from [zed-industries/extensions](https://github.com/zed-industries/extensions). These extensions may install further tooling as needed, such as language servers. In the long run, we would like to make this safer, [see here](https://github.com/zed-industries/zed/issues/12358).
- Zed automatically installs versions of common developer tools, similar to rustup/rbenv/pyenv. This behavior is discussed [here](https://github.com/zed-industries/zed/issues/12589).
- Users can install extensions locally and from [zed-industries/extensions](https://github.com/zed-industries/extensions). Extensions may install additional tools such as language servers. Planned safety improvements are tracked [here](https://github.com/zed-industries/zed/issues/12358).
- Zed connects to several online services by default (AI, telemetry, collaboration). AI and our telemetry can be disabled by your users with their zed settings or by patching our [default settings file](https://github.com/zed-industries/zed/blob/main/assets/settings/default.json).
- As a result of the above issues, zed currently does not play nice with sandboxes, [see here](https://github.com/zed-industries/zed/pull/12006#issuecomment-2130421220)
- Because of the points above, Zed currently does not work well with sandboxes. See [this discussion](https://github.com/zed-industries/zed/pull/12006#issuecomment-2130421220).
## Flatpak
@@ -163,21 +166,21 @@ When this zed instance is exited, terminal output will include a command to run
## Perf recording
How to get a flamegraph with resolved symbols from a running zed instance. Use
when zed is using a lot of CPU. Not useful for hangs.
How to get a flamegraph with resolved symbols from a running Zed instance.
Use this when Zed is using a lot of CPU. It is not useful for hangs.
### During the incident
- Find the PID (process ID) using:
`ps -eo size,pid,comm | grep zed | sort | head -n 1 | cut -d ' ' -f 2`
Or find the pid of the command zed-editor with the most ram usage in something
Or find the PID of `zed-editor` with the highest RAM usage in something
like htop/btop/top.
- Install perf:
On Ubuntu (derivatives) run `sudo apt install linux-tools`.
- Perf Record:
run `sudo perf record -p <pid you just found>`, wait a few seconds to gather data then press Ctrl+C. You should now have a perf.data file
- Perf record:
Run `sudo perf record -p <pid you just found>`, wait a few seconds to gather data, then press Ctrl+C. You should now have a `perf.data` file.
- Make the output file user owned:
run `sudo chown $USER:$USER perf.data`
@@ -185,7 +188,7 @@ when zed is using a lot of CPU. Not useful for hangs.
- Get build info:
Run zed again and type `zed: about` in the command pallet to get the exact commit.
The `data.perf` file can be send to zed together with the exact commit.
The `perf.data` file can be sent to Zed together with the exact commit.
### Later
@@ -193,7 +196,7 @@ This can be done by Zed staff.
- Build Zed with symbols:
Check out the commit found previously and modify `Cargo.toml`.
Apply the following diff then make a release build.
Apply the following diff, then make a release build.
```diff
[profile.release]
@@ -201,8 +204,8 @@ This can be done by Zed staff.
+debug = "full"
```
- Add the symbols to perf database:
`pref buildid-cache -v -a <path to release zed binary>`
- Add the symbols to the perf database:
`perf buildid-cache -v -a <path to release zed binary>`
- Resolve the symbols from the db:
`perf inject -i perf.data -o perf_with_symbols.data`
docs/src/development/macos.md
+12 -10
View File
@@ -1,16 +1,21 @@
---
title: Building Zed for macOS
description: "Guide to building zed for macos for Zed development."
---
# Building Zed for macOS
## Repository
Clone down the [Zed repository](https://github.com/zed-industries/zed).
Clone the [Zed repository](https://github.com/zed-industries/zed).
## Dependencies
- Install [rustup](https://www.rust-lang.org/tools/install)
- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store, or from the [Apple Developer](https://developer.apple.com/download/all/) website. Note this requires a developer account.
- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store or from the [Apple Developer](https://developer.apple.com/download/all/) website. The Apple Developer download requires a developer account.
> Ensure you launch Xcode after installing, and install the macOS components, which is the default option.
> Launch Xcode after installation and install the macOS components (the default option).
- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
@@ -138,7 +143,7 @@ Caused by:
cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
```
This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
This file is part of Xcode. Make sure the Xcode command line tools are installed and the path is set correctly:
```sh
xcode-select --install
@@ -169,21 +174,18 @@ This error seems to be caused by OS resource constraints. Installing and running
### Avoiding continual rebuilds
If you are finding that Zed is continually rebuilding root crates, it may be because
you are pointing your development Zed at the codebase itself.
If Zed continually rebuilds root crates, you may be opening the Zed codebase itself in your development build.
This causes problems because `cargo run` exports a bunch of environment
variables which are picked up by the `rust-analyzer` that runs in the development
build of Zed. These environment variables are in turn passed to `cargo check`, which
invalidates the build cache of some of the crates we depend on.
You can easily avoid running the built binary on the checked-out Zed codebase using `cargo run
~/path/to/other/project` to ensure that you don't hit this.
To avoid this, run the built binary against a different project, for example `cargo run ~/path/to/other/project`.
### Speeding up verification
If you are building Zed a lot, you may find that macOS continually verifies new
builds which can add a few seconds to your iteration cycles.
If you build Zed frequently, macOS may keep verifying new builds, which can add a few seconds to each iteration.
To fix this, you can:
docs/src/development/release-notes.md
+8 -3
View File
@@ -1,3 +1,8 @@
---
title: Release Notes
description: "Guide to release notes for Zed development."
---
# Release Notes
Whenever you open a pull request, the body is automatically populated based on this [pull request template](https://github.com/zed-industries/zed/blob/main/.github/pull_request_template.md).
@@ -10,9 +15,9 @@ Release Notes:
- N/A _or_ Added/Fixed/Improved ...
```
On Wednesdays, we run a [`get-preview-channel-changes`](https://github.com/zed-industries/zed/blob/main/script/get-preview-channel-changes) script that scrapes `Release Notes` lines from pull requests landing in preview, as documented in our [Release](https://zed.dev/docs/development/release-notes) docs.
On Wednesdays, we run [`get-preview-channel-changes`](https://github.com/zed-industries/zed/blob/main/script/get-preview-channel-changes), which collects `Release Notes` lines from pull requests landing in preview, as described in the [Release](https://zed.dev/docs/development/release-notes) docs.
The script outputs everything below the `Release Notes` line, including additional data such as the pull request author (if not a Zed team member) and a link to the pull request.
The script outputs everything below the `Release Notes` line, including metadata such as the pull request author (if they are not a Zed team member) and a link to the pull request.
If you use `N/A`, the script skips your pull request entirely.
## Guidelines for crafting your `Release Notes` line(s)
@@ -26,4 +31,4 @@ If you use `N/A`, the script skips your pull request entirely.
Don't make the user dig into docs or the pull request to find this information (although it should be included in docs as well).
- For pull requests that are reverts:
- If the item being reverted **has already been shipped**, include a `Release Notes` line explaining why we reverted, as this is a breaking change.
- If the item being reverted **hasn't been shipped**, edit the original PR's `Release Notes` line to be `N/A`; otherwise, it will be included and the compiler of the release notes may not know to skip it, leading to a potentially-awkward situation where we are stating we shipped something we actually didn't.
- If the item being reverted **hasn't been shipped**, edit the original PR's `Release Notes` line to `N/A`; otherwise, it will still be included and the release notes compiler may not know to skip it.
docs/src/development/windows.md
+24 -19
View File
@@ -1,22 +1,27 @@
---
title: Building Zed for Windows
description: "Guide to building zed for windows for Zed development."
---
# Building Zed for Windows
> The following commands may be executed in any shell.
## Repository
Clone down the [Zed repository](https://github.com/zed-industries/zed).
Clone the [Zed repository](https://github.com/zed-industries/zed).
## Dependencies
- Install [rustup](https://www.rust-lang.org/tools/install)
- Install either [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the optional components `MSVC v*** - VS YYYY C++ x64/x86 build tools` and `MSVC v*** - VS YYYY C++ x64/x86 Spectre-mitigated libs (latest)` (`v***` is your VS version and `YYYY` is year when your VS was released. Pay attention to the architecture and change it to yours if needed.)
- Or, if you prefer to have a slimmer installer of only the MSVC compiler tools, you can install the [build tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (+libs as above) and the "Desktop development with C++" workload.
But beware this installation is not automatically picked up by rustup. You must initialize your environment variables by first launching the "developer" shell (cmd/powershell) this installation places in the start menu or in Windows Terminal and then compile.
- Install Windows 11 or 10 SDK depending on your system, but ensure that at least `Windows 10 SDK version 2104 (10.0.20348.0)` is installed on your machine. You can download it from the [Windows SDK Archive](https://developer.microsoft.com/windows/downloads/windows-sdk/)
- Install either [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the optional components `MSVC v*** - VS YYYY C++ x64/x86 build tools` and `MSVC v*** - VS YYYY C++ x64/x86 Spectre-mitigated libs (latest)` (`v***` is your VS version and `YYYY` is the release year. Adjust architecture as needed).
- Or, if you prefer a slimmer installation, install only the [Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (plus the libs above) and the "Desktop development with C++" workload.
This setup is not picked up automatically by rustup. Before compiling, initialize environment variables by launching the developer shell (cmd/PowerShell) installed in the Start menu or Windows Terminal.
- Install the Windows 11 or 10 SDK for your system, and make sure at least `Windows 10 SDK version 2104 (10.0.20348.0)` is installed. You can download it from the [Windows SDK Archive](https://developer.microsoft.com/windows/downloads/windows-sdk/).
- Install [CMake](https://cmake.org/download) (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/)). Or you can install it through Visual Studio Installer, then manually add the `bin` directory to your `PATH`, for example: `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`.
If you can't compile Zed, make sure that you have at least the following components installed in case of a Visual Studio installation:
If you cannot compile Zed, make sure a Visual Studio installation includes at least the following components:
```json [settings]
{
@@ -34,7 +39,7 @@ If you can't compile Zed, make sure that you have at least the following compone
}
```
Or if in case of just Build Tools, the following components:
If you are using Build Tools only, make sure these components are installed:
```json [settings]
{
@@ -60,7 +65,7 @@ Or if in case of just Build Tools, the following components:
}
```
The list can be obtained as follows:
You can export this component list as follows:
- Open the Visual Studio Installer
- Click on `More` in the `Installed` tab
@@ -68,7 +73,7 @@ The list can be obtained as follows:
### Notes
You should modify the `pg_hba.conf` file in the `data` directory to use `trust` instead of `scram-sha-256` for the `host` method. Otherwise, the connection will fail with the error `password authentication failed`. The `pg_hba.conf` file typically locates at `C:\Program Files\PostgreSQL\17\data\pg_hba.conf`. After the modification, the file should look like this:
Update `pg_hba.conf` in the `data` directory to use `trust` instead of `scram-sha-256` for the `host` method. Otherwise, the connection fails with `password authentication failed`. The file is typically at `C:\Program Files\PostgreSQL\17\data\pg_hba.conf`. After the change, it should look like this:
```conf
# IPv4 local connections:
@@ -77,14 +82,14 @@ host all all 127.0.0.1/32 trust
host all all ::1/128 trust
```
Also, if you are using a non-latin Windows version, you must modify the`lc_messages` parameter in the `postgresql.conf` file in the `data` directory to `English_United States.1252` (or whatever UTF8-compatible encoding you have). Otherwise, the database will panic. The `postgresql.conf` file should look like this:
If you are using a non-Latin Windows locale, set the `lc_messages` parameter in `postgresql.conf` (in the `data` directory) to `English_United States.1252` (or another UTF-8-compatible encoding available on your system). Otherwise, the database may panic. The file should look like this:
```conf
# lc_messages = 'Chinese (Simplified)_China.936' # locale for system error message strings
lc_messages = 'English_United States.1252'
```
After this, you should restart the `postgresql` service. Press the `win` key + `R` to launch the `Run` window. Type the `services.msc` and hit the `OK` button to open the Services Manager. Then, find the `postgresql-x64-XX` service, right-click on it, and select `Restart`.
After this, restart the `postgresql` service. Press `Win`+`R` to open the Run dialog, enter `services.msc`, and select **OK**. In Services Manager, find `postgresql-x64-XX`, right-click it, and select **Restart**.
## Building from source
@@ -122,9 +127,9 @@ Please refer to [MSYS2 documentation](https://www.msys2.org/docs/ides-editors/#z
If you set the `RUSTFLAGS` env var, it will override the `rustflags` settings in `.cargo/config.toml` which is required to properly build Zed.
Since these settings can vary from time to time, the build errors you receive may vary from linker errors, to other stranger errors.
Because these settings change over time, the resulting build errors may vary from linker failures to other hard-to-diagnose errors.
If you'd like to add extra rust flags, you may do 1 of the following in `.cargo/config.toml`:
If you need extra Rust flags, use one of the following approaches in `.cargo/config.toml`:
Add your flags in the build section
@@ -145,7 +150,7 @@ rustflags = [
]
```
Or, you can create a new `.cargo/config.toml` in the same folder as the Zed repo (see below). This is particularly useful if you are doing CI builds since you don't have to edit the original `.cargo/config.toml`.
Or, create a new `.cargo/config.toml` in the parent directory of the Zed repo (see below). This is useful in CI because you do not need to edit the repo's original `.cargo/config.toml`.
```
upper_dir
@@ -200,7 +205,7 @@ Caused by:
warning: build failed, waiting for other jobs to finish...
```
In order to fix this issue, you can manually set the `ZED_RC_TOOLKIT_PATH` environment variable to the RC toolkit path. Usually, you can set it to:
To fix this issue, manually set the `ZED_RC_TOOLKIT_PATH` environment variable to the RC toolkit path. Usually this is:
`C:\Program Files (x86)\Windows Kits\10\bin\<SDK_version>\x64`.
See this [issue](https://github.com/zed-industries/zed/issues/18393) for more information.
@@ -222,7 +227,7 @@ Caused by:
path too long: 'C:/Users/runneradmin/.cargo/git/checkouts/python-environment-tools-903993894b37a7d2/ffcbf3f/crates/pet-conda/tests/unix/conda_env_without_manager_but_found_in_history/some_other_location/conda_install/conda-meta/python-fastjsonschema-2.16.2-py310hca03da5_0.json'; class=Filesystem (30)
```
In order to solve this, you can enable longpath support for git and Windows.
To fix this, enable long-path support for both Git and Windows.
For git: `git config --system core.longpaths true`
@@ -234,13 +239,13 @@ New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name
For more information on this, please see [win32 docs](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell)
(note that you will need to restart your system after enabling longpath support)
(You need to restart your system after enabling long-path support.)
### Graphics issues
#### Zed fails to launch
Currently, Zed uses Vulkan as its graphics API on Windows. However, Vulkan isn't always the most reliable on Windows, so if Zed fails to launch, it's likely a Vulkan-related issue.
Zed currently uses Vulkan as its graphics API on Windows. If Zed fails to launch, Vulkan is a common cause.
You can check the Zed log at:
`C:\Users\YOU\AppData\Local\Zed\logs\Zed.log`
@@ -252,6 +257,6 @@ If you see messages like:
- `GPU Crashed`
- `ERROR_SURFACE_LOST_KHR`
Then Vulkan might not be working properly on your system. In most cases, updating your GPU drivers may help resolve this.
Vulkan may not be working correctly on your system. Updating GPU drivers often resolves this.
If there's nothing Vulkan-related in the logs and you happen to have Bandicam installed, try uninstalling it. Zed is currently not compatible with Bandicam.