Mike-Solar
ae908441c8
- Linux CD builds no longer disable Vulkan: the AppImage, deb, rpm and Arch packages now build and ship liboakvulkan (the AppImage deploys it via linuxdeploy --library so libvulkan is bundled too, and the verify step checks both backend libraries); deb/rpm dependencies gain libvulkan1/vulkan-loader; the Arch PKGBUILD gains vulkan-headers - macOS CD installs vulkan-loader and exports VULKAN_SDK so find_package(Vulkan) locates the Homebrew loader (previously the Vulkan backend silently never built there) - ffmpeg_bridge now installs to the standard lib directory with /../lib RPATH instead of the non-standard ffmpeg_bridge/bin layout (verified: editor, worker, oakgl and oakvulkan all resolve it) - build guides (EN/ZH) document the macOS Vulkan backend dependencies and the VULKAN_SDK variable
271 lines
5.1 KiB
Markdown
271 lines
5.1 KiB
Markdown
# macOS 编译指南
|
||
|
||
本文档介绍如何在 macOS 上从源代码构建 Oak 视频编辑器。
|
||
|
||
英文版本请参见 [`build-macos.md`](../build_macos.md)。
|
||
|
||
---
|
||
|
||
## 前置要求
|
||
|
||
- macOS 12.0 (Monterey) 或更高版本
|
||
- [Homebrew](https://brew.sh/) 包管理器
|
||
- Xcode 命令行工具
|
||
|
||
### 安装 Xcode 命令行工具
|
||
|
||
```bash
|
||
xcode-select --install
|
||
```
|
||
|
||
---
|
||
|
||
## 安装依赖
|
||
|
||
### 1. 安装 Homebrew（如果尚未安装）
|
||
|
||
```bash
|
||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||
```
|
||
|
||
### 2. 安装构建工具和库
|
||
|
||
```bash
|
||
brew update
|
||
brew install cmake ninja pkg-config
|
||
```
|
||
|
||
### 3. 安装 Qt 6
|
||
|
||
```bash
|
||
brew install qt@6
|
||
```
|
||
|
||
将 Qt 6 添加到你的 PATH（建议添加到 `~/.zshrc`）：
|
||
|
||
```bash
|
||
echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.zshrc
|
||
source ~/.zshrc
|
||
```
|
||
|
||
### 4. 安装 FFmpeg
|
||
|
||
```bash
|
||
brew install ffmpeg
|
||
```
|
||
|
||
### 5. 安装图像/色彩库
|
||
|
||
```bash
|
||
brew install openimageio opencolorio openexr
|
||
```
|
||
|
||
### 6. 安装音频和 XML 库
|
||
|
||
```bash
|
||
brew install portaudio expat
|
||
```
|
||
|
||
### 7. 安装 Vulkan 后端依赖（可选）
|
||
|
||
仅在需要 Vulkan 渲染后端时需要。Oak 始终构建 OpenGL 后端，当 Vulkan 不可用时会自动回退到它：
|
||
|
||
```bash
|
||
brew install molten-vk vulkan-headers vulkan-loader
|
||
```
|
||
|
||
让 CMake 能找到 loader，使 `find_package(Vulkan)` 成功（经常构建的话可以写入 `~/.zshrc`）：
|
||
|
||
```bash
|
||
export VULKAN_SDK="$(brew --prefix vulkan-loader)"
|
||
```
|
||
|
||
### 8. 安装测试框架（可选）
|
||
|
||
仅在需要构建和运行测试时需要：
|
||
|
||
```bash
|
||
brew install googletest
|
||
```
|
||
|
||
---
|
||
|
||
## 编译 OpenTimelineIO（可选）
|
||
|
||
OpenTimelineIO 支持以 OTIO 格式导入/导出时间线数据。如果你不需要 OTIO 支持，可以跳过此步骤。
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
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. 克隆仓库
|
||
|
||
```bash
|
||
git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
|
||
cd oak
|
||
```
|
||
|
||
> **注意：** 请务必使用 `--recursive` 克隆子模块，因为 Oak 依赖于多个作为子模块包含的外部库。
|
||
|
||
### 2. 使用 CMake 配置
|
||
|
||
基础配置（不包含 OTIO）：
|
||
|
||
```bash
|
||
cmake -S . -B build -G Ninja \
|
||
-DCMAKE_BUILD_TYPE=Release \
|
||
-DOCIO_LOCATION=$(brew --prefix opencolorio)
|
||
```
|
||
|
||
包含 OTIO 支持的配置：
|
||
|
||
```bash
|
||
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. 编译
|
||
|
||
```bash
|
||
cmake --build build --config Release
|
||
```
|
||
|
||
编译过程可能需要 10-30 分钟，具体取决于你的硬件配置。
|
||
|
||
---
|
||
|
||
## 运行应用程序
|
||
|
||
编译成功后，你可以运行 Oak 视频编辑器：
|
||
|
||
```bash
|
||
./build/app/oak-editor
|
||
```
|
||
|
||
或者打开应用程序包（如果已生成）：
|
||
|
||
```bash
|
||
open ./build/app/Oak.app
|
||
```
|
||
|
||
---
|
||
|
||
## 运行测试（可选）
|
||
|
||
如果你使用 `-DBUILD_TESTS=ON` 构建了项目：
|
||
|
||
```bash
|
||
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 中：
|
||
|
||
```bash
|
||
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`：
|
||
|
||
```bash
|
||
-DOCIO_LOCATION=$(brew --prefix opencolorio)
|
||
```
|
||
|
||
### 找不到 OpenImageIO
|
||
|
||
尝试重新安装 OpenImageIO：
|
||
|
||
```bash
|
||
brew reinstall openimageio
|
||
```
|
||
|
||
### PortAudio 问题
|
||
|
||
如果遇到与音频相关的编译错误：
|
||
|
||
```bash
|
||
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`。确保环境变量设置正确：
|
||
|
||
```bash
|
||
export PATH="/opt/homebrew/bin:$PATH"
|
||
export LIBRARY_PATH="/opt/homebrew/lib:$LIBRARY_PATH"
|
||
export CPATH="/opt/homebrew/include:$CPATH"
|
||
```
|
||
|
||
---
|
||
|
||
## 创建应用程序包
|
||
|
||
要创建可分发的 `.app` 包，你可能需要使用 `macdeployqt`：
|
||
|
||
```bash
|
||
/opt/homebrew/opt/qt@6/bin/macdeployqt build/app/Oak.app
|
||
```
|
||
|
||
这会将所需的 Qt 库打包到应用程序中。
|
||
|
||
---
|
||
|
||
## 卸载
|
||
|
||
要删除已构建的应用程序：
|
||
|
||
```bash
|
||
rm -rf build
|
||
```
|
||
|
||
要删除 Homebrew 依赖（可选）：
|
||
|
||
```bash
|
||
brew uninstall qt@6 ffmpeg openimageio opencolorio openexr portaudio expat googletest
|
||
```
|