oak-team/oak-editor
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
oak-editor/docs/build.md
T
Mike-Solar 66d761b4b7 R8: finish app/ pure C ABI migration (P3-P9) and make OTIO required 
- app/ no longer includes engine C++ headers nor holds engine C++ types:
  engine access goes through the oakengine C ABI plus C++ wrappers
  (oakutil/oaknode.h, oakutil/oakvideo.h) and app-local mirror types
  (tooltypes, trackreferencehandle, timelinecommonapp, keyframetypes,
  subtitleapp, serializedlayoutinfoapp, nodevaluehandle, sliderdisplaytypeapp)
- engine: new C ABI functions for block/track/clip/transition navigation
  and predicates, links, caches, waveform/playback, disk folder,
  sequence_track_list, node_free, footage_is_valid, block_get_track,
  get_brush; loadotio/saveotio ported to the current engine API
- OTIO is now a required dependency: CI and CD build it on every
  platform, FindOpenTimelineIO fixed for OTIO 0.16/0.19 (the old deps
  include requirement silently disabled OTIO everywhere), runtime
  libraries are bundled into packages and copied next to macOS binaries
  (oak_copy_otio_runtime)
- fix ProjectViewModel drag&drop mime read/write size mismatch (segfault)
- unify color label naming (k_olive -> "Oak") in the app-side mirror
- docs: OTIO required, FFmpeg minimum corrected to 6.0 (en/zh)
- gtest suite: 1925 passed, 0 failed
2026-07-31 22:46:52 +08:00

9.1 KiB
Raw Permalink Blame History

Build Guide

This document describes how to build Oak Video Editor from source on Windows, Linux, and macOS.

Prerequisites

  • CMake 3.20+
  • Ninja (recommended)
  • Qt 6 (with private headers)
  • FFmpeg 6.0+ development libraries
  • OpenTimelineIO (0.16+, built from source below — no distro package on most platforms)
  • OpenImageIO
  • OpenColorIO (2.x)
  • OpenEXR
  • Expat
  • PortAudio
  • OpenGL headers
  • Vulkan SDK (optional, required for the Vulkan render backend)
  • XKB common (Linux)

Windows (MSYS2)

This guide uses MSYS2 with the UCRT64 toolchain.

1. Install MSYS2

Download and install MSYS2 from https://www.msys2.org/. Then open the MSYS2 UCRT64 terminal.

2. Install Dependencies

pacman -Syu
pacman -S --needed \
  mingw-w64-ucrt-x86_64-cmake \
  mingw-w64-ucrt-x86_64-ninja \
  mingw-w64-ucrt-x86_64-qt6-base \
  mingw-w64-ucrt-x86_64-qt6-tools \
  mingw-w64-ucrt-x86_64-ffmpeg \
  mingw-w64-ucrt-x86_64-openimageio \
  mingw-w64-ucrt-x86_64-opencolorio \
  mingw-w64-ucrt-x86_64-openexr \
  mingw-w64-ucrt-x86_64-fmt \
  mingw-w64-ucrt-x86_64-expat \
  mingw-w64-ucrt-x86_64-portaudio \
  mingw-w64-ucrt-x86_64-vulkan-headers \
  mingw-w64-ucrt-x86_64-vulkan-loader \
  mingw-w64-ucrt-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-ucrt-x86_64-qt6-base-private if available.

3. Build OpenTimelineIO (required)

There is no MSYS2 package for OpenTimelineIO, so build it from source:

git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DOTIO_FIND_IMATH=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
cmake --build OpenTimelineIO/build
cmake --install OpenTimelineIO/build

4. Clone and Build

# 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 \
  -DOTIO_LOCATION="/path/to/otio-install" \
  -DBUILD_QT6=ON

# Build
cmake --build build --config Release

5. Run Tests (Optional)

ctest --test-dir build --output-on-failure -C Release

Linux

Debian / Ubuntu

Install dependencies (Ubuntu 24.04+ ships FFmpeg 6.1, which satisfies the 6.0 minimum; on older releases build FFmpeg from source as described in Troubleshooting):

sudo apt-get update
sudo apt-get install -y \
  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 libavutil-dev libswscale-dev libswresample-dev libavfilter-dev \
  libopencolorio-dev libopenimageio-dev libopenexr-dev libexpat1-dev \
  portaudio19-dev libgl1-mesa-dev libvulkan-dev libxkbcommon-dev

Build OpenTimelineIO (required, no distro package):

git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DOTIO_FIND_IMATH=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
cmake --build OpenTimelineIO/build
cmake --install OpenTimelineIO/build

Configure and build:

cmake -S . -B build -G Ninja \
  -DBUILD_TESTS=ON -DBUILD_QT6=ON \
  -DOTIO_LOCATION="$PWD/otio-install"
cmake --build build --config Release

Run tests:

ctest --test-dir build --output-on-failure -C Release

Fedora

Install dependencies:

sudo dnf install -y \
  cmake ninja-build pkgconf-pkg-config \
  qt6-qtbase-devel qt6-qtbase-private-devel qt6-qttools-devel \
  ffmpeg-free-devel \
  OpenImageIO-devel \
  OpenColorIO-devel \
  openexr-devel \
  expat-devel \
  portaudio-devel \
  mesa-libGL-devel \
  vulkan-headers \
  vulkan-loader-devel \
  libxkbcommon-devel \
  gcc-c++ \
  bzip2-devel

Build OpenTimelineIO (required, no distro package):

git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DOTIO_FIND_IMATH=ON \
  -DOTIO_FIND_IMATH=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
cmake --build OpenTimelineIO/build
cmake --install OpenTimelineIO/build

Configure and build:

cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
  -DOTIO_LOCATION="$PWD/otio-install"
cmake --build build --config Release

Run tests:

ctest --test-dir build --output-on-failure -C Release

Arch Linux

Install dependencies:

sudo pacman -Syu
sudo pacman -S --needed \
  cmake ninja pkgconf \
  qt6-base qt6-tools \
  ffmpeg \
  openimageio \
  opencolorio \
  openexr \
  expat \
  portaudio \
  opentimelineio \
  mesa \
  vulkan-headers \
  vulkan-icd-loader \
  libxkbcommon \
  fmt \
  gcc

Note: On Arch Linux, Qt 6 private headers are included in the qt6-base package.

Configure and build:

cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON
cmake --build build --config Release

Run tests:

ctest --test-dir build --output-on-failure -C Release

macOS

macOS is now a fully supported platform. See build_macos.md for a dedicated, step-by-step guide.

Install dependencies:

brew update
brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader

Build OpenTimelineIO (required):

git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DOTIO_FIND_IMATH=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
cmake --build OpenTimelineIO/build
cmake --install OpenTimelineIO/build

Configure and build:

export PATH="$(brew --prefix qt@6)/bin:$PATH"
export CMAKE_PREFIX_PATH="$(brew --prefix qt@6)"
export OTIO_LOCATION="${PWD}/otio-install"
export OCIO_LOCATION="$(brew --prefix opencolorio)"
# Let CMake's FindVulkan locate the Homebrew Vulkan loader (optional,
# enables the Vulkan render backend)
export VULKAN_SDK="$(brew --prefix vulkan-loader)"

cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
  -DOTIO_LOCATION="${OTIO_LOCATION}" \
  -DOCIO_LOCATION="${OCIO_LOCATION}"
cmake --build build --config Release

Run tests:

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
BUILD_QT6 ON Build with Qt 6 instead of Qt 5
OTIO_LOCATION - Path to OpenTimelineIO installation (required)
OAK_BUNDLE_OTIO ON Install OTIO runtime libraries alongside Oak (set OFF for distro-native packaging where opentimelineio is a package dependency, e.g. Arch)
OCIO_LOCATION - Path to OpenColorIO installation
OAK_ENABLE_DYNAMIC_RENDER_BACKEND ON Build dynamic render backend libraries (liboakgl.so / liboakvulkan.so)

Troubleshooting

Qt 6 Not Found

Ensure Qt 6 is in your PATH and CMake prefix path:

# Linux / macOS
export PATH="/path/to/qt6/bin:$PATH"
export CMAKE_PREFIX_PATH="/path/to/qt6"

# Windows (MSYS2)
export PATH="/ucrt64/bin:$PATH"

Missing Private Headers

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).

FFmpeg Not Found

Make sure FFmpeg development libraries are installed and pkg-config can locate them:

pkg-config --exists libavcodec && echo "Found" || echo "Not found"

FFmpeg Version Too Old

Oak requires FFmpeg 6.0 or newer; CMake configure fails with Could NOT find FFMPEG (missing: FFMPEG_VERSION) (Required is at least version "6.0") on older versions. Ubuntu 24.04+ / Fedora / Arch / Homebrew / MSYS2 all ship new enough FFmpeg. If your distro is older, build from source:

git clone --branch n8.1.1 --depth 1 https://git.ffmpeg.org/ffmpeg.git ffmpeg-src
cd ffmpeg-src
./configure \
  --prefix="$PWD/../ffmpeg-install" \
  --enable-static \
  --disable-shared \
  --disable-doc \
  --disable-programs \
  --disable-avdevice \
  --disable-network \
  --enable-pic \
  --enable-gpl \
  --enable-version3
make -j$(nproc)
make install
cd ..

Then pass -DFFMPEG_ROOT="$PWD/ffmpeg-install" to CMake.

OpenTimelineIO Not Found

OpenTimelineIO is a required dependency. Build it from source as shown in your platform's section above and pass -DOTIO_LOCATION=/path/to/otio-install to CMake. On Arch Linux the opentimelineio package provides it directly.

Reference in New Issue View Git Blame Copy Permalink