dpcs: Update build instructions

.gitignore

@@ -1,5 +1,5 @@
 # CMake artifacts
-/build*/
+/cmake-build-*
 build
 # Doxygen
 

docs/build.md

@@ -201,7 +201,7 @@ ctest --test-dir build --output-on-failure -C Release
 
 ## macOS
 
-macOS is a fully supported platform. See [`build-macos.md`](build-macos.md) for a dedicated, step-by-step guide.
+macOS is now a fully supported platform. See [`build_macos.md`](build_macos.md) for a dedicated, step-by-step guide.
 
 Install dependencies:
 

docs/build_macos.md

@@ -0,0 +1,256 @@
+# macOS Build Guide
+
+This document describes how to build Oak Video Editor from source on macOS.
+
+For the Chinese version, see [`build-macos-zh.md`](zh/build_macos-zh.md).
+
+---
+
+## Prerequisites
+
+- macOS 12.0 (Monterey) or later
+- [Homebrew](https://brew.sh/) package manager
+- Xcode Command Line Tools
+
+### Install Xcode Command Line Tools
+
+```bash
+xcode-select --install
+```
+
+---
+
+## Install Dependencies
+
+### 1. Install Homebrew (if not already installed)
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+### 2. Install Build Tools and Libraries
+
+```bash
+brew update
+brew install cmake ninja pkg-config
+```
+
+### 3. Install Qt 6
+
+```bash
+brew install qt@6
+```
+
+Add Qt 6 to your PATH (you may want to add this to your `~/.zshrc`):
+
+```bash
+echo 'export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### 4. Install FFmpeg
+
+```bash
+brew install ffmpeg
+```
+
+### 5. Install Image/Color Libraries
+
+```bash
+brew install openimageio opencolorio openexr
+```
+
+### 6. Install Audio and XML Libraries
+
+```bash
+brew install portaudio expat
+```
+
+### 7. Install Test Framework (Optional)
+
+Only needed if you plan to build and run tests:
+
+```bash
+brew install googletest
+```
+
+---
+
+## Build OpenTimelineIO (Optional)
+
+OpenTimelineIO enables importing/exporting timeline data in OTIO format. If you don't need OTIO support, you can skip this step.
+
+```bash
+# Clone the repository
+git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
+cd OpenTimelineIO
+
+# Configure and build
+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
+```
+
+Note the installation path (e.g., `${PWD}/install`), you'll need it for the `OTIO_LOCATION` CMake option.
+
+---
+
+## Clone and Build Oak Video Editor
+
+### 1. Clone the Repository
+
+```bash
+git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
+cd oak
+```
+
+> **Note:** Make sure to use `--recursive` to clone submodules, as Oak depends on several external libraries included as submodules.
+
+### 2. Configure with CMake
+
+Basic configuration (without OTIO):
+
+```bash
+cmake -S . -B build -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DOCIO_LOCATION=$(brew --prefix opencolorio)
+```
+
+Configuration with OTIO support:
+
+```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. Build
+
+```bash
+cmake --build build --config Release
+```
+
+The build process may take 10-30 minutes depending on your hardware.
+
+---
+
+## Run the Application
+
+After successful build, you can run Oak Video Editor:
+
+```bash
+./build/app/olive-editor
+```
+
+Or open the app bundle (if generated):
+
+```bash
+open ./build/app/olive-editor.app
+```
+
+---
+
+## Run Tests (Optional)
+
+If you built with `-DBUILD_TESTS=ON`:
+
+```bash
+ctest --test-dir build --output-on-failure -C Release
+```
+
+---
+
+## Build Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `BUILD_TESTS` | `OFF` | Build unit tests |
+| `BUILD_DOXYGEN` | `OFF` | Build Doxygen documentation |
+| `USE_WERROR` | `OFF` | Treat warnings as errors |
+| `OTIO_LOCATION` | - | Path to OpenTimelineIO installation (optional) |
+| `OCIO_LOCATION` | - | Path to OpenColorIO installation |
+
+---
+
+## Troubleshooting
+
+### Qt 6 Not Found
+
+If CMake cannot find Qt 6, ensure it's in your PATH:
+
+```bash
+export PATH="/opt/homebrew/opt/qt@6/bin:$PATH"
+export CMAKE_PREFIX_PATH="/opt/homebrew/opt/qt@6"
+```
+
+For Intel Macs, the path may be `/usr/local/opt/qt@6` instead.
+
+### OpenColorIO Not Found
+
+Make sure to specify the correct `OCIO_LOCATION`:
+
+```bash
+-DOCIO_LOCATION=$(brew --prefix opencolorio)
+```
+
+### OpenImageIO Not Found
+
+Try reinstalling OpenImageIO:
+
+```bash
+brew reinstall openimageio
+```
+
+### PortAudio Issues
+
+If you encounter audio-related build errors:
+
+```bash
+brew reinstall portaudio
+export PKG_CONFIG_PATH="/opt/homebrew/opt/portaudio/lib/pkgconfig:$PKG_CONFIG_PATH"
+```
+
+### Apple Silicon (M1/M2/M3) Specific Issues
+
+On Apple Silicon Macs, Homebrew installs to `/opt/homebrew` instead of `/usr/local`. Make sure your environment variables are set correctly:
+
+```bash
+export PATH="/opt/homebrew/bin:$PATH"
+export LIBRARY_PATH="/opt/homebrew/lib:$LIBRARY_PATH"
+export CPATH="/opt/homebrew/include:$CPATH"
+```
+
+---
+
+## Creating an App Bundle
+
+To create a distributable `.app` bundle, you may need to use `macdeployqt`:
+
+```bash
+/opt/homebrew/opt/qt@6/bin/macdeployqt build/app/olive-editor.app
+```
+
+This will bundle the required Qt libraries into the app.
+
+---
+
+## Uninstall
+
+To remove the built application:
+
+```bash
+rm -rf build
+```
+
+To remove Homebrew dependencies (optional):
+
+```bash
+brew uninstall qt@6 ffmpeg openimageio opencolorio openexr portaudio expat googletest
+```

docs/zh/build.md

@@ -201,7 +201,7 @@ ctest --test-dir build --output-on-failure -C Release
 
 ## macOS
 
-macOS 是正式支持的平台。更详细的逐步指南请参见 [`build-macos-zh.md`](build-macos-zh.md)。
+macOS 现在是正式支持的平台。更详细的逐步指南请参见 [`build_macos-zh.md`](build_macos-zh.md)。
 
 安装依赖：
 

docs/zh/build_macos-zh.md

@@ -0,0 +1,256 @@
+# 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. 安装测试框架（可选）
+
+仅在需要构建和运行测试时需要：
+
+```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/olive-editor
+```
+
+或者打开应用程序包（如果已生成）：
+
+```bash
+open ./build/app/olive-editor.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/olive-editor.app
+```
+
+这会将所需的 Qt 库打包到应用程序中。
+
+---
+
+## 卸载
+
+要删除已构建的应用程序：
+
+```bash
+rm -rf build
+```
+
+要删除 Homebrew 依赖（可选）：
+
+```bash
+brew uninstall qt@6 ffmpeg openimageio opencolorio openexr portaudio expat googletest
+```