zed-industries/zed
1
1
Fork 0
mirror of https://github.com/zed-industries/zed.git synced 2024-12-27 00:12:27 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update Readme & building Zed doc (#4094)

Browse Source 
This PR cleans out the README.md, moves most relevant build details to
`docs/src/developing_zed__building_zed.md`.

It also restructures and cleans up the Building Zed doc.

There are a number of outstanding TODOs to have this doc be ready for
external folks to be able to build Zed.

Release Notes:

- N/A
This commit is contained in:
Nate Butler 2024-01-17 13:23:09 -05:00 committed by GitHub
commit c4ba5ef03f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 107 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
README.md
View File

@ -1,110 +1,27 @@
# 🚧 TODO 🚧
[ ] Add intro
[ ] Add link to contributing guide
[ ] Add barebones running zed from source instructions
[ ] Link out to further dev docs
# Zed
[![CI](https://github.com/zed-industries/zed/actions/workflows/ci.yml/badge.svg)](https://github.com/zed-industries/zed/actions/workflows/ci.yml)
Welcome to Zed, a lightning-fast, collaborative code editor that makes your dreams come true.
Welcome to Zed, a high-performance, multiplayer code editor from the creators of [Atom]https://github.com/atom/atom) and [Tree-sitter](https://github.com/tree-sitter/tree-sitter).
## Development tips
## Developing Zed
### Dependencies
* Install Xcode from https://apps.apple.com/us/app/xcode/id497799835?mt=12, and accept the license:
```
sudo xcodebuild -license
```
* Install homebrew, node and rustup-init (rustup, rust, cargo, etc.)
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node rustup-init
rustup-init # follow the installation steps
```
* Install postgres and configure the database
```
brew install postgresql@15
brew services start postgresql@15
psql -c "CREATE ROLE postgres SUPERUSER LOGIN" postgres
psql -U postgres -c "CREATE DATABASE zed"
```
* Install the `LiveKit` server, the `PostgREST` API server, and the `foreman` process supervisor:
```
brew install livekit
brew install postgrest
brew install foreman
```
* 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
npm install -g vercel
```
* Return to Zed project directory and Initialize submodules
```
cd zed
git submodule update --init --recursive
```
* Set up a local `zed` database and seed it with some initial users:
[Create a personal GitHub token](https://github.com/settings/tokens/new) to run `script/bootstrap` once successfully: the token needs to have an access to private repositories for the script to work (`repo` OAuth scope).
Then delete that token.
```
GITHUB_TOKEN=<$token> script/bootstrap
```
* Now try running zed with collaboration disabled:
```
cargo run
```
### Common errors
* `xcrun: error: unable to find utility "metal", not a developer tool or in PATH`
* You need to install Xcode and then run: `xcode-select --switch /Applications/Xcode.app/Contents/Developer`
* (see https://github.com/gfx-rs/gfx/issues/2309)
### Testing against locally-running servers
Start the web and collab servers:
```
foreman start
```
If you want to run Zed pointed at the local servers, you can run:
```
script/zed-local
```
### Dump element JSON
If you trigger `cmd-alt-i`, Zed will copy a JSON representation of the current window contents to the clipboard. You can paste this in a tool like [DJSON](https://chrome.google.com/webstore/detail/djson-json-viewer-formatt/chaeijjekipecdajnijdldjjipaegdjc?hl=en) to navigate the state of on-screen elements in a structured way.
- [Building Zed](./docs/src/developing_zed__building_zed.md)
- [Running Collaboration Locally](./docs/src/developing_zed__local_collaboration.md)
### Licensing
License information for third party dependencies must be correctly provided for CI to pass.
We use [`cargo-about`](https://github.com/EmbarkStudios/cargo-about) to automatically comply with open source licenses. If CI is failing, check the following:
- Is it showing a `no license specified` error for a crate you've created? If so, add `publish = false` under `[package]` in your crate's Cargo.toml.
- Is the error `failed to satisfy license requirements` for a dependency? If so, first determine what license the project has and whether this system is sufficient to comply with this license's requirements. If you're unsure, ask a lawyer. Once you've verified that this system is acceptable add the license's SPDX identifier to the `accepted` array in `script/licenses/zed-licenses.toml`.
- Is `cargo-about` unable to find the license for a dependency? If so, add a clarification field at the end of `script/licenses/zed-licenses.toml`, as specified in the [cargo-about book](https://embarkstudios.github.io/cargo-about/cli/generate/config.html#crate-configuration).
### Wasm Plugins
Zed has a Wasm-based plugin runtime which it currently uses to embed plugins. To compile Zed, you'll need to have the `wasm32-wasi` toolchain installed on your system. To install this toolchain, run:
```bash
rustup target add wasm32-wasi
```
Plugins can be found in the `plugins` folder in the root. For more information about how plugins work, check the [Plugin Guide](./crates/plugin_runtime/README.md) in `crates/plugin_runtime/README.md`.

162
docs/src/developing_zed__building_zed.md
View File

@ -1,94 +1,120 @@
# Building Zed
🚧 TODO:
- [ ] Tidy up & update instructions
- [ ] 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
### Prerequisites
🚧 TODO 🚧 Update for open source
- Be added to the GitHub organization
- Be added to the Vercel team
- Create a [Personal Access Token](https://github.com/settings/personal-access-tokens/new) 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
## Process
### Dependencies
Expect this to take 30min to an hour! Some of these steps will take quite a while based on your connection speed, and how long your first build will be.
- Install [Rust](https://www.rust-lang.org/tools/install)
- Install the [GitHub CLI](https://cli.github.com/), [Livekit](https://formulae.brew.sh/formula/livekit) & [Foreman](https://formulae.brew.sh/formula/foreman)
```bash
brew install gh
brew install livekit
brew install foreman
```
- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store
- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
```bash
xcode-select --install
```
- If `xcode-select --print-path prints /Library/Developer/CommandLineTools…` run `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer.`
* Install [Postgres](https://postgresapp.com)
* Install the wasm toolchain
```bash
rustup target add wasm32-wasi
```
### Building Zed from Source
1. Install the [GitHub CLI](https://cli.github.com/):
- `brew install gh`
1. Clone the `zed` repo
- `gh repo clone zed-industries/zed`
1. Install Xcode from the macOS App Store
1. 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.`
1. Install [Postgres](https://postgresapp.com)
1. Install rust/rustup
- `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
1. Install the wasm toolchain
- `rustup target add wasm32-wasi`
1. Install Livekit & Foreman
- `brew install livekit`
- `brew install foreman`
1. Generate an GitHub API Key
- 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
1. (Optional but reccomended) Add your GITHUB_TOKEN to your `.zshrc` or `.bashrc` like this: `export GITHUB_TOKEN=yourGithubAPIToken`
1. 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
npm install -g vercel
```
1. 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. Run `vercel pull` to pull down the environment variables and project info from Vercel
```bash
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`
1. (🚧 TODO 🚧 - Will this be relevant for open source?) Ensure the Zed.dev website is checked out in a sibling directory and install its dependencies:
```bash
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
1. Open Postgres.app
1. From `./path/to/zed/`:
- Run:
- `GITHUB_TOKEN={yourGithubAPIToken} script/bootstrap`
- Replace `{yourGithubAPIToken}` with the API token you generated above.
- 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).
- If you get:
- ```bash
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)"`
1. 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`
- 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)`
**`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`
**`xcrun: error: unable to find utility "metal", not a developer tool or in PATH`**
### Seeding errors during `script/bootstrap` runs
### `script/bootstrap`
```bash
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...
@ -104,4 +130,4 @@ Same command
### If you experience errors that mention some dependency is using unstable features
Try `cargo clean` and `cargo build`
Try `cargo clean` and `cargo build`,