From edc197001a84a72c73a364b5fa8d8a17510833bb Mon Sep 17 00:00:00 2001 From: Jason Lee <5518+huacnlee@users.noreply.github.com> Date: Thu, 1 Oct 2026 01:45:49 +0800 Subject: [PATCH] docs: Document macOS font-kit requirement --- website/docs/getting-started.md | 29 +++++++++++++++++++++++++++ website/docs/installation.md | 1 + website/zh-CN/docs/getting-started.md | 24 ++++++++++++++++++++++ website/zh-CN/docs/installation.md | 1 + 4 files changed, 55 insertions(+) diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md index 0796491a1a..44c1a62a5d 100644 --- a/website/docs/getting-started.md +++ b/website/docs/getting-started.md @@ -24,6 +24,35 @@ gpui-kit = "{{gpui_kit_version}}" This single dependency includes GPUI, GPUI Base, the styled GPUI Component library and its default icon assets. Application code accesses GPUI through `use gpui_kit::*;` and components through `gpui_kit::component`. You can change the feature selection later; see [Icons & Assets](./assets.md). +### macOS text rendering: `font-kit` + +**macOS needs the `font-kit` feature on `gpui-pre-platform` to render text.** +The `gpui-kit` dependency above already enables it, so this guide needs no +additional dependency or feature setting. + +If you maintain an application that depends on GPUI directly, enable the feature +on the `gpui_platform` dependency instead. For a macOS-only GPUI application, +the dependency entries are: + +```toml +[dependencies] +gpui = { package = "gpui-pre", version = "={{gpui_pre_version}}" } +gpui_platform = { package = "gpui-pre-platform", version = "={{gpui_pre_version}}", features = ["font-kit"] } +``` + +Keep any other platform features your application uses, and keep the GPUI +snapshot versions aligned. This is an alternative for direct GPUI users; keep +the single `gpui-kit` dependency for the Kit example below. Do not add +`features = ["font-kit"]` to `gpui` or `gpui-kit`, or add a separate `font-kit` +dependency: the feature belongs to `gpui-pre-platform` and enables +`gpui-pre-macos/font-kit`. + +`gpui-pre-platform` does not enable `font-kit` by default. Without it, the macOS +backend uses `NoopTextSystem`: a window can open while no text is rendered, +and `all_font_names()` returns an empty list. After updating your manifest, +rebuild with `cargo run`. On macOS, `cargo tree -e features -i gpui-pre-macos` +shows which dependencies enable the backend's features; check for `font-kit`. + ## Add a view Replace `src/main.rs` with: diff --git a/website/docs/installation.md b/website/docs/installation.md index 09aada789c..4abdeafc3c 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -81,6 +81,7 @@ For a new project instead, follow [Getting Started](./getting-started). It creat | Windows reports `link.exe` missing or cannot find a Windows SDK. | Confirm the Visual Studio C++ workload and SDK are installed, then build with an MSVC Rust toolchain from a Visual Studio Developer PowerShell if needed. | | Linux reports a missing `pkg-config` executable, X11, Wayland, fontconfig, or WebKit header. | Install the Ubuntu packages above, or their equivalents for your distribution. If `pkg-config` itself is missing, install the `pkg-config` package too. The error identifies the missing tool or system library. | | The program compiles but no window appears on Linux. | Check that the process is running in a graphical Wayland or X11 session and that a Vulkan driver works for that session. A headless shell or Vulkan loader without a driver is insufficient. | +| A window opens on macOS, but no text is rendered. | If you depend on GPUI directly, enable `font-kit` on `gpui-pre-platform` and rebuild. `gpui-kit` already enables it. See [Getting Started](./getting-started.md#macos-text-rendering-font-kit) for the manifest and feature check. | | Cargo cannot resolve `gpui-pre` or APIs differ from these examples. | Keep the `gpui-kit` requirement and update dependencies together. Kit pins a matching `gpui-pre-*` snapshot; do not override one GPUI package to a different version. In a repository checkout, use the checked-in `Cargo.lock`. | For errors after a window opens, continue with [Getting Started](./getting-started) and inspect the relevant guide for the feature you are using. diff --git a/website/zh-CN/docs/getting-started.md b/website/zh-CN/docs/getting-started.md index aa12ccd1b3..d86a80f894 100644 --- a/website/zh-CN/docs/getting-started.md +++ b/website/zh-CN/docs/getting-started.md @@ -24,6 +24,30 @@ gpui-kit = "{{gpui_kit_version}}" 只需这一个依赖，即可使用 GPUI、GPUI Base、带样式的 GPUI Component 和默认图标资源。应用代码通过 `use gpui_kit::*;` 使用 GPUI，通过 `gpui_kit::component` 使用组件。以后可以调整 feature 选择，详见[图标与资源](./assets.md)。 +### macOS 文字渲染：`font-kit` + +**macOS 需要启用 `gpui-pre-platform` 的 `font-kit` feature 才能渲染文字。** +上面的 `gpui-kit` 依赖已经启用了它，按本指南创建应用时无需额外添加依赖或配置 feature。 + +如果你维护的应用直接依赖 GPUI，需要在 `gpui_platform` 依赖上启用这个 feature。 +仅面向 macOS 的 GPUI 应用可使用以下依赖配置： + +```toml +[dependencies] +gpui = { package = "gpui-pre", version = "={{gpui_pre_version}}" } +gpui_platform = { package = "gpui-pre-platform", version = "={{gpui_pre_version}}", features = ["font-kit"] } +``` + +保留应用原有的其他平台 features，并保持 GPUI 快照版本一致。这是直接使用 GPUI 时的配置； +本页后续 Kit 示例仍只需 `gpui-kit` 一个依赖。不要把 `features = ["font-kit"]` 加到 +`gpui` 或 `gpui-kit` 上，也无需单独添加 `font-kit` crate：这个 feature 属于 +`gpui-pre-platform`，会启用 `gpui-pre-macos/font-kit`。 + +`gpui-pre-platform` 默认不启用 `font-kit`。未启用时，macOS 后端会使用 `NoopTextSystem`： +窗口可以打开，但不会渲染文字，`all_font_names()` 也会返回空列表。修改 manifest 后， +重新运行 `cargo run`。在 macOS 上，可以用 `cargo tree -e features -i gpui-pre-macos` +查看后端的 features 由哪些依赖启用，确认其中包含 `font-kit`。 + ## 添加视图 将 `src/main.rs` 替换为： diff --git a/website/zh-CN/docs/installation.md b/website/zh-CN/docs/installation.md index ddaba31b1e..a101dd925c 100644 --- a/website/zh-CN/docs/installation.md +++ b/website/zh-CN/docs/installation.md @@ -81,6 +81,7 @@ cargo run -p hello_world | Windows 提示缺少 `link.exe` 或 Windows SDK。 | 检查 Visual Studio C++ workload 和 SDK，并确认使用 MSVC Rust 工具链；必要时从 Visual Studio Developer PowerShell 构建。 | | Linux 提示缺少 `pkg-config` 命令、X11、Wayland、fontconfig 或 WebKit 头文件。 | 安装上面的 Ubuntu 开发包，或对应发行版的等价包。如果缺少 `pkg-config` 命令本身，还需安装 `pkg-config` 包；根据报错定位具体工具或系统库。 | | Linux 上编译成功，但没有出现窗口。 | 确认程序运行于 Wayland 或 X11 图形会话，并且会话中有可用的 Vulkan 驱动。无图形环境的终端或只有 Vulkan loader 都不够。 | +| macOS 上窗口可以打开，但没有文字。 | 如果直接依赖 GPUI，请在 `gpui-pre-platform` 上启用 `font-kit` 并重新构建。`gpui-kit` 已经启用了它。配置示例和 feature 检查命令见 [Getting Started](./getting-started.md#macos-文字渲染font-kit)。 | | Cargo 无法解析 `gpui-pre`，或 API 与示例不一致。 | 保留 `gpui-kit` 依赖要求，并一起更新依赖。Kit 固定一组匹配的 `gpui-pre-*` 快照；不要把其中某个 GPUI 包单独覆盖为别的版本。在本仓库中使用已提交的 `Cargo.lock`。 | 窗口打开后的功能问题，可继续阅读[Getting Started](./getting-started)以及对应功能指南。