docs: add build guide and CI.

.github/workflows/ci.yml

@@ -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 OFX integration tests that require external plugin bundles
-      # Enable plugin smoke tests
+      RUN_OFX_ITEST: "1"
+      # Enable plugin subsystem smoke tests
       OAK_PLUGIN_SMOKE_TEST: "1"
+
     steps:
       - uses: actions/checkout@v4
-        with: 
+        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
+          msystem: MINGW64
-          cache: true
+          update: true
-          tools: 'tools_ninja'
+          install: >-
-
+            mingw-w64-x86_64-cmake
-      - name: Install dependencies (Windows)
+            mingw-w64-x86_64-ninja
-        if: runner.os == 'Windows'
+            mingw-w64-x86_64-gcc
-        shell: pwsh
+            mingw-w64-x86_64-qt6-base
-        run: |
+            mingw-w64-x86_64-qt6-tools
-          choco install -y ninja
+            mingw-w64-x86_64-ffmpeg
-          $env:VCPKG_ROOT = "C:\vcpkg"
+            mingw-w64-x86_64-openimageio
-          & "$env:VCPKG_ROOT\vcpkg.exe" install ffmpeg openimageio opencolorio openexr expat portaudio --triplet x64-windows
+            mingw-w64-x86_64-opencolorio
-          echo "VCPKG_ROOT=$env:VCPKG_ROOT" | Out-File -FilePath $env:GITHUB_ENV -Append
+            mingw-w64-x86_64-openexr
-          echo "CMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake" | Out-File -FilePath $env:GITHUB_ENV -Append
+            mingw-w64-x86_64-expat
-
+            mingw-w64-x86_64-portaudio
-      - name: Setup MSVC (Windows)
-        if: runner.os == 'Windows'
-        uses: ilammy/msvc-dev-cmd@v1
 
+      # ------------------------------------------------------------------
+      # 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"
+          cmake -S . -B build -G Ninja \
-          $ninja = "$env:ChocolateyInstall\bin\ninja.exe"
+            -DBUILD_TESTS=ON \
-          cmake -S . -B build -G Ninja `
+            -DBUILD_QT6=ON \
-            -DBUILD_TESTS=ON `
+            -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-            -DBUILD_QT6=ON `
-            -DCMAKE_BUILD_TYPE=$env:CMAKE_BUILD_TYPE `
-            -DCMAKE_TOOLCHAIN_FILE=$toolchain `
-            -DCMAKE_MAKE_PROGRAM=$ninja `
-            -DCMAKE_PREFIX_PATH=$env:Qt6_DIR
 
+      # ------------------------------------------------------------------
+      # Build Oak
+      # ------------------------------------------------------------------
       - name: Build
+        if: runner.os != 'Windows'
         run: cmake --build build --config ${{ env.CMAKE_BUILD_TYPE }}
 
-      - name: Build OpenFX misc plugins (Linux, optional)
+      - name: Build (Windows)
-        if: runner.os == 'Linux' && env.RUN_OFX_ITEST == '1'
+        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)
+      - name: Export OFX test environment (Windows)
-        if: runner.os == 'macOS' && env.RUN_OFX_ITEST == '1'
+        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
-          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'
         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)
+      - name: Test (macOS)
-        if: runner.os != 'Linux'
+        if: runner.os == 'macOS'
-        env:
-          OAK_PLUGIN_SMOKE_TEST: "1"
         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: ./build/tests/gtest/olive-gtest --gtest_filter="PluginSmoke*"
-        run: |
-          echo "Running plugin subsystem smoke tests..."
-          ./build/tests/gtest/olive-gtest --gtest_filter="PluginSmoke*"
 
       - name: Plugin Smoke Tests (macOS)
         if: runner.os == 'macOS'
-        env:
+        run: ./build/tests/gtest/olive-gtest --gtest_filter="PluginSmoke*"
-          OAK_PLUGIN_SMOKE_TEST: "1"
-        run: |
-          echo "Running plugin subsystem smoke tests..."
-          ./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"
+          QT_QPA_PLATFORM: offscreen
-        run: |
+        run: ./build/tests/gtest/olive-gtest --gtest_filter="PluginIntegration.*:PluginMisc.*"
-          Write-Host "Running plugin subsystem smoke tests..."
+
-          & "$env:GITHUB_WORKSPACE\build\tests\gtest\olive-gtest.exe" --gtest_filter="PluginSmoke*"
+      - 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: |
+        run: ./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
-          echo "Running audio subsystem smoke tests..."
-          ./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
 
       - name: Audio Smoke Tests (macOS)
         if: runner.os == 'macOS'
-        run: |
+        run: ./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
-          echo "Running audio subsystem smoke tests..."
-          ./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
 
       - name: Audio Smoke Tests (Windows)
         if: runner.os == 'Windows'
-        shell: pwsh
+        shell: msys2 {0}
-        run: |
+        run: ./build/tests/gtest/olive-gtest --gtest_filter="AudioSmoke*"
-          Write-Host "Running audio subsystem smoke tests..."
-          & "$env:GITHUB_WORKSPACE\build\tests\gtest\olive-gtest.exe" --gtest_filter="AudioSmoke*"
 
       - name: Viewer Smoke Tests (Linux)
         if: runner.os == 'Linux'
         env:
           QT_QPA_PLATFORM: offscreen
-        run: |
+        run: ./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
-          echo "Running viewer/preview subsystem smoke tests..."
-          ./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
 
       - name: Viewer Smoke Tests (macOS)
         if: runner.os == 'macOS'
-        run: |
+        run: ./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
-          echo "Running viewer/preview subsystem smoke tests..."
-          ./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
 
       - name: Viewer Smoke Tests (Windows)
         if: runner.os == 'Windows'
-        shell: pwsh
+        shell: msys2 {0}
-        run: |
+        run: ./build/tests/gtest/olive-gtest --gtest_filter="ViewerSmoke*"
-          Write-Host "Running viewer/preview subsystem smoke tests..."
-          & "$env:GITHUB_WORKSPACE\build\tests\gtest\olive-gtest.exe" --gtest_filter="ViewerSmoke*"

README.md

@@ -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
+## Building from Source
-- 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`
+See [`docs/build.md`](docs/build.md) for build instructions on Windows (MSYS2), Linux (Debian/Ubuntu, Fedora, Arch Linux), and macOS.
-- 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`

docs/build.md

@@ -1,7 +1,6 @@
 # Build Guide
 
-This document describes how to build Oak Video Editor from source. For Chinese, see
+This document describes how to build Oak Video Editor from source on Windows, Linux, and macOS.
-[`docs/build-zh.md`](docs/build-zh.md).
 
 ## 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
+Note: macOS support is **non-official**. We only run CI automation on macOS and do not perform manual testing.
-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
+| Option | Default | Description |
-choco install -y ninja
+|--------|---------|-------------|
-$env:VCPKG_ROOT = "C:\vcpkg"
+| `BUILD_TESTS` | `OFF` | Build unit tests |
-& "$env:VCPKG_ROOT\vcpkg.exe" install ffmpeg openimageio opencolorio openexr expat portaudio --triplet x64-windows
+| `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
+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).
-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
-```
 
-Run tests:
+### FFmpeg Not Found
 
-```powershell
+Make sure FFmpeg development libraries are installed and `pkg-config` can locate them:
-ctest --test-dir build --output-on-failure -C Release
+
+```bash
+pkg-config --exists libavcodec && echo "Found" || echo "Not found"
 ```