docs: current bilingual build guide; retire the C++/CMake one

docs/build.md + docs/zh/build.md rewritten for the Rust workspace:
project-built FFmpeg 8.1 (.cargo/config.toml presets FFMPEG_DIR),
vendored static OCIO on Linux/macOS vs MSYS2 dynamic OCIO on Windows
(with the OCIO_INSTALL_DIR/OCIO_RS_LINK env), the Windows GNU toolchain
requirements (MSYS2 Rust, RUSTFLAGS=-C link-args=-lmsvcrt for the
mingw-w64 _assert forwarding, unset INCLUDE/LIB), Linux audio dev
packages and xvfb headless testing, container packaging, and a
troubleshooting section. The macOS-only guides gain a deprecation
pointer. Also correct two stale comments in tooling/install-deps.sh
(FFmpeg is built by tooling/ffmpeg/build-ffmpeg.sh, not by cargo).

docs/zh/build.md

@@ -1,342 +1,164 @@
 # 构建指南
 
-本文档介绍如何在 Windows、Linux 和 macOS 上从源码构建 Oak Video Editor。
+本文档介绍如何在 macOS、Linux 和 Windows 上从源码构建 Oak 视频编辑器。
+英文版见 [`../build.md`](../build.md)。
 
-## 依赖
-
-- CMake 3.20+
-- Ninja（推荐）
-- Qt 6（含私有头文件）
-- FFmpeg 6.0+ 开发库
-- OpenTimelineIO（0.16+，按下文从源码构建——大多数平台没有发行版软件包）
-- OpenImageIO
-- OpenColorIO（2.x）
-- OpenEXR
-- Expat
-- PortAudio
-- OpenGL 头文件
-- Vulkan SDK（可选，Vulkan 渲染后端需要）
-- XKB common（Linux）
+> **2026 年说明：** Oak 现在是纯 Rust workspace。在仓库根目录执行
+> `cargo build` 会产出应用（`oak-editor`）、命令行工具（`oak-cli`）
+> 和渲染进程（`oak-worker`）。旧的 C++/CMake 代码保留在
+> `cpp-legacy` 分支，本指南不涉及它。
 
 ---
 
-## Windows（MSYS2）
+## 通用前置条件
 
-本指南使用 [MSYS2](https://www.msys2.org/) 的 UCRT64 工具链。
+- **git** —— 克隆时必须带子模块（`gpui/` 是子模块）：
+  ```sh
+  git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
+  cd oak
+  # 已有克隆则：git submodule update --init --recursive
+  ```
+- **Rust stable**（通过 [rustup](https://rustup.rs/) 安装；Windows
+  请改用 MSYS2 自带 Rust——见 Windows 章节）。
+- **C 工具链 + cmake + pkg-config + nasm** —— cmake 和 C++ 编译器
+  用于 vendored OpenColorIO 构建（Linux/macOS），nasm 用于 FFmpeg
+  汇编。
+- **FFmpeg 8.1，由项目脚本构建。** 发行版自带版本对 `ffmpeg-next` 9
+  来说太旧，刻意不使用：
+  ```sh
+  tooling/install-deps.sh        # 编解码/滤镜库 + 构建工具
+  tooling/ffmpeg/build-ffmpeg.sh # 克隆 release/8.1，安装到 .cache/ffmpeg
+  ```
+  `FFMPEG_DIR` 无需手动导出：仓库内提交的 `.cargo/config.toml` 已按
+  workspace 根的相对路径设置（`ffmpeg-sys-next` 的构建脚本读不了
+  `.env`，这是唯一与机器无关的方式）。缺少它时 `oakffmpeg-link` 的
+  构建脚本会直接 panic：首次 `cargo build` 前请先跑一次
+  `build-ffmpeg.sh`。
 
-### 1. 安装 MSYS2
+## 快速开始（macOS / Linux）
 
-从 [https://www.msys2.org/](https://www.msys2.org/) 下载并安装 MSYS2，然后打开 **MSYS2 UCRT64** 终端。
-
-### 2. 安装依赖
-
-```bash
-pacman -Syu
-pacman -S --needed \
-  mingw-w64-ucrt-x86_64-cmake \
-  mingw-w64-ucrt-x86_64-ninja \
-  mingw-w64-ucrt-x86_64-qt6-base \
-  mingw-w64-ucrt-x86_64-qt6-tools \
-  mingw-w64-ucrt-x86_64-ffmpeg \
-  mingw-w64-ucrt-x86_64-openimageio \
-  mingw-w64-ucrt-x86_64-opencolorio \
-  mingw-w64-ucrt-x86_64-openexr \
-  mingw-w64-ucrt-x86_64-fmt \
-  mingw-w64-ucrt-x86_64-expat \
-  mingw-w64-ucrt-x86_64-portaudio \
-  mingw-w64-ucrt-x86_64-vulkan-headers \
-  mingw-w64-ucrt-x86_64-vulkan-loader \
-  mingw-w64-ucrt-x86_64-gcc
-```
-
-> **注意：** Qt 6 私有头文件可能需要额外安装。如果 CMake 报告找不到私有头文件，请尝试安装 `mingw-w64-ucrt-x86_64-qt6-base-private`（如果仓库中有）。
-
-### 3. 构建 OpenTimelineIO（必需）
-
-MSYS2 仓库没有 OpenTimelineIO 软件包，需从源码构建：
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-### 4. 克隆并构建
-
-```bash
-# 克隆仓库
-git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
-cd oak
-
-# 配置
-cmake -S . -B build -G Ninja \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DOTIO_LOCATION="/path/to/otio-install" \
-  -DBUILD_QT6=ON
-
-# 构建
-cmake --build build --config Release
-```
-
-### 5. 运行测试（可选）
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
----
-
-## Linux
-
-### Debian / Ubuntu
-
-安装依赖（Ubuntu 24.04+ 自带的 FFmpeg 6.1 已满足 6.0 最低要求；更旧的发行版请按"故障排除"一节从源码编译 FFmpeg）：
-
-```bash
-sudo apt-get update
-sudo apt-get install -y \
-  cmake ninja-build pkg-config \
-  qt6-base-dev qt6-base-dev-tools qt6-base-private-dev qt6-tools-dev qt6-tools-dev-tools \
-  libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev \
-  libopencolorio-dev libopenimageio-dev libopenexr-dev libexpat1-dev \
-  portaudio19-dev libgl1-mesa-dev libvulkan-dev libxkbcommon-dev
-```
-
-从源码构建 OpenTimelineIO（必需，无发行版软件包）：
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-配置并构建：
-
-```bash
-cmake -S . -B build -G Ninja \
-  -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="$PWD/otio-install"
-cmake --build build --config Release
-```
-
-运行测试：
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
-### Fedora
-
-安装依赖：
-
-```bash
-sudo dnf install -y \
-  cmake ninja-build pkgconf-pkg-config \
-  qt6-qtbase-devel qt6-qtbase-private-devel qt6-qttools-devel \
-  ffmpeg-free-devel \
-  OpenImageIO-devel \
-  OpenColorIO-devel \
-  openexr-devel \
-  expat-devel \
-  portaudio-devel \
-  mesa-libGL-devel \
-  vulkan-headers \
-  vulkan-loader-devel \
-  libxkbcommon-devel \
-  gcc-c++ \
-  bzip2-devel
-```
-
-从源码构建 OpenTimelineIO（必需，无发行版软件包）：
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-配置并构建：
-
-```bash
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="$PWD/otio-install"
-cmake --build build --config Release
-```
-
-运行测试：
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
-### Arch Linux
-
-安装依赖：
-
-```bash
-sudo pacman -Syu
-sudo pacman -S --needed \
-  cmake ninja pkgconf \
-  qt6-base qt6-tools \
-  ffmpeg \
-  openimageio \
-  opencolorio \
-  openexr \
-  expat \
-  portaudio \
-  opentimelineio \
-  mesa \
-  vulkan-headers \
-  vulkan-icd-loader \
-  libxkbcommon \
-  fmt \
-  gcc
-```
-
-> **注意：** Arch Linux 的 `qt6-base` 包已经包含私有头文件。
-
-配置并构建：
-
-```bash
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON
-cmake --build build --config Release
-```
-
-运行测试：
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
+```sh
+tooling/install-deps.sh         # Homebrew / apt / dnf / pacman
+tooling/ffmpeg/build-ffmpeg.sh  # 约 10–20 分钟，只需一次
+cargo build --workspace
+cargo test  --workspace         # Linux：见下文"无头测试"
 ```
 
 ---
 
 ## macOS
 
-macOS 现在是正式支持的平台。更详细的逐步指南请参见 [`build_macos-zh.md`](build_macos-zh.md)。
+- macOS 12+、Xcode Command Line Tools（`xcode-select --install`）、Homebrew。
+- ```sh
+  brew install cmake pkg-config
+  tooling/install-deps.sh
+  tooling/ffmpeg/build-ffmpeg.sh
+  cargo build --workspace
+  cargo test  --workspace
+  ```
+- OpenColorIO 由 vendored 2.5.2 源码编译并静态链接——不需要
+  `brew install opencolorio`（但需要 cmake）。
+- GPU 相关测试（OFX GL 叠加层、硬件解码）仅在设置 `OAK_GPU_TESTS=1`
+  时运行。
 
-安装依赖：
+## Linux
 
-```bash
-brew update
-brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader
-```
+- `tooling/install-deps.sh` 支持 Debian/Ubuntu、Fedora、Arch。
+  另外需要安装：
+  ```sh
+  # Debian/Ubuntu
+  sudo apt-get install -y cmake \
+    libpipewire-0.3-dev libspa-0.2-dev libjack-jackd2-dev \
+    libasound2-dev libpulse-dev libsndfile1-dev \
+    libgl1-mesa-dev libvulkan-dev libxkbcommon-dev libxkbcommon-x11-dev
+  ```
+  （PipeWire/JACK/ALSA/PulseAudio/sndfile 开发包是 cpal 的音频后端；
+  GL/Vulkan/XKB 是 wgpu 窗口栈。）
+- **无头测试：** 部分 gpui/UI 测试会通过 wgpu 在 Mesa 软件 Vulkan
+  （lavapipe）上打开真实窗口。无显示环境下请运行：
+  ```sh
+  sudo apt-get install -y xvfb mesa-vulkan-drivers
+  xvfb-run -a -s "-screen 0 1920x1080x24" cargo test --workspace
+  ```
+- OpenColorIO 与 macOS 相同，使用 vendored 静态构建。
 
-构建 OpenTimelineIO（必需）：
+## Windows（MSYS2 UCRT64）
 
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
+Windows 构建目标是 **x86_64-pc-windows-gnu**，使用 MSYS2 自带 Rust；
+不支持 MSVC 工具链（构建脚本会发出 MSVC 链接器不接受的 Unix 风格
+链接参数）。
 
-配置并构建：
-
-```bash
-export PATH="$(brew --prefix qt@6)/bin:$PATH"
-export CMAKE_PREFIX_PATH="$(brew --prefix qt@6)"
-export OTIO_LOCATION="${PWD}/otio-install"
-export OCIO_LOCATION="$(brew --prefix opencolorio)"
-# 让 CMake 的 FindVulkan 找到 Homebrew 的 Vulkan loader（可选，
-# 启用 Vulkan 渲染后端）
-export VULKAN_SDK="$(brew --prefix vulkan-loader)"
-
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="${OTIO_LOCATION}" \
-  -DOCIO_LOCATION="${OCIO_LOCATION}"
-cmake --build build --config Release
-```
-
-运行测试：
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
+1. 安装 [MSYS2](https://www.msys2.org/)，打开 **UCRT64** 终端。
+2. ```sh
+   pacman -Syu
+   pacman -S --needed mingw-w64-ucrt-x86_64-rust \
+     mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-opencolorio
+   tooling/install-deps.sh        # 必须在 UCRT64 终端内运行
+   tooling/ffmpeg/build-ffmpeg.sh
+   ```
+3. 环境变量（写入 shell rc 或每次会话导出）：
+   ```sh
+   # vendored OCIO 源码含有仅 MSVC 可编译的构造，Windows 改为动态链接
+   # MSYS2 的 OpenColorIO 2.5.2：
+   export OCIO_RS_ENABLE_REAL=1 OCIO_INSTALL_DIR=/ucrt64 OCIO_RS_LINK=dynamic
+   # mingw-w64（2025 年 11 月后）把 _assert 转发到 libmingwex.a 里的
+   # __msvcrt_assert，而 rustc 的链接顺序把 -lmingwex 放在最后；末尾
+   # 追加 -lmsvcrt 让链接器再扫一遍 CRT 导入库
+   # （否则报 undefined _fileno/_setmode/__imp___msvcrt_assert）。
+   export RUSTFLAGS="-C link-args=-lmsvcrt"
+   # 如果 shell 继承了 MSVC 的 INCLUDE/LIB（某些 CI runner 会向每个
+   # 步骤注入），务必清除——它们会污染 MinGW 编译：
+   unset INCLUDE LIB
+   ```
+4. ```sh
+   cargo build --workspace
+   cargo test  --workspace
+   ```
 
 ---
 
-## 构建选项
+## OpenColorIO 一览
 
-| 选项 | 默认值 | 说明 |
-|------|--------|------|
-| `BUILD_TESTS` | `OFF` | 构建单元测试 |
-| `BUILD_DOXYGEN` | `OFF` | 构建 Doxygen 文档 |
-| `USE_WERROR` | `OFF` | 将警告视为错误 |
-| `BUILD_QT6` | `ON` | 使用 Qt 6 而非 Qt 5 |
-| `OTIO_LOCATION` | - | OpenTimelineIO 安装路径（必需） |
-| `OAK_BUNDLE_OTIO` | `ON` | 随 Oak 一并安装 OTIO 运行库（发行版原生打包且 `opentimelineio` 是包依赖时设 `OFF`，如 Arch） |
-| `OCIO_LOCATION` | - | OpenColorIO 安装路径 |
-| `OAK_ENABLE_DYNAMIC_RENDER_BACKEND` | `ON` | 构建动态渲染后端库（`liboakgl.so` / `liboakvulkan.so`） |
+| 平台 | 来源 | 链接方式 | 备注 |
+|------|------|----------|------|
+| Linux / macOS | vendored 2.5.2（`ocio-sys` 的 `bundled` 特性，默认开启） | 静态 | 需要 cmake + C++ 编译器 |
+| Windows | MSYS2 `mingw-w64-ucrt-x86_64-opencolorio` | 动态 | 设置 `OCIO_INSTALL_DIR=/ucrt64`、`OCIO_RS_LINK=dynamic` |
 
----
+既没有 `bundled` 特性也没有 `OCIO_RS_ENABLE_REAL=1` 时，`ocio-sys`
+构建为 stub，所有色彩测试直接跳过。`oakrender` 无条件启用 bundled
+特性，因此在 Linux/macOS 上直接 `cargo build` 就会得到真实 OCIO。
 
-## 故障排除
+## 打包
 
-### 找不到 Qt 6
+发行版包在容器中构建（宿主机只需要 Docker/Podman）：
 
-确保 Qt 6 在 PATH 和 CMake prefix path 中：
-
-```bash
-# Linux / macOS
-export PATH="/path/to/qt6/bin:$PATH"
-export CMAKE_PREFIX_PATH="/path/to/qt6"
-
-# Windows（MSYS2）
-export PATH="/ucrt64/bin:$PATH"
+```sh
+tooling/package/build-deb.sh  # Debian 12  → .deb
+tooling/package/build-rpm.sh  # Fedora 41  → .rpm
+tooling/package/build-pkg.sh  # Arch Linux → .pkg.tar.zst
 ```
 
-### 缺少私有头文件
+所有运行时依赖都声明在各自的打包元数据中（`packaging/`、
+`tooling/package/oak.spec`、`tooling/package/PKGBUILD`）——除文档
+列明的系统库外包是自包含的；文件安装位置见
+`docs/project-storage.md`。
 
-如果看到缺少 Qt 私有头文件的错误，请安装对应发行版的私有开发包（例如 Debian/Ubuntu 上的 `qt6-base-private-dev`，Fedora 上的 `qt6-qtbase-private-devel`）。
+## 故障排查
 
-### FFmpeg 版本太旧
-
-Oak 要求 FFmpeg 6.0 或更新版本；版本不足时 CMake 配置阶段会报 `Could NOT find FFMPEG ... (Required is at least version "6.0")`。Ubuntu 24.04+ / Fedora / Arch / Homebrew / MSYS2 自带的版本都足够新。如果发行版过旧，请从源码编译：
-
-```bash
-git clone --branch n8.1.1 --depth 1 https://git.ffmpeg.org/ffmpeg.git ffmpeg-src
-cd ffmpeg-src
-./configure \
-  --prefix="$PWD/../ffmpeg-install" \
-  --enable-static \
-  --disable-shared \
-  --disable-doc \
-  --disable-programs \
-  --disable-avdevice \
-  --disable-network \
-  --enable-pic \
-  --enable-gpl \
-  --enable-version3
-make -j$(nproc)
-make install
-cd ..
-```
-
-然后在 CMake 中加上 `-DFFMPEG_ROOT="$PWD/ffmpeg-install"`。
-
-### 找不到 OpenTimelineIO
-
-OpenTimelineIO 是必需依赖。按你所在平台章节的说明从源码构建，并在 CMake 中加上 `-DOTIO_LOCATION=/path/to/otio-install`。Arch Linux 可直接安装 `opentimelineio` 包。
+- **`oakffmpeg-link` 报 `FFMPEG_DIR` panic** —— 先跑一次
+  `tooling/ffmpeg/build-ffmpeg.sh`；它安装到 `.cache/ffmpeg`，
+  `.cargo/config.toml` 已指向该目录。
+- **IDE 构建失败（RustRover 等）** —— 无法向 cargo 注入环境变量的
+  IDE 可以在 workspace 根放一个 git 忽略的 `.env`，写入
+  `FFMPEG_DIR=...`（编解码库在自定义前缀时再加
+  `PKG_CONFIG_PATH=...`）。
+- **pacman 报 "Operation too slow"** —— MSYS2 镜像偶尔卡顿；
+  `install-deps.sh` 会自动重试三次，手动重跑也会借助 `--needed`
+  断点续装。
+- **Windows：`undefined reference to _fileno/_setmode/__imp___msvcrt_assert`**
+  —— 设置 `RUSTFLAGS="-C link-args=-lmsvcrt"`（见 Windows 章节）。
+- **Windows：出现 MSVC 风格的链接错误** —— 你用的是 MSVC 版 Rust；
+  请改用 MSYS2 自带 Rust（`x86_64-pc-windows-gnu`）。
+- **`gpui/` 目录为空** —— `git submodule update --init --recursive`。
+- **Linux 测试开窗口卡死/失败** —— 使用 Linux 章节的 `xvfb-run`
+  命令。

docs/zh/build_macos-zh.md

@@ -1,5 +1,9 @@
 # macOS 编译指南
 
+> **已过时（2026）：** 本文档描述旧的 C++/CMake 构建。当前 Rust
+> workspace 的构建方法见 [`build.md`](build.md)（英文：
+> [`../build.md`](../build.md)）。
+
 本文档介绍如何在 macOS 上从源代码构建 Oak 视频编辑器。
 
 英文版本请参见 [`build-macos.md`](../build_macos.md)。