# 构建 Rust 核心

本页是供贡献者参考的、用于在全新机器上编译 Rust 核心的说明。

它仅涵盖 **仓库根目录的 crate**:

* Cargo 包： `openhuman`
* 二进制： `openhuman-core`
* 库： `openhuman_core`

如果你想要完整桌面应用（`pnpm dev`、Tauri、CEF、前端工具链），请使用 [安装与设置](/openhuman/zh/kai-fa/getting-set-up.md)。那条路径还需要额外的 JavaScript、子模块和桌面运行时要求，这些对仅核心的 **并不** 需要的 `cargo` 工作流。

## 1. 安装固定的 Rust 工具链

仓库在以下文件中固定了 Rust 版本 [`rust-toolchain.toml`](https://github.com/tinyhumansai/openhuman/blob/main/rust-toolchain.toml):

* 通道： `1.93.0`
* 组件： `rustfmt`, `clippy`

建议安装方式：

```bash
rustup toolchain install 1.93.0 --component rustfmt --component clippy
rustup default 1.93.0
```

你也可以让 `cargo` 从以下位置自动安装 `rust-toolchain.toml` 之后 `rustup` 本身安装完成后。

## 2. 克隆仓库

仅核心开发：

```bash
git clone https://github.com/tinyhumansai/openhuman.git
cd openhuman
```

这对根 crate 来说就足够了。

桌面/Tauri 开发则不同：

* `app/src-tauri/vendor/` 只有在构建桌面外壳或支持 CEF 的 Tauri 工具时才需要子模块。
* 对于该流程，请按照 [安装与设置](/openhuman/zh/kai-fa/getting-set-up.md) 并运行 `git submodule update --init --recursive`.

## 3. 构建命令

从仓库根目录执行：

```bash
# 快速依赖检查 + 类型检查
cargo check --manifest-path Cargo.toml

# 实际 CLI / RPC 二进制的调试构建
cargo build --manifest-path Cargo.toml --bin openhuman-core

# 发布构建
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 命令行工具： `xcode-select --install`

原因：

* `whisper-rs` 在构建期间会编译原生代码。
* 在 macOS 上，这个 crate 在 `metal` 功能启用的情况下构建，位于 [`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml)中，因此需要存在 Apple 工具链和 SDK 头文件。

安装好 Xcode CLT 后，核心应可使用上面的 cargo 命令构建。

## 5. Linux 先决条件

### 仅核心软件包集合

在新的 Linux 机器上运行 `cargo` 之前，请安装这些软件包。

**Ubuntu / Debian：**

```bash
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：**

```bash
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`：本地 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` 下失败，并出现：

```
fatal error: 'array' file not found
```

这就是文档提到 `libstdc++-14-dev`: `clang` 在 Ubuntu runner 上可能会选到 GCC 14 的 C++ 头文件的原因。

如果你的发行版布局仍然导致 `libstdc++.so` 在构建时无法解析，请使用 [`AGENTS.md`](https://github.com/tinyhumansai/openhuman/blob/main/AGENTS.md):

```bash
中记录的相同解决方法：
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`](https://github.com/tinyhumansai/openhuman/blob/main/.github/workflows/build-desktop.yml)):

```bash
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：**

```bash
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`
* Visual Studio Build Tools 2022 或带有以下组件的 Visual Studio： **使用 C++ 的桌面开发** 工作负载
* CI 和发布构建使用的 MSVC 目标： `x86_64-pc-windows-msvc`

安装 Microsoft 工具链后，推荐执行的命令：

```powershell
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，并避免 `LNK2038` / `LNK1169` 在中提到的不匹配问题 [`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml)。请使用 MSVC 工具链，不要使用 MinGW。

## 7. 相关路径

* [安装与设置](/openhuman/zh/kai-fa/getting-set-up.md)：完整的桌面贡献者设置，包含 `pnpm`、Tauri、子模块和侧车阶段。
* [OpenHuman 架构](/openhuman/zh/kai-fa/architecture.md)：核心在桌面应用和 RPC 流程中的位置。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/building-rust-core.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.