Developing Zed

See the platform-specific instructions for building Zed from source:

Keychain access

Zed stores secrets in the system keychain.

However, when running a development build of Zed on macOS (and perhaps other platforms) trying to access the keychain results in a lot of keychain prompts that require entering your password over and over.

On macOS this is caused by the development build not having a stable identity. Even if you choose the "Always Allow" option, the OS will still prompt you for your password again the next time something changes in the binary.

This quickly becomes annoying and impedes development speed.

That is why, by default, when running a development build of Zed an alternative credential provider is used to bypass the system keychain.

Note: This is only the case for development builds. For all non-development release channels the system keychain is always used.

If you need to test something out using the real system keychain in a development build, run Zed with the following environment variable set:

ZED_DEVELOPMENT_USE_KEYCHAIN=1

Performance Measurements

Zed 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.

Using ZED_MEASUREMENTS

To enable performance measurements, set the ZED_MEASUREMENTS environment variable:

export ZED_MEASUREMENTS=1

When enabled, Zed will print frame rendering timing information to stderr, showing how long each frame takes to render.

Performance Comparison Workflow

Here's a typical workflow for comparing frame rendering performance between different versions:

Enable measurements:
```
export ZED_MEASUREMENTS=1
```
Test the first version:
- Checkout the commit you want to measure
- Run Zed in release mode and use it for 5-10 seconds: cargo run --release &> version-a
Test the second version:
- Checkout another commit you want to compare
- Run Zed in release mode and use it for 5-10 seconds: cargo run --release &> version-b
Generate comparison:
```
script/histogram version-a version-b
```

The 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.

Using `util_macros::perf`

For benchmarking unit tests, annotate them with the #[perf] attribute from the util_macros crate. Then run cargo perf-test -p $CRATE to benchmark them. See the rustdoc documentation on crates/util_macros and tooling/perf for in-depth examples and explanations.

ETW Profiling on Windows

Changed in Preview (v0.225). See release notes.

Zed 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.

Recording a trace

Open the command palette and run:

etw_tracing: Record Etw Trace — Records CPU, GPU, and I/O activity
etw_tracing: Record Etw Trace With Heap Tracing — Includes heap allocation data for the Zed process

Zed prompts you to choose a save location for the .etl trace file.

Saving or canceling

While recording:

etw_tracing: Save Etw Trace — Stops recording and saves the trace to disk
etw_tracing: Cancel Etw Trace — Stops recording without saving

Zed buffers trace data in memory. Recordings automatically save after 60 seconds if you don't manually stop them.

Analyzing traces

Open .etl files with Windows Performance Analyzer to inspect CPU stacks, GPU usage, disk I/O patterns, and heap allocations.

Note for existing keybindings: The etw_tracing::StopEtwTrace action was renamed to etw_tracing::SaveEtwTrace. Update any custom keybindings.