ZIm/docs/src/developing_zed__building_zed.md

Building Zed

🚧 TODO:

• Remove ZI-specific things
• Rework any steps that currently require a ZI-specific account

How to build Zed from source for the first time.

Prerequisites

🚧 TODO 🚧 Update for open source

• Be added to the GitHub organization
• Be added to the Vercel team
• Create a Personal Access Token on Github
  • 🚧 TODO 🚧 What permissions are required?
  • 🚧 TODO 🚧 What changes when repo isn't private?
  • Go to https://github.com/settings/tokens and Generate new token
  • GitHub currently provides two kinds of tokens:
    • Classic Tokens, where only repo (Full control of private repositories) OAuth scope has to be selected Unfortunately, unselecting repo scope and selecting every its inner scope instead does not allow the token users to read from private repositories
    • (not applicable) Fine-grained Tokens, at the moment of writing, did not allow any kind of access of non-owned private repos
  • Keep the token in the browser tab/editor for the next two steps

Dependencies

• Install Rust

• Install the GitHub CLI, Livekit & Foreman

brew install gh
brew install livekit
brew install foreman

• Install Xcode from the macOS App Store

• Install Xcode command line tools

xcode-select --install

• If xcode-select --print-path prints /Library/Developer/CommandLineTools… run sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer.

• Install Postgres

• Install the wasm toolchain

rustup target add wasm32-wasi

Building Zed from Source

1. Clone the zed repo

gh repo clone zed-industries/zed

1. (Optional but recommended) Add your GITHUB_TOKEN to your .zshrc or .bashrc like this: export GITHUB_TOKEN=yourGithubAPIToken
2. (🚧 TODO 🚧 - Will this be relevant for open source?) Ensure the Zed.dev website is checked out in a sibling directory and install its dependencies:

cd ..
git clone https://github.com/zed-industries/zed.dev
cd zed.dev && npm install
pnpm install -g vercel

1. (🚧 TODO 🚧 - Will this be relevant for open source?) Link your zed.dev project to Vercel

• vercel link
• Select the zed-industries team. If you don't have this get someone on the team to add you to it.
• Select the zed.dev project

1. (🚧 TODO 🚧 - Will this be relevant for open source?) Run vercel pull to pull down the environment variables and project info from Vercel
2. Open Postgres.app
3. From ./path/to/zed/ run GITHUB_TOKEN={yourGithubAPIToken} script/bootstrap

• You don't need to include the GITHUB_TOKEN if you exported it above.
• Consider removing the token (if it's fine for you to recreate such tokens during occasional migrations) or store this token somewhere safe (like your Zed 1Password vault).

1. To run the Zed app:
   • If you are working on zed:
     • cargo run
   • If you are just using the latest version, but not working on zed:
     • cargo run --release
   • If you need to run the collaboration server locally:
     • script/zed-local

Troubleshooting

error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)

• Try xcode-select --switch /Applications/Xcode.app/Contents/Developer

xcrun: error: unable to find utility "metal", not a developer tool or in PATH

script/bootstrap

Error: Cannot install in Homebrew on ARM processor in Intel default prefix (/usr/local)!
Please create a new installation in /opt/homebrew using one of the
"Alternative Installs" from:
https://docs.brew.sh/Installation

• In that case try /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

• If Homebrew is not in your PATH:

  • Replace {username} with your home folder name (usually your login name)
  • echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/{username}/.zprofile
  • eval "$(/opt/homebrew/bin/brew shellenv)"

seeding database...
thread 'main' panicked at 'failed to deserialize github user from 'https://api.github.com/orgs/zed-industries/teams/staff/members': reqwest::Error { kind: Decode, source: Error("invalid type: map, expected a sequence", line: 1, column: 0) }', crates/collab/src/bin/seed.rs:111:10

Wrong permissions for GITHUB_TOKEN token used, the token needs to be able to read from private repos. For Classic GitHub Tokens, that required OAuth scope repo (seacrh the scope name above for more details)

Same command

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

If you experience errors that mention some dependency is using unstable features

Try cargo clean and cargo build,