diff --git a/.gitignore b/.gitignore index 7b8ac41c9..9b0d97838 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # CMake artifacts -/build*/ +/cmake-build-* build # Doxygen diff --git a/docs/build.md b/docs/build.md index 6babc7477..fd9f83039 100644 --- a/docs/build.md +++ b/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: diff --git a/docs/build_macos.md b/docs/build_macos.md new file mode 100644 index 000000000..b6885eed7 --- /dev/null +++ b/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 +``` diff --git a/docs/zh/build.md b/docs/zh/build.md index be58e55ec..6346fbd9f 100644 --- a/docs/zh/build.md +++ b/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)。 安装依赖： diff --git a/docs/zh/build_macos-zh.md b/docs/zh/build_macos-zh.md new file mode 100644 index 000000000..4cc2f7464 --- /dev/null +++ b/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 +```