From d266fe7491e16bcf1fd7edcdc42d66d3e3559458 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Thu, 1 Oct 2026 12:17:18 -0400 Subject: [PATCH] =?UTF-8?q?T48c=20Docs=20=C2=B7=20Installation:=20requirem?= =?UTF-8?q?ents,=20the=20git=20dependencies=20and=20why,=20shaders,=20a=20?= =?UTF-8?q?check,=20failures=20and=20their=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- frontend/src/docs/guides.ts | 2 +- frontend/src/docs/installation.md | 49 +++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 frontend/src/docs/installation.md diff --git a/frontend/src/docs/guides.ts b/frontend/src/docs/guides.ts index 9653f90..d96b645 100644 --- a/frontend/src/docs/guides.ts +++ b/frontend/src/docs/guides.ts @@ -6,7 +6,7 @@ import { Marked, type Tokens } from "marked"; const at = (relative: string) => fileURLToPath(new URL(relative, import.meta.url)); /** The guides in reading order, by file name. */ -const ORDER = ["introduction"]; +const ORDER = ["introduction", "installation"]; export interface Guide { /** The path segment; the introduction has none. */ diff --git a/frontend/src/docs/installation.md b/frontend/src/docs/installation.md new file mode 100644 index 0000000..98c9c61 --- /dev/null +++ b/frontend/src/docs/installation.md @@ -0,0 +1,49 @@ +# Installation + +## Requirements + +- Rust 1.95 or later, the version Ely's `Cargo.toml` names. +- macOS, where Ely is tested. Windows and Linux builds are not tested yet. +- No full Xcode: Ely compiles GPUI's Metal shaders when the app starts. + +## Add the dependencies + +Ely is not on crates.io. Depend on it by git, with GPUI from Zed's repository at the revision Ely pins: + +```toml +[dependencies] +ely-gpui-component = { git = "https://github.com/ZacharyZhang-NY/Ely-GPUI-Components" } +gpui = { git = "https://github.com/zed-industries/zed", rev = "1a28cff4b409169bac058bca40dfbfeb7621d19b" } +gpui_platform = { git = "https://github.com/zed-industries/zed", rev = "1a28cff4b409169bac058bca40dfbfeb7621d19b", features = ["font-kit"] } +``` + +| Line | Why | +| --- | --- | +| `ely-gpui-component` | The library. `Cargo.lock` records the commit; add `rev = ""` to hold it in `Cargo.toml` as well. | +| `gpui` | The same revision as Ely's. Another revision builds a second GPUI, and its types do not match the ones Ely takes. | +| `gpui_platform` | Opens windows on each platform. Without `font-kit`, macOS falls back to GPUI's no-op text system and draws no text. | + +## Shaders + +Ely's default feature, `runtime_shaders`, turns on the same feature in `gpui_platform`, so GPUI compiles its Metal shaders at run time. With `default-features = false` the build runs `xcrun metal` instead, which needs Xcode's Metal compiler. + +## Check the install + +Copy the [first window](/docs/#a-first-window) into `src/main.rs` and run it: + +```sh +cargo run +``` + +A window opens with a counter and a Press button. From a clone of the repository, `cargo run --example gallery` opens every chapter. + +## When it fails + +| Symptom | Cause and fix | +| --- | --- | +| Panic: ``ely: pass `ely_gpui_component::Assets` to `Application::with_assets` `` | `init` found no Ely assets. Start the app with `gpui_platform::application().with_assets(Assets)`. | +| Panic: `ely: asset source failed` | The app's asset source returned an error. The panic carries it. | +| Panic: `ely: embedded fonts failed to register` | GPUI's text system refused Ely's fonts. File a bug with the log. | +| Windows open with no text on macOS | `gpui_platform` lacks the `font-kit` feature. | +| `mismatched types`, with the note ``there are multiple different versions of crate `gpui` in the dependency graph`` | `gpui` points at a revision other than Ely's. Use `1a28cff4b409169bac058bca40dfbfeb7621d19b`. | +| `metal shader compilation failed` | Default features are off and Xcode's Metal compiler is missing. Keep `runtime_shaders`. |