oak-editor/docs/zh/build_macos-zh.md

macOS 编译指南

本文档介绍如何在 macOS 上从源代码构建 Oak 视频编辑器。

英文版本请参见 build-macos.md。

---

前置要求

• macOS 12.0 (Monterey) 或更高版本
• Homebrew 包管理器
• Xcode 命令行工具

安装 Xcode 命令行工具

xcode-select --install

---

安装依赖

1. 安装 Homebrew（如果尚未安装）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 安装构建工具和库

brew update
brew install cmake ninja pkg-config

3. 安装 Qt 6

brew install qt@6

将 Qt 6 添加到你的 PATH（建议添加到 ~/.zshrc）：

echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

4. 安装 FFmpeg

brew install ffmpeg

5. 安装图像/色彩库

brew install openimageio opencolorio openexr

6. 安装音频和 XML 库

brew install portaudio expat

7. 安装 Vulkan 后端依赖（可选）

仅在需要 Vulkan 渲染后端时需要。Oak 始终构建 OpenGL 后端，当 Vulkan 不可用时会自动回退到它：

brew install molten-vk vulkan-headers vulkan-loader

让 CMake 能找到 loader，使 find_package(Vulkan) 成功（经常构建的话可以写入 ~/.zshrc）：

export VULKAN_SDK="$(brew --prefix vulkan-loader)"

8. 安装测试框架（可选）

仅在需要构建和运行测试时需要：

brew install googletest

---

编译 OpenTimelineIO（可选）

OpenTimelineIO 支持以 OTIO 格式导入/导出时间线数据。如果你不需要 OTIO 支持，可以跳过此步骤。

# 克隆仓库
git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cd OpenTimelineIO

# 配置并编译
cmake -S . -B build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/install"

cmake --build build
cmake --install build

记下安装路径（例如 ${PWD}/install），稍后在 CMake 配置中需要用到 OTIO_LOCATION 选项。

---

克隆并编译 Oak 视频编辑器

1. 克隆仓库

git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
cd oak

注意： 请务必使用 --recursive 克隆子模块，因为 Oak 依赖于多个作为子模块包含的外部库。

2. 使用 CMake 配置

基础配置（不包含 OTIO）：

cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DOCIO_LOCATION=$(brew --prefix opencolorio)

包含 OTIO 支持的配置：

cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DOCIO_LOCATION=$(brew --prefix opencolorio) \
  -DOTIO_LOCATION=/path/to/otio/install \
  -DBUILD_TESTS=ON

3. 编译

cmake --build build --config Release

编译过程可能需要 10-30 分钟，具体取决于你的硬件配置。

---

运行应用程序

编译成功后，你可以运行 Oak 视频编辑器：

./build/app/oak-editor

或者打开应用程序包（如果已生成）：

open ./build/app/Oak.app

---

运行测试（可选）

如果你使用 -DBUILD_TESTS=ON 构建了项目：

ctest --test-dir build --output-on-failure -C Release

---

编译选项

选项	默认值	说明
BUILD_TESTS	OFF	构建单元测试
BUILD_DOXYGEN	OFF	构建 Doxygen 文档
USE_WERROR	OFF	将警告视为错误
OTIO_LOCATION	-	OpenTimelineIO 安装路径（可选）
OCIO_LOCATION	-	OpenColorIO 安装路径

---

故障排除

找不到 Qt 6

如果 CMake 无法找到 Qt 6，请确保它已在 PATH 中：

export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"
export CMAKE_PREFIX_PATH="/opt/homebrew/opt/qt@6"

对于 Intel Mac，路径可能是 /usr/local/opt/qt@6。

找不到 OpenColorIO

确保指定了正确的 OCIO_LOCATION：

-DOCIO_LOCATION=$(brew --prefix opencolorio)

找不到 OpenImageIO

尝试重新安装 OpenImageIO：

brew reinstall openimageio

PortAudio 问题

如果遇到与音频相关的编译错误：

brew reinstall portaudio
export PKG_CONFIG_PATH="/opt/homebrew/opt/portaudio/lib/pkgconfig:$PKG_CONFIG_PATH"

Apple Silicon (M1/M2/M3) 特定问题

在 Apple Silicon Mac 上，Homebrew 安装到 /opt/homebrew 而不是 /usr/local。确保环境变量设置正确：

export PATH="/opt/homebrew/bin:$PATH"
export LIBRARY_PATH="/opt/homebrew/lib:$LIBRARY_PATH"
export CPATH="/opt/homebrew/include:$CPATH"

---

创建应用程序包

要创建可分发的 .app 包，你可能需要使用 macdeployqt：

/opt/homebrew/opt/qt@6/bin/macdeployqt build/app/Oak.app

这会将所需的 Qt 库打包到应用程序中。

---

卸载

要删除已构建的应用程序：

rm -rf build

要删除 Homebrew 依赖（可选）：

brew uninstall qt@6 ffmpeg openimageio opencolorio openexr portaudio expat googletest