6.3 KiB
description, icon, lang
| description | icon | lang |
|---|---|---|
| 在全新机器上从头构建 Rust 核心。 | terminal | zh-CN |
构建 Rust 核心
本页面向贡献者，是在全新机器上编译 Rust 核心的参考文档。
它仅涵盖仓库根目录的 crate：
- Cargo 包：
openhuman - 二进制文件：
openhuman-core - 库：
openhuman_core
如果你需要完整的桌面应用（pnpm dev、Tauri、CEF、前端工具链），请使用环境搭建。该路径有额外的 JavaScript、子模块和桌面运行时依赖，不需要用于纯核心的 cargo 工作流。
1. 安装指定版本的 Rust 工具链
仓库在 rust-toolchain.toml 中固定了 Rust 版本：
- Channel：
1.93.0 - Components：
rustfmt、clippy
推荐安装方式：
rustup toolchain install 1.93.0 --component rustfmt --component clippy
rustup default 1.93.0
你也可以在安装 rustup 后，让 cargo 从 rust-toolchain.toml 自动安装。
2. 克隆仓库
仅核心开发：
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman
这对根目录 crate 来说已足够。
桌面/Tauri 开发则不同：
- 只有在构建桌面壳层或 CEF 感知的 Tauri 工具链时，才需要
app/src-tauri/vendor/子模块。 - 该流程请遵循环境搭建并运行
git submodule update --init --recursive。
3. 构建命令
从仓库根目录运行：
# 快速依赖 + 类型检查
cargo check --manifest-path Cargo.toml
# 实际 CLI / RPC 二进制文件的 Debug 构建
cargo build --manifest-path Cargo.toml --bin openhuman-core
# Release 构建
cargo build --manifest-path Cargo.toml --release --bin openhuman-core
# Rust 测试
cargo test --manifest-path Cargo.toml
注意：
- 包名是
openhuman，但可运行的二进制文件是openhuman-core。 - 如果你更喜欢面向包的 cargo 命令用于打包脚本，请使用
-p openhuman。 - 构建好的二进制文件位于
target/debug/openhuman-core或target/release/openhuman-core。
4. macOS 前置条件
安装：
- Xcode Command Line Tools：
xcode-select --install
原因：
whisper-rs在构建期间编译原生代码。- 在 macOS 上，该 crate 在
Cargo.toml中以metal特性启用构建，因此需要 Apple 工具链和 SDK 头文件。
安装 Xcode CLT 后，核心应该能用上述 cargo 命令构建。
5. Linux 前置条件
仅核心包集合
在全新 Linux 机器上运行 cargo 前，先安装这些包。
Ubuntu / Debian：
sudo apt-get update
sudo apt-get install -y \
build-essential cmake pkg-config clang libssl-dev libclang-dev \
libasound2-dev libxi-dev libxtst-dev libxdo-dev libudev-dev \
libstdc++-14-dev
Arch Linux：
sudo pacman -S --needed base-devel cmake pkgconf clang openssl \
alsa-lib libxi libxtst xdotool libevdev
在 Arch 上，
clang包含libclang，base-devel包含gcc（提供libstdc++），因此不需要单独的-dev包。
这些包的重要性：
build-essential/base-devel、cmake、pkg-config/pkgconf：传递性 Rust 依赖使用的原生构建。clang、libclang-dev：bindgen / C 和 C++ 编译路径，被原生 crate 使用。libssl-dev/openssl：某些网络依赖需要的 OpenSSL 头文件。libasound2-dev/alsa-lib、libxi-dev/libxi、libxtst-dev/libxtst、libxdo-dev/xdotool、libudev-dev（Arch 中已包含在systemd-libs内）、libevdev：被核心构建引入的音频/输入/设备 crate 所需。
whisper-rs + clang 注意事项
whisper-rs-sys 在 clang 下可能会失败并提示：
fatal error: 'array' file not found
这就是为什么文档特别指出 libstdc++-14-dev：clang 在 Ubuntu runner 上可能会选择 GCC 14 的 C++ 头文件。
如果你的发行版布局仍然导致构建无法解析 libstdc++.so，请使用 AGENTS.md 中记录的相同变通方案：
# Ubuntu/Debian —— 按需调整 GCC 版本
sudo ln -sf /usr/lib/gcc/x86_64-linux-gnu/13/libstdc++.so /usr/lib/x86_64-linux-gnu/libstdc++.so
Arch Linux 通常不需要此变通方案，因为 gcc-libs 将 libstdc++.so 放在了默认库搜索路径上。
Linux 桌面/Tauri 包集合
如果你构建的是桌面壳层而非仅核心 crate，请安装更广泛的依赖集合。
Ubuntu / Debian（镜像自 .github/workflows/build-desktop.yml）：
sudo apt-get update
sudo apt-get install -y \
libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev \
patchelf cmake libasound2-dev libxdo-dev libxtst-dev libx11-dev libxi-dev \
libevdev-dev libssl-dev libclang-dev \
libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
libgbm1 libpango-1.0-0 libcairo2 libatspi2.0-0 libxshmfence1 libu2f-udev
Arch Linux：
sudo pacman -S --needed gtk3 webkit2gtk-4.1 libayatana-appindicator \
librsvg patchelf nss nspr at-spi2-core libcups libdrm \
libxkbcommon libxcomposite libxdamage libxfixes libxrandr \
mesa pango cairo libxshmfence
仅在需要 app/src-tauri/ 时使用桌面列表；对于根 crate 工作，上面较小的仅核心列表是相关的基线。
6. Windows 前置条件
安装：
- 通过
rustup安装 Rust - Visual Studio Build Tools 2022 或带 使用 C++ 的桌面开发 工作负载的 Visual Studio
- CI 和发布构建使用的 MSVC 目标：
x86_64-pc-windows-msvc
安装 Microsoft 工具链后推荐的命令：
rustup toolchain install 1.93.0 --component rustfmt --component clippy
rustup target add x86_64-pc-windows-msvc
cargo build --manifest-path Cargo.toml --bin openhuman-core
Windows 注意事项：
- 仓库对
whisper-rs-sys打补丁以强制使用静态 MSVC CRT，并避免Cargo.toml中提到的LNK2038/LNK1169不匹配。请使用 MSVC 工具链，而非 MinGW。
7. 相关路径
- 环境搭建：完整的桌面贡献者设置，含
pnpm、Tauri、子模块和 sidecar staging。 - OpenHuman 架构：核心在桌面应用和 RPC 流程中的位置。