1---
2title: Developing Zed
3description: "Guide to building and developing Zed from source."
4---
5
6# Developing Zed
7
8See the platform-specific instructions for building Zed from source:
9
10- [macOS](./development/macos.md)
11- [Linux](./development/linux.md)
12- [Windows](./development/windows.md)
13
14## Keychain access
15
16Zed stores secrets in the system keychain.
17
18However, when running a development build of Zed on macOS (and perhaps other
19platforms) trying to access the keychain results in a lot of keychain prompts
20that require entering your password over and over.
21
22On macOS this is caused by the development build not having a stable identity.
23Even if you choose the "Always Allow" option, the OS will still prompt you for
24your password again the next time something changes in the binary.
25
26This quickly becomes annoying and impedes development speed.
27
28That is why, by default, when running a development build of Zed an alternative
29credential provider is used to bypass the system keychain.
30
31> **Note:** This is **only** the case for development builds. For all non-development
32> release channels the system keychain is always used.
33
34If you need to test something out using the real system keychain in a
35development build, run Zed with the following environment variable set:
36
37```
38ZED_DEVELOPMENT_USE_KEYCHAIN=1
39```
40
41## Performance Measurements
42
43Zed includes a frame time measurement system that can be used to profile how long it takes to render each frame. This is particularly useful when comparing rendering performance between different versions or when optimizing frame rendering code.
44
45### Using ZED_MEASUREMENTS
46
47To enable performance measurements, set the `ZED_MEASUREMENTS` environment variable:
48
49```sh
50export ZED_MEASUREMENTS=1
51```
52
53When enabled, Zed will print frame rendering timing information to stderr, showing how long each frame takes to render.
54
55### Performance Comparison Workflow
56
57Here's a typical workflow for comparing frame rendering performance between different versions:
58
591. **Enable measurements:**
60
61 ```sh
62 export ZED_MEASUREMENTS=1
63 ```
64
652. **Test the first version:**
66
67 - Checkout the commit you want to measure
68 - Run Zed in release mode and use it for 5-10 seconds: `cargo run --release &> version-a`
69
703. **Test the second version:**
71
72 - Checkout another commit you want to compare
73 - Run Zed in release mode and use it for 5-10 seconds: `cargo run --release &> version-b`
74
754. **Generate comparison:**
76
77 ```sh
78 script/histogram version-a version-b
79 ```
80
81The `script/histogram` tool can accept as many measurement files as you like and will generate a histogram visualization comparing the frame rendering performance data between the provided versions.
82
83### Using `util_macros::perf`
84
85For benchmarking unit tests, annotate them with the `#[perf]` attribute from the `util_macros` crate. Then run `cargo
86perf-test -p $CRATE` to benchmark them. See the rustdoc documentation on `crates/util_macros` and `tooling/perf` for
87in-depth examples and explanations.
88
89## ETW Profiling on Windows
90
91> **Changed in Preview (v0.225).** See [release notes](/releases#0.225).
92
93Zed supports Event Tracing for Windows (ETW) to capture detailed performance data. You can record CPU, GPU, disk I/O, and file I/O activity, with optional heap allocation tracking.
94
95### Recording a trace
96
97Open the command palette and run:
98
99- **`etw_tracing: Record Etw Trace`** — Records CPU, GPU, and I/O activity
100- **`etw_tracing: Record Etw Trace With Heap Tracing`** — Includes heap allocation data for the Zed process
101
102Zed prompts you to choose a save location for the `.etl` trace file.
103
104### Saving or canceling
105
106While recording:
107
108- **`etw_tracing: Save Etw Trace`** — Stops recording and saves the trace to disk
109- **`etw_tracing: Cancel Etw Trace`** — Stops recording without saving
110
111Zed buffers trace data in memory. Recordings automatically save after 60 seconds if you don't manually stop them.
112
113### Analyzing traces
114
115Open `.etl` files with [Windows Performance Analyzer](https://learn.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer) to inspect CPU stacks, GPU usage, disk I/O patterns, and heap allocations.
116
117**Note for existing keybindings**: The `etw_tracing::StopEtwTrace` action was renamed to `etw_tracing::SaveEtwTrace`. Update any custom keybindings.
118
119## Contributor links
120
121- [CONTRIBUTING.md](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md)
122- [Debugging Crashes](./development/debugging-crashes.md)
123- [Code of Conduct](https://zed.dev/code-of-conduct)
124- [Zed Contributor License](https://zed.dev/cla)