Mike-Solar
66d761b4b7
- app/ no longer includes engine C++ headers nor holds engine C++ types: engine access goes through the oakengine C ABI plus C++ wrappers (oakutil/oaknode.h, oakutil/oakvideo.h) and app-local mirror types (tooltypes, trackreferencehandle, timelinecommonapp, keyframetypes, subtitleapp, serializedlayoutinfoapp, nodevaluehandle, sliderdisplaytypeapp) - engine: new C ABI functions for block/track/clip/transition navigation and predicates, links, caches, waveform/playback, disk folder, sequence_track_list, node_free, footage_is_valid, block_get_track, get_brush; loadotio/saveotio ported to the current engine API - OTIO is now a required dependency: CI and CD build it on every platform, FindOpenTimelineIO fixed for OTIO 0.16/0.19 (the old deps include requirement silently disabled OTIO everywhere), runtime libraries are bundled into packages and copied next to macOS binaries (oak_copy_otio_runtime) - fix ProjectViewModel drag&drop mime read/write size mismatch (segfault) - unify color label naming (k_olive -> "Oak") in the app-side mirror - docs: OTIO required, FFmpeg minimum corrected to 6.0 (en/zh) - gtest suite: 1925 passed, 0 failed
262 lines
4.9 KiB
Markdown
262 lines
4.9 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 格式导入/导出时间线数据，是必需依赖。
|
||
|
||
```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 \
|
||
-DOTIO_FIND_IMATH=ON \
|
||
-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 配置
|
||
|
||
```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
|
||
```
|