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
91Zed supports performance profiling with Event Tracing for Windows (ETW) to capture detailed performance data, including CPU, GPU, memory, disk, and file I/O activity. Data is saved to an `.etl` file, which can be opened in standard profiling tools for analysis.
92
93ETW recordings may contain personally identifiable or security-sensitive information, such as paths to files and registry keys accessed, as well as process names. Please keep this in mind when sharing traces with others.
94
95### Recording a trace
96
97Open the command palette and run one of the following:
98
99- `zed: record etw trace`: records CPU, GPU, memory, and I/O activity
100- `zed: record etw trace with heap tracing`: includes heap allocation data for the Zed process
101
102Zed will prompt you to choose a save location for the `.etl` file, then request administrator permission. Once granted, recording will begin.
103
104### Saving or canceling
105
106While a trace is recording, open the command palette and run one of the following:
107
108- `zed: save etw trace`: stops recording and saves the trace to disk
109- `zed: cancel etw trace`: stops recording without saving
110
111Recordings automatically save after 60 seconds if not stopped manually.
112
113## Contributor links
114
115- [CONTRIBUTING.md](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md)
116- [Debugging Crashes](./development/debugging-crashes.md)
117- [Code of Conduct](https://zed.dev/code-of-conduct)
118- [Zed Contributor License](https://zed.dev/cla)