dpcs: Update build instructions

2026-07-13 14:32:17 +08:00
parent 43773c430a
commit 2a11988b77
5 changed files with 515 additions and 3 deletions
@@ -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
+```