oak-team/oak-editor
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add build guide and CI.

Browse Source
This commit is contained in:
Mike-Solar
2026-05-21 16:50:17 +08:00
parent a0abf9cfb0
commit 393a9eda63
4 changed files with 277 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/ci.yml
+110 -92
View File
@@ -10,16 +10,22 @@ jobs:
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-2022]
os: [ubuntu-latest, macos-latest, windows-latest]
env:
CMAKE_BUILD_TYPE: Release
RUN_OFX_ITEST: "0"
# Enable plugin smoke tests
# Enable OFX integration tests that require external plugin bundles
RUN_OFX_ITEST: "1"
# Enable plugin subsystem smoke tests
OAK_PLUGIN_SMOKE_TEST: "1"
steps:
- uses: actions/checkout@v4
with:
submodules: 'true'
# ------------------------------------------------------------------
# Linux dependencies
# ------------------------------------------------------------------
- name: Install dependencies (Linux)
if: runner.os == 'Linux'
run: |
@@ -31,6 +37,9 @@ jobs:
libopencolorio-dev libopenimageio-dev libopenexr-dev libexpat1-dev \
portaudio19-dev libgl1-mesa-dev libxkbcommon-dev
# ------------------------------------------------------------------
# macOS dependencies
# ------------------------------------------------------------------
- name: Install dependencies (macOS)
if: runner.os == 'macOS'
run: |
@@ -52,28 +61,31 @@ jobs:
cmake --install OpenTimelineIO/build
echo "OTIO_LOCATION=${PWD}/otio-install" >> "$GITHUB_ENV"
- name: Install Qt (Windows)
# ------------------------------------------------------------------
# Windows dependencies (MSYS2)
# ------------------------------------------------------------------
- name: Setup MSYS2
if: runner.os == 'Windows'
uses: jurplel/install-qt-action@v4
uses: msys2/setup-msys2@v2
with:
version: 6.5.3
cache: true
tools: 'tools_ninja'
- name: Install dependencies (Windows)
if: runner.os == 'Windows'
shell: pwsh
run: |
choco install -y ninja
$env:VCPKG_ROOT = "C:\vcpkg"
& "$env:VCPKG_ROOT\vcpkg.exe" install ffmpeg openimageio opencolorio openexr expat portaudio --triplet x64-windows
echo "VCPKG_ROOT=$env:VCPKG_ROOT" | Out-File -FilePath $env:GITHUB_ENV -Append
echo "CMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake" | Out-File -FilePath $env:GITHUB_ENV -Append
- name: Setup MSVC (Windows)
if: runner.os == 'Windows'
uses: ilammy/msvc-dev-cmd@v1
msystem: MINGW64
update: true
install: >-
mingw-w64-x86_64-cmake
mingw-w64-x86_64-ninja
mingw-w64-x86_64-gcc
mingw-w64-x86_64-qt6-base
mingw-w64-x86_64-qt6-tools
mingw-w64-x86_64-ffmpeg
mingw-w64-x86_64-openimageio
mingw-w64-x86_64-opencolorio
mingw-w64-x86_64-openexr
mingw-w64-x86_64-expat
mingw-w64-x86_64-portaudio
# ------------------------------------------------------------------
# Configure
# ------------------------------------------------------------------
- name: Configure (Linux)
if: runner.os == 'Linux'
run: |
@@ -95,132 +107,138 @@ jobs:
- name: Configure (Windows)
if: runner.os == 'Windows'
shell: pwsh
shell: msys2 {0}
run: |
$toolchain = "$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake"
$ninja = "$env:ChocolateyInstall\bin\ninja.exe"
cmake -S . -B build -G Ninja `
-DBUILD_TESTS=ON `
-DBUILD_QT6=ON `
-DCMAKE_BUILD_TYPE=$env:CMAKE_BUILD_TYPE `
-DCMAKE_TOOLCHAIN_FILE=$toolchain `
-DCMAKE_MAKE_PROGRAM=$ninja `
-DCMAKE_PREFIX_PATH=$env:Qt6_DIR
cmake -S . -B build -G Ninja \
-DBUILD_TESTS=ON \
-DBUILD_QT6=ON \
-DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
# ------------------------------------------------------------------
# Build Oak
# ------------------------------------------------------------------
- name: Build
if: runner.os != 'Windows'
run: cmake --build build --config ${{ env.CMAKE_BUILD_TYPE }}
- name: Build OpenFX misc plugins (Linux, optional)
if: runner.os == 'Linux' && env.RUN_OFX_ITEST == '1'
- name: Build (Windows)
if: runner.os == 'Windows'
shell: msys2 {0}
run: cmake --build build --config ${{ env.CMAKE_BUILD_TYPE }}
# ------------------------------------------------------------------
# Clone and build OpenFX-Misc plugins (used by OFX integration tests)
# ------------------------------------------------------------------
- name: Clone OpenFX-Misc
run: git clone --recursive --depth 1 https://github.com/NatronGitHub/openfx-misc.git
- name: Build OpenFX-Misc plugins (Linux / macOS)
if: runner.os != 'Windows'
run: |
git clone --depth 1 https://github.com/NatronGitHub/openfx-misc.git
cmake -S openfx-misc -B openfx-misc/build -G Ninja \
-DCMAKE_BUILD_TYPE=Release
cmake --build openfx-misc/build
- name: Build OpenFX-Misc plugins (Windows)
if: runner.os == 'Windows'
shell: msys2 {0}
run: |
cmake -S openfx-misc -B openfx-misc/build -G Ninja \
-DCMAKE_BUILD_TYPE=Release
cmake --build openfx-misc/build
- name: Export OFX test environment
if: runner.os != 'Windows'
run: |
echo "OAK_OFX_ITEST=1" >> "$GITHUB_ENV"
echo "OAK_OFX_PLUGIN_PATH=${PWD}/openfx-misc/build" >> "$GITHUB_ENV"
echo "OAK_OFX_PLUGIN_ID=net.sf.openfx.ChromaKeyerPlugin" >> "$GITHUB_ENV"
- name: Build OpenFX misc plugins (macOS, optional)
if: runner.os == 'macOS' && env.RUN_OFX_ITEST == '1'
run: |
git clone --depth 1 https://github.com/NatronGitHub/openfx-misc.git
cmake -S openfx-misc -B openfx-misc/build -G Ninja \
-DCMAKE_BUILD_TYPE=Release
cmake --build openfx-misc/build
echo "OAK_OFX_ITEST=1" >> "$GITHUB_ENV"
echo "OAK_OFX_PLUGIN_PATH=${PWD}/openfx-misc/build" >> "$GITHUB_ENV"
echo "OAK_OFX_PLUGIN_ID=net.sf.openfx.ChromaKeyerPlugin" >> "$GITHUB_ENV"
- name: Build OpenFX misc plugins (Windows, optional)
if: runner.os == 'Windows' && env.RUN_OFX_ITEST == '1'
- name: Export OFX test environment (Windows)
if: runner.os == 'Windows'
shell: pwsh
run: |
git clone --depth 1 https://github.com/NatronGitHub/openfx-misc.git
cmake -S openfx-misc -B openfx-misc/build -G Ninja `
-DCMAKE_BUILD_TYPE=Release
cmake --build openfx-misc/build
"OAK_OFX_ITEST=1" | Out-File -FilePath $env:GITHUB_ENV -Append
"OAK_OFX_PLUGIN_PATH=$env:GITHUB_WORKSPACE\\openfx-misc\\build" | Out-File -FilePath $env:GITHUB_ENV -Append
"OAK_OFX_PLUGIN_PATH=$env:GITHUB_WORKSPACE\openfx-misc\build" | Out-File -FilePath $env:GITHUB_ENV -Append
"OAK_OFX_PLUGIN_ID=net.sf.openfx.ChromaKeyerPlugin" | Out-File -FilePath $env:GITHUB_ENV -Append
# ------------------------------------------------------------------
# Run all tests (including previously environment-gated OFX tests)
# ------------------------------------------------------------------
- name: Test (Linux)
if: runner.os == 'Linux'
env:
QT_QPA_PLATFORM: offscreen
OAK_PLUGIN_SMOKE_TEST: "1"
run: ctest --test-dir build --output-on-failure -C ${{ env.CMAKE_BUILD_TYPE }}
- name: Test (macOS/Windows)
if: runner.os != 'Linux'
env:
OAK_PLUGIN_SMOKE_TEST: "1"
- name: Test (macOS)
if: runner.os == 'macOS'
run: ctest --test-dir build --output-on-failure -C ${{ env.CMAKE_BUILD_TYPE }}
- name: Test (Windows)
if: runner.os == 'Windows'
shell: msys2 {0}
run: ctest --test-dir build --output-on-failure -C ${{ env.CMAKE_BUILD_TYPE }}
# ------------------------------------------------------------------
# Filtered gtest runs for clearer CI output
# ------------------------------------------------------------------
- name: Plugin Smoke Tests (Linux)
if: runner.os == 'Linux'
env:
QT_QPA_PLATFORM: offscreen
OAK_PLUGIN_SMOKE_TEST: "1"
run: |
echo "Running plugin subsystem smoke tests..."
./build/tests/gtest/olive-gtest --gtest_filter="PluginSmoke*"
run: ./build/tests/gtest/olive-gtest --gtest_filter="PluginSmoke*"
- name: Plugin Smoke Tests (macOS)
if: runner.os == 'macOS'
env:
OAK_PLUGIN_SMOKE_TEST: "1"
run: |
echo "Running plugin subsystem smoke tests..."
./build/tests/gtest/olive-gtest --gtest_filter="PluginSmoke*"
run: ./build/tests/gtest/olive-gtest --gtest_filter="PluginSmoke*"
- name: Plugin Smoke Tests (Windows)
if: runner.os == 'Windows'
shell: pwsh
shell: msys2 {0}
run: ./build/tests/gtest/olive-gtest --gtest_filter="PluginSmoke*"
- name: OFX Integration Tests (Linux)
if: runner.os == 'Linux'
env:
OAK_PLUGIN_SMOKE_TEST: "1"
run: |
Write-Host "Running plugin subsystem smoke tests..."
& "$env:GITHUB_WORKSPACE\build\tests\gtest\olive-gtest.exe" --gtest_filter="PluginSmoke*"
QT_QPA_PLATFORM: offscreen
run: ./build/tests/gtest/olive-gtest --gtest_filter="PluginIntegration.*:PluginMisc.*"
- name: OFX Integration Tests (macOS)
if: runner.os == 'macOS'
run: ./build/tests/gtest/olive-gtest --gtest_filter="PluginIntegration.*:PluginMisc.*"
- name: OFX Integration Tests (Windows)
if: runner.os == 'Windows'
shell: msys2 {0}
run: ./build/tests/gtest/olive-gtest --gtest_filter="PluginIntegration.*:PluginMisc.*"
- name: Audio Smoke Tests (Linux)
if: runner.os == 'Linux'
env:
QT_QPA_PLATFORM: offscreen
run: |
echo "Running audio subsystem smoke tests..."
./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
run: ./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
- name: Audio Smoke Tests (macOS)
if: runner.os == 'macOS'
run: |
echo "Running audio subsystem smoke tests..."
./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
run: ./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
- name: Audio Smoke Tests (Windows)
if: runner.os == 'Windows'
shell: pwsh
run: |
Write-Host "Running audio subsystem smoke tests..."
& "$env:GITHUB_WORKSPACE\build\tests\gtest\olive-gtest.exe" --gtest_filter="AudioSmoke*"
shell: msys2 {0}
run: ./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
- name: Viewer Smoke Tests (Linux)
if: runner.os == 'Linux'
env:
QT_QPA_PLATFORM: offscreen
run: |
echo "Running viewer/preview subsystem smoke tests..."
./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
run: ./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
- name: Viewer Smoke Tests (macOS)
if: runner.os == 'macOS'
run: |
echo "Running viewer/preview subsystem smoke tests..."
./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
run: ./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
- name: Viewer Smoke Tests (Windows)
if: runner.os == 'Windows'
shell: pwsh
run: |
Write-Host "Running viewer/preview subsystem smoke tests..."
& "$env:GITHUB_WORKSPACE\build\tests\gtest\olive-gtest.exe" --gtest_filter="ViewerSmoke*"
shell: msys2 {0}
run: ./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
README.md
+3 -10
View File
@@ -15,13 +15,6 @@ The original author compiled following binaries:
- [0.1.0 alpha](https://github.com/olive-editor/olive/releases/tag/0.1.0)
- [0.2.0 unstable development build](https://github.com/olive-editor/olive/releases/tag/0.2.0-nightly)
## OpenFX Support TODO
- Implement plugin discovery/loading from a given path and populate the cache (currently creates host/cache only). `app/pluginSupport/OliveHost.cpp`
- Wire output clip image storage: allocate a backing buffer, set `kOfxImagePropData`, and update bounds/rowBytes before render. `app/pluginSupport/OliveClip.cpp`
- Provide real input clip image fetches (currently returns an empty `Image` for inputs). `app/pluginSupport/OliveClip.cpp`
- Ensure render path sets per-frame output data and handles ROD/bounds correctly. `app/render/plugin/pluginrenderer.cpp`
- Add missing param instance types (String, Double3D/Integer3D, Group/Page, Custom/Bytes) and mapping to node inputs. `app/pluginSupport/OlivePluginInstance.cpp`, `app/node/plugins/Plugin.cpp`
- Implement `editBegin`/`editEnd`, progress, and timeline hooks instead of stubs. `app/pluginSupport/OlivePluginInstance.cpp`, `app/pluginSupport/OlivePluginInstance.h`
- Integrate persistent message handling with the app UI (currently TODO placeholders). `app/pluginSupport/OlivePluginInstance.cpp`
- Decide and enforce project extent/fielding behavior instead of the current placeholder comment. `app/pluginSupport/OlivePluginInstance.cpp`
- Add OpenGL texture render suite support or explicitly disable it (currently `loadTexture` returns null). `app/pluginSupport/OliveClip.h`
## Building from Source
See [`docs/build.md`](docs/build.md) for build instructions on Windows (MSYS2), Linux (Debian/Ubuntu, Fedora, Arch Linux), and macOS.
docs/build.md
+163 -26
View File
@@ -1,7 +1,6 @@
# Build Guide
This document describes how to build Oak Video Editor from source. For Chinese, see
[`docs/build-zh.md`](docs/build-zh.md).
This document describes how to build Oak Video Editor from source on Windows, Linux, and macOS.
## Prerequisites
@@ -17,14 +16,70 @@ This document describes how to build Oak Video Editor from source. For Chinese,
- OpenGL headers
- XKB common (Linux)
## Linux (Ubuntu/Debian)
---
## Windows (MSYS2)
This guide uses [MSYS2](https://www.msys2.org/) with the MinGW-w64 toolchain.
### 1. Install MSYS2
Download and install MSYS2 from [https://www.msys2.org/](https://www.msys2.org/). Then open the **MSYS2 MinGW 64-bit** terminal.
### 2. Install Dependencies
```bash
pacman -Syu
pacman -S --needed \
mingw-w64-x86_64-cmake \
mingw-w64-x86_64-ninja \
mingw-w64-x86_64-qt6-base \
mingw-w64-x86_64-qt6-tools \
mingw-w64-x86_64-ffmpeg \
mingw-w64-x86_64-openimageio \
mingw-w64-x86_64-opencolorio \
mingw-w64-x86_64-openexr \
mingw-w64-x86_64-expat \
mingw-w64-x86_64-portaudio \
mingw-w64-x86_64-gcc
```
> **Note:** Qt 6 private headers may require additional packages depending on the MSYS2 repository state. If CMake reports missing private headers, install `mingw-w64-x86_64-qt6-base-private` if available.
### 3. Clone and Build
```bash
# Clone the repository
git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
cd oak
# Configure
cmake -S . -B build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DBUILD_QT6=ON
# Build
cmake --build build --config Release
```
### 4. Run Tests (Optional)
```bash
ctest --test-dir build --output-on-failure -C Release
```
---
## Linux
### Debian / Ubuntu
Install dependencies:
```bash
sudo apt-get update
sudo apt-get install -y \
ninja-build pkg-config \
cmake ninja-build pkg-config \
qt6-base-dev qt6-base-dev-tools qt6-base-private-dev qt6-tools-dev qt6-tools-dev-tools \
libavcodec-dev libavformat-dev libavfilter-dev libavutil-dev libswscale-dev libswresample-dev \
libopencolorio-dev libopenimageio-dev libopenexr-dev libexpat1-dev \
@@ -44,16 +99,84 @@ Run tests:
ctest --test-dir build --output-on-failure -C Release
```
### Fedora
Install dependencies:
```bash
sudo dnf install -y \
cmake ninja-build pkgconf-pkg-config \
qt6-qtbase-devel qt6-qtbase-private-devel qt6-qttools-devel \
ffmpeg-devel \
OpenImageIO-devel \
OpenColorIO-devel \
openexr-devel \
expat-devel \
portaudio-devel \
mesa-libGL-devel \
libxkbcommon-devel \
gcc-c++
```
Configure and build:
```bash
cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON
cmake --build build --config Release
```
Run tests:
```bash
ctest --test-dir build --output-on-failure -C Release
```
### Arch Linux
Install dependencies:
```bash
sudo pacman -Syu
sudo pacman -S --needed \
cmake ninja pkgconf \
qt6-base qt6-tools \
ffmpeg \
openimageio \
opencolorio \
openexr \
expat \
portaudio \
mesa \
libxkbcommon \
gcc
```
> **Note:** On Arch Linux, Qt 6 private headers are included in the `qt6-base` package.
Configure and build:
```bash
cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON
cmake --build build --config Release
```
Run tests:
```bash
ctest --test-dir build --output-on-failure -C Release
```
---
## macOS (Non-Official Support)
Note: macOS support is **non-official**. We only run CI automation on macOS
and do not perform manual testing.
Note: macOS support is **non-official**. We only run CI automation on macOS and do not perform manual testing.
Install dependencies:
```bash
brew update
brew install ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat
brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat
```
Build OpenTimelineIO (optional, required for OTIO support):
@@ -89,30 +212,44 @@ Run tests:
ctest --test-dir build --output-on-failure -C Release
```
## Windows
---
Install Qt 6 (system installer or CI action). Use vcpkg for dependencies.
## Build Options
```powershell
choco install -y ninja
$env:VCPKG_ROOT = "C:\vcpkg"
& "$env:VCPKG_ROOT\vcpkg.exe" install ffmpeg openimageio opencolorio openexr expat portaudio --triplet x64-windows
| Option | Default | Description |
|--------|---------|-------------|
| `BUILD_TESTS` | `OFF` | Build unit tests |
| `BUILD_DOXYGEN` | `OFF` | Build Doxygen documentation |
| `USE_WERROR` | `OFF` | Treat warnings as errors |
| `BUILD_QT6` | `ON` | Build with Qt 6 instead of Qt 5 |
| `OTIO_LOCATION` | - | Path to OpenTimelineIO installation (optional) |
| `OCIO_LOCATION` | - | Path to OpenColorIO installation |
---
## Troubleshooting
### Qt 6 Not Found
Ensure Qt 6 is in your PATH and CMake prefix path:
```bash
# Linux / macOS
export PATH="/path/to/qt6/bin:$PATH"
export CMAKE_PREFIX_PATH="/path/to/qt6"
# Windows (MSYS2)
export PATH="/mingw64/bin:$PATH"
```
Configure and build:
### Missing Private Headers
```powershell
cmake -S . -B build -G Ninja `
-DBUILD_TESTS=ON `
-DBUILD_QT6=ON `
-DCMAKE_BUILD_TYPE=Release `
-DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake" `
-DCMAKE_PREFIX_PATH="$env:Qt6_DIR"
cmake --build build --config Release
```
If you see errors about missing Qt private headers, install the corresponding private development package for your distribution (e.g., `qt6-base-private-dev` on Debian/Ubuntu, `qt6-qtbase-private-devel` on Fedora).
Run tests:
### FFmpeg Not Found
```powershell
ctest --test-dir build --output-on-failure -C Release
Make sure FFmpeg development libraries are installed and `pkg-config` can locate them:
```bash
pkg-config --exists libavcodec && echo "Found" || echo "Not found"
```
docs/rgbaf32-global-plan.md → docs/zh/rgbaf32-global-plan.md
View File