构建 Rust 核心
在一台全新的机器上从零构建 Rust 核心。
本页是面向贡献者的参考，说明如何在一台全新机器上编译 Rust 核心。
它只涵盖 仓库根目录的 crate:
Cargo 包：
openhuman二进制：
openhuman-core库：
openhuman_core
如果你想要完整的桌面应用（pnpm dev、Tauri、CEF、前端工具链），请使用 入门设置。那条路径会额外需要 JavaScript、子模块和桌面运行时，这些对于仅核心的 并不 需要 cargo 工作流。
1. 安装固定的 Rust 工具链
该仓库在 rust-toolchain.toml:
中固定了 Rust
1.93.0组件：
rustfmt,clippy
推荐安装：
rustup toolchain install 1.93.0 --component rustfmt --component clippy
rustup default 1.93.0你也可以让 cargo 自动从 rust-toolchain.toml 之后 rustup 本身安装完成后自动安装。
2. 克隆仓库
仅核心工作：
这对根 crate 来说已经足够。
桌面/Tauri 工作不同：
app/src-tauri/vendor/这些子模块只有在构建桌面壳或支持 CEF 的 Tauri 工具链时才需要。对于该流程，请遵循 入门设置 并运行
git submodule update --init --recursive.
3. 构建命令
在仓库根目录下：
说明：
该 包 名称是
openhuman，但可运行的二进制是openhuman-core.如果你更偏好面向包的 cargo 命令用于打包脚本，请使用
-p openhuman.构建出的二进制位于
target/debug/openhuman-core或target/release/openhuman-core.
更快的本地链接（可选）
该 openhuman 核心 crate 链接的是一个较大的单一 rlib，因此编辑 → cargo check/cargo test 内循环经常受链接速度限制。更快的链接器（Linux 上用 mold，macOS 上用 lld）可以为每次增量重链接节省大量时间。 .cargo/config.toml 记录了手动启用方式，但最简单的路径是：
先安装链接器（apt install mold / brew install llvm）——如果缺失，脚本会检测到并退出，同时给出说明。它是幂等的：如果链接器已经配置好，再次运行不会有任何影响。CI 通过 RUSTFLAGS 在 Linux Rust 作业中直接启用同样的标志；这个脚本的存在是为了让本地 cargo 调用也能获得同样的速度提升，而无需依赖容器。
4. macOS 先决条件
安装：
Xcode 命令行工具：
xcode-select --install
原因：
whisper-rs会在构建过程中编译本地代码。在 macOS 上，该 crate 构建时启用了
metal特性，且在Cargo.toml中，因此需要安装 Apple 工具链和 SDK 头文件。
安装完 Xcode CLT 后，核心应可使用上面的 cargo 命令构建。
5. Linux 先决条件
仅核心包集合
在全新 Linux 机器上运行 cargo 之前请安装这些包。
Ubuntu / Debian：
Arch Linux：
在 Arch 上，
clang包含libclang和base-devel包含gcc（提供libstdc++），因此不需要单独的-dev软件包。
这些为什么重要：
build-essential/base-devel,cmake,pkg-config/pkgconf：传递性 Rust 依赖使用的本地构建工具。clang,libclang-dev：native crate 使用的 bindgen / C 和 C++ 编译路径。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 下可能会失败，报错：
这就是文档中指出 libstdc++-14-dev: clang 可能会在 Ubuntu 运行器上选择 GCC 14 的 C++ 头文件的原因。
如果你的发行版布局仍然导致 libstdc++.so 在构建时无法解析，请使用 AGENTS.md:
Arch Linux 通常不需要这个变通方法，因为 gcc-libs 会将 libstdc++.so 放在默认库搜索路径中。
Linux 桌面/Tauri 包集合
如果你构建的是桌面壳而不是仅核心 crate，请安装更广泛的依赖集合。
Ubuntu / Debian （镜像自 .github/workflows/build-desktop.yml):
Arch Linux：
只有在你需要时才使用桌面列表 app/src-tauri/；对于根 crate 工作，上面更小的仅核心列表才是相关基线。
6. Windows 先决条件
安装：
通过
rustupVisual Studio Build Tools 2022 或带有 使用 C++ 的桌面开发 工作负载的 Visual Studio 安装 Rust
CI 和发布构建使用的 MSVC 目标：
x86_64-pc-windows-msvc
安装 Microsoft 工具链后推荐运行的命令：
Windows 注意：
该仓库会打补丁
whisper-rs-sys以强制使用静态 MSVC CRT，并避免LNK2038/LNK1169中提到的不匹配。请使用 MSVC 工具链，不要使用 MinGW。Cargo.toml.
7. 相关路径
入门设置：包含
pnpm、Tauri、子模块和 sidecar 暂存的完整桌面贡献者设置。OpenHuman 架构：核心如何适配桌面应用和 RPC 流程。
最后更新于