update docs content (#11374)
Move all docs to zed repo Release Notes: - N/A --------- Co-authored-by: Marshall Bowers <elliott.codes@gmail.com> Co-authored-by: Marshall <marshall@zed.dev>
This commit is contained in:
Conrad Irwin
GitHub
parent
3e5dcd1bec
commit
a497c49fb8
30 changed files with 996 additions and 479 deletions
29
docs/src/development/debugging-crashes.md
Normal file
29
docs/src/development/debugging-crashes.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# Debugging Crashes
|
||||
|
||||
## Crashes
|
||||
|
||||
When an app crashes, macOS creates a `.ips` file in `~/Library/Logs/DiagnosticReports`. You can view these using the built in Console app (`cmd-space Console`) under "Crash Reports".
|
||||
|
||||
If you have enabeld Zed's telemetry these will be uploaded to us when you restart the app. They end up in Datadog, and a [Slack channel (internal only)](https://zed-industries.slack.com/archives/C04S6T1T7TQ).
|
||||
|
||||
These crash reports are generated by the crashing binary, and contain a wealth of information; but they are hard to read for a few reasons:
|
||||
|
||||
- They don't contain source files and line numbers
|
||||
- The symbols are [mangled](https://doc.rust-lang.org/rustc/symbol-mangling/index.html)
|
||||
- Inlined functions are elided
|
||||
|
||||
To get a better sense of the backtrace of a crash you can download the `.ips` file locally and run:
|
||||
|
||||
```
|
||||
./script/symbolicate ~/path/zed-XXX-XXX.ips
|
||||
```
|
||||
|
||||
This will download the correct debug symbols from our public [digital ocean bucket](https://zed-debug-symbols.nyc3.digitaloceanspaces.com), and run [symbolicate](https://crates.io/crates/symbolicate) for you.
|
||||
|
||||
The output contains the source file and line number, and the demangled symbol information for every inlined frame.
|
||||
|
||||
## Panics
|
||||
|
||||
When the app panics at the rust level, Zed creates a file in `~/Library/Logs/Zed` with the text of the panic, and a summary of the backtrace. On boot, if you have telemetry enabled, we upload these panics so we can keep track of them.
|
||||
|
||||
A panic is also considered a crash, and so for most panics we get both the crash report and the panic.
|
||||
83
docs/src/development/linux.md
Normal file
83
docs/src/development/linux.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# Building Zed for Linux
|
||||
|
||||
## Repository
|
||||
|
||||
After cloning the repository, ensure all git submodules are initialized:
|
||||
|
||||
```shell
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Install [Rust](https://www.rust-lang.org/tools/install). If it's already installed, make sure it's up-to-date:
|
||||
|
||||
```bash
|
||||
rustup update
|
||||
```
|
||||
|
||||
- Install the necessary system libraries:
|
||||
|
||||
```bash
|
||||
script/linux
|
||||
```
|
||||
|
||||
If you prefer to install the system libraries manually, you can find the list of required packages in the `script/linux` file.
|
||||
|
||||
## Backend dependencies
|
||||
|
||||
> [!WARNING]
|
||||
> This section is still in development. The instructions are not yet complete.
|
||||
|
||||
If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
|
||||
|
||||
- Install [Postgres](https://www.postgresql.org/download/linux/)
|
||||
- Install [Livekit](https://github.com/livekit/livekit-cli) and [Foreman](https://theforeman.org/manuals/3.9/quickstart_guide.html)
|
||||
|
||||
Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
|
||||
|
||||
```sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Building from source
|
||||
|
||||
Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
|
||||
|
||||
For a debug build:
|
||||
|
||||
```
|
||||
cargo run
|
||||
```
|
||||
|
||||
For a release build:
|
||||
|
||||
```
|
||||
cargo run --release
|
||||
```
|
||||
|
||||
And to run the tests:
|
||||
|
||||
```
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
## Wayland & X11
|
||||
|
||||
Zed has basic support for both modes. The mode is selected at runtime. If you're on wayland and want to run in X11 mode, you can set `WAYLAND_DISPLAY='' cargo run` to do so.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Can't compile zed
|
||||
|
||||
Before reporting the issue, make sure that you have the latest rustc version with `rustup update`.
|
||||
|
||||
### Cargo errors claiming that a dependency is using unstable features
|
||||
|
||||
Try `cargo clean` and `cargo build`.
|
||||
|
||||
### Vulkan/GPU issues
|
||||
|
||||
If Zed crashes at runtime due to GPU or vulkan issues, you can try running [vkcube](https://github.com/krh/vkcube) (usually available as part of the `vulkaninfo` package on various distributions) to try to troubleshoot where the issue is coming from. Try running in both X11 and wayland modes by running `vkcube -m [x11|wayland]`. Some versions of `vkcube` use `vkcube` to run in X11 and `vkcube-wayland` to run in wayland.
|
||||
|
||||
If you have multiple GPUs, you can also try running Zed on a different one (for example, with [vkdevicechooser](https://github.com/jiriks74/vkdevicechooser)) to figure out where the issue comes from.
|
||||
68
docs/src/development/local-collaboration.md
Normal file
68
docs/src/development/local-collaboration.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# Local Collaboration
|
||||
|
||||
First, make sure you've installed Zed's [backend dependencies](./developing_zed__building_zed.md#backend-dependencies).
|
||||
|
||||
## Database setup
|
||||
|
||||
Before you can run the `collab` server locally, you'll need to set up a `zed` Postgres database.
|
||||
|
||||
```
|
||||
script/bootstrap
|
||||
```
|
||||
|
||||
This script will set up the `zed` Postgres database, and populate it with some users. It requires internet access, because it fetches some users from the GitHub API.
|
||||
|
||||
The script will seed the database with various content defined by:
|
||||
|
||||
```
|
||||
cat crates/collab/seed.default.json
|
||||
```
|
||||
|
||||
To use a different set of admin users, you can create your own version of that json file and export the `SEED_PATH` environment variable. Note that the usernames listed in the admins list currently must correspond to valid Github users.
|
||||
|
||||
```json
|
||||
{
|
||||
"admins": ["admin1", "admin2"],
|
||||
"channels": ["zed"]
|
||||
}
|
||||
```
|
||||
|
||||
## Testing collaborative features locally
|
||||
|
||||
In one terminal, run Zed's collaboration server and the `livekit` dev server:
|
||||
|
||||
```
|
||||
|
||||
foreman start
|
||||
|
||||
```
|
||||
|
||||
In a second terminal, run two or more instances of Zed.
|
||||
|
||||
```
|
||||
|
||||
script/zed-local -2
|
||||
|
||||
```
|
||||
|
||||
This script starts one to four instances of Zed, depending on the `-2`, `-3` or `-4` flags. Each instance will be connected to the local `collab` server, signed in as a different user from `.admins.json` or `.admins.default.json`.
|
||||
|
||||
## Running a local collab server
|
||||
|
||||
If you want to run your own version of the zed collaboration service, you can, but note that this is still under development, and there is no good support for authentication nor extensions.
|
||||
|
||||
Configuration is done through environment variables. By default it will read the configuration from [`.env.toml`](../../crates/collab/.env.toml) and you should use that as a guide for setting this up.
|
||||
|
||||
By default Zed assumes that the DATABASE_URL is a Postgres database, but you can make it use Sqlite by compiling with `--features sqlite` and using a sqlite DATABASE_URL with `?mode=rwc`.
|
||||
|
||||
To authenticate you must first configure the server by creating a seed.json file that contains at a minimum your github handle. This will be used to create the user on demand.
|
||||
|
||||
```json
|
||||
{
|
||||
"admins": ["nathansobo"]
|
||||
}
|
||||
```
|
||||
|
||||
By default the collab server will seed the database when first creating it, but if you want to add more users you can explicitly reseed them with `SEED_PATH=./seed.json cargo run -p collab seed`
|
||||
|
||||
Then when running the zed client you must specify two environment variables, `ZED_ADMIN_API_TOKEN` (which should match the value of `API_TOKEN` in .env.toml) and `ZED_IMPERSONATE` (which should match one of the users in your seed.json)
|
||||
89
docs/src/development/macos.md
Normal file
89
docs/src/development/macos.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
# Building Zed for macOS
|
||||
|
||||
## Repository
|
||||
|
||||
After cloning the repository, ensure all git submodules are initialized:
|
||||
|
||||
```shell
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Install [Rust](https://www.rust-lang.org/tools/install)
|
||||
- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store, or from the [Apple Developer](https://developer.apple.com/download/all/) website. Note this requires a developer account.
|
||||
|
||||
> Ensure you launch XCode after installing, and install the MacOS components, which is the default option.
|
||||
|
||||
- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
|
||||
|
||||
```bash
|
||||
xcode-select --install
|
||||
```
|
||||
|
||||
- Ensure that the Xcode command line tools are using your newly installed copy of Xcode:
|
||||
|
||||
```
|
||||
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
|
||||
```
|
||||
|
||||
* Install the Rust wasm toolchain:
|
||||
|
||||
```bash
|
||||
rustup target add wasm32-wasi
|
||||
```
|
||||
|
||||
## Backend Dependencies
|
||||
|
||||
If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
|
||||
|
||||
- Install [Postgres](https://postgresapp.com)
|
||||
- Install [Livekit](https://formulae.brew.sh/formula/livekit) and [Foreman](https://formulae.brew.sh/formula/foreman)
|
||||
|
||||
```bash
|
||||
brew install livekit foreman
|
||||
```
|
||||
|
||||
Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
|
||||
|
||||
```sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Building Zed from Source
|
||||
|
||||
Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
|
||||
|
||||
For a debug build:
|
||||
|
||||
```
|
||||
cargo run
|
||||
```
|
||||
|
||||
For a release build:
|
||||
|
||||
```
|
||||
cargo run --release
|
||||
```
|
||||
|
||||
And to run the tests:
|
||||
|
||||
```
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error compiling metal shaders
|
||||
|
||||
```
|
||||
error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
|
||||
|
||||
xcrun: error: unable to find utility "metal", not a developer tool or in PATH
|
||||
```
|
||||
|
||||
Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
|
||||
|
||||
### Cargo errors claiming that a dependency is using unstable features
|
||||
|
||||
Try `cargo clean` and `cargo build`.
|
||||
49
docs/src/development/releases.md
Normal file
49
docs/src/development/releases.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
# Zed Releases
|
||||
|
||||
Zed currently maintains two public releases for macOS:
|
||||
|
||||
- [Stable](https://zed.dev/download). This is the primary version that people download and use.
|
||||
- [Preview](https://zed.dev/releases/preview), which receives updates a week ahead of stable for early adopters.
|
||||
|
||||
Typically we cut a new minor release every Wednesday. The current Preview becomes Stable, and the new Preview contains everything on main up until that point.
|
||||
|
||||
If bugs are found and fixed during the week, they may be cherry-picked into the release branches and so new patch versions for preview and stable can become available throughout the week.
|
||||
|
||||
## Wednesday release process
|
||||
|
||||
You will need write access to the Zed repository to do this:
|
||||
|
||||
- Checkout `main` and ensure your working copy is clean.
|
||||
- Run `./script/bump-zed-minor-versions` and push the tags
|
||||
and branches as instructed.
|
||||
- Wait for the builds to appear at https://github.com/zed-industries/zed/releases (typically takes around 30 minutes)
|
||||
- While you're waiting:
|
||||
- Start creating the new release notes for preview. You can start with the output of `./script/get-preview-channel-changes`.
|
||||
- Start drafting the release tweets.
|
||||
- Once the builds are ready:
|
||||
- Copy the release notes from the previous Preview release(s) to the current Stable release.
|
||||
- Download the artifacts for each release and test that you can run them locally.
|
||||
- Publish the releases on GitHub.
|
||||
- Tweet the tweets (Credentials are in 1password).
|
||||
|
||||
## Patch release process
|
||||
|
||||
If your PR fixes a panic or a crash, you should cherry-pick it to the current stable and preview branches. If your PR fixes a regression in recently released code, you should cherry-pick it to preview.
|
||||
|
||||
You will need write access to the Zed repository to do this:
|
||||
|
||||
- Send a PR containing your change to `main` as normal.
|
||||
- Leave a comment on the PR `/cherry-pick v0.XXX.x`. Once your PR is merged, the GitHub bot will send a PR to the branch.
|
||||
- In case of a merge conflict, you will have to cherry-pick manually and push the change to the `v0.XXX.x` branch.
|
||||
- After the commits are cherry-picked onto the branch, run `./script/trigger-release {preview|stable}`. This will bump the version numbers, create a new release tag, and kick off a release build.
|
||||
- This can also be run from the [GitHub Actions UI](https://github.com/zed-industries/zed/actions/workflows/bump_patch_version.yml):
|
||||
|
||||
- Wait for the builds to appear at https://github.com/zed-industries/zed/releases (typically takes around 30 minutes)
|
||||
- Proof-read and edit the release notes as needed.
|
||||
- Download the artifacts for each release and test that you can run them locally.
|
||||
- Publish the release.
|
||||
|
||||
## Nightly release process
|
||||
|
||||
In addition to the public releases, we also have a nightly build that we encourage employees to use.
|
||||
Nightly is released by cron once a day, and can be shipped as often as you'd like. There are no release notes or announcements, so you can just merge your changes to main and run `./script/trigger-release nightly`.
|
||||
78
docs/src/development/windows.md
Normal file
78
docs/src/development/windows.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# Building Zed for Windows
|
||||
|
||||
> [!NOTE]
|
||||
> The following commands may be executed in any shell.
|
||||
|
||||
## Repository
|
||||
|
||||
After cloning the repository, ensure all git submodules are initialized:
|
||||
|
||||
```shell
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Install [Rust](https://www.rust-lang.org/tools/install). If it's already installed, make sure it's up-to-date:
|
||||
|
||||
```bash
|
||||
rustup update
|
||||
```
|
||||
|
||||
- Install the Rust wasm toolchain:
|
||||
|
||||
```bash
|
||||
rustup target add wasm32-wasi
|
||||
```
|
||||
|
||||
- Install [Visual Studio](https://visualstudio.microsoft.com/downloads/) with optional component `MSVC v*** - VS YYYY C++ x64/x86 build tools` and install Windows 11 or 10 SDK depending on your system
|
||||
|
||||
> [!NOTE] > `v***` is your VS version and `YYYY` is year when your VS was released.
|
||||
|
||||
## Backend dependencies
|
||||
|
||||
> [!WARNING]
|
||||
> This section is still in development. The instructions are not yet complete.
|
||||
|
||||
If you are developing collaborative features of Zed, you'll need to install the dependencies of zed's `collab` server:
|
||||
|
||||
- Install [Postgres](https://www.postgresql.org/download/windows/)
|
||||
- Install [Livekit](https://github.com/livekit/livekit-cli) and [Foreman](https://theforeman.org/manuals/3.9/quickstart_guide.html)
|
||||
|
||||
Alternatively, if you have [Docker](https://www.docker.com/) installed you can bring up all the `collab` dependencies using Docker Compose:
|
||||
|
||||
```sh
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Building from source
|
||||
|
||||
Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
|
||||
|
||||
For a debug build:
|
||||
|
||||
```
|
||||
cargo run
|
||||
```
|
||||
|
||||
For a release build:
|
||||
|
||||
```
|
||||
cargo run --release
|
||||
```
|
||||
|
||||
And to run the tests:
|
||||
|
||||
```
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Can't compile zed
|
||||
|
||||
Before reporting the issue, make sure that you have the latest rustc version with `rustup update`.
|
||||
|
||||
### Cargo errors claiming that a dependency is using unstable features
|
||||
|
||||
Try `cargo clean` and `cargo build`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue