docs: current bilingual build guide; retire the C++/CMake one
docs/build.md + docs/zh/build.md rewritten for the Rust workspace: project-built FFmpeg 8.1 (.cargo/config.toml presets FFMPEG_DIR), vendored static OCIO on Linux/macOS vs MSYS2 dynamic OCIO on Windows (with the OCIO_INSTALL_DIR/OCIO_RS_LINK env), the Windows GNU toolchain requirements (MSYS2 Rust, RUSTFLAGS=-C link-args=-lmsvcrt for the mingw-w64 _assert forwarding, unset INCLUDE/LIB), Linux audio dev packages and xvfb headless testing, container packaging, and a troubleshooting section. The macOS-only guides gain a deprecation pointer. Also correct two stale comments in tooling/install-deps.sh (FFmpeg is built by tooling/ffmpeg/build-ffmpeg.sh, not by cargo).
This commit is contained in:
+141
-364
@@ -1,392 +1,169 @@
|
||||
# Build Guide
|
||||
|
||||
This document describes how to build Oak Video Editor from source on Windows, Linux, and macOS.
|
||||
This document describes how to build the Oak Video Editor from source on
|
||||
macOS, Linux, and Windows. For the Chinese version see
|
||||
[`zh/build.md`](zh/build.md).
|
||||
|
||||
> **Note (2026):** Oak is now a Rust workspace; `cargo build` at the
|
||||
> repository root produces the app, the CLI and the worker
|
||||
> (`liboakengine` — the plugin/external-consumer cdylib — is not a
|
||||
> default member, M14 R4; build it explicitly with
|
||||
> `cargo build -p oakengine`). The CMake instructions below are kept for
|
||||
> historical
|
||||
> reference only. Rust dependencies are pulled from crates.io; the only
|
||||
> native libraries still needed are FFmpeg (see the next section),
|
||||
> OpenColorIO (optional; `ocio-sys` builds a stub without it) and a
|
||||
> C/C++ toolchain for the FFI shims.
|
||||
>
|
||||
> ### FFmpeg for the Rust build
|
||||
>
|
||||
> `ffmpeg-next` 9.x pairs with FFmpeg 8.x headers, which most distros do
|
||||
> not ship yet. Build a project-owned FFmpeg — GPL parts enabled, every
|
||||
> free-license external codec library that is installed, per-OS hardware
|
||||
> acceleration, static+PIC — with the project scripts:
|
||||
>
|
||||
> ```sh
|
||||
> tooling/install-deps.sh # Homebrew / MSYS2 UCRT64 / Debian / Fedora / Arch
|
||||
> tooling/ffmpeg/build-ffmpeg.sh # clones release/8.0, installs into .cache/ffmpeg
|
||||
> cargo build
|
||||
> ```
|
||||
>
|
||||
> `FFMPEG_DIR` no longer needs exporting: the committed
|
||||
> `.cargo/config.toml` sets it relative to the workspace root (the
|
||||
> ffmpeg-sys-next build script cannot read `.env` files — this is the
|
||||
> only machine-agnostic way).
|
||||
>
|
||||
> External libraries are probed with `pkg-config` and silently skipped
|
||||
> when missing. `FFMPEG_DIR` is mandatory (the `oakffmpeg-link` build
|
||||
> script panics without it): silently binding a system FFmpeg risks
|
||||
> stale `.pc` paths after package upgrades. IDEs that cannot inject
|
||||
> environment variables into cargo (RustRover) can instead put
|
||||
> `FFMPEG_DIR=...` (and `PKG_CONFIG_PATH=...` where needed) into a
|
||||
> `.env` file at the workspace root — it is git-ignored.
|
||||
> ffmpeg-next's `build` cargo feature is deliberately not used: it
|
||||
> clones release/<crate-version>, and every such pairing is broken
|
||||
> upstream (9.0.0 → FFmpeg 9.0 removed AVCodec fields; 8.1.0 → FFmpeg
|
||||
> 8.1 added enum variants; 8.0.0 → FFmpeg 8.0 renamed FF_PROFILE_*).
|
||||
|
||||
## 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)
|
||||
> **2026 note:** Oak is a pure Rust workspace. `cargo build` at the
|
||||
> repository root produces the app (`oak-editor`), the CLI (`oak-cli`)
|
||||
> and the render worker (`oak-worker`). The old C++/CMake tree lives on
|
||||
> the `cpp-legacy` branch; nothing in this guide uses it.
|
||||
|
||||
---
|
||||
|
||||
## Windows (MSYS2)
|
||||
## Prerequisites (all platforms)
|
||||
|
||||
This guide uses [MSYS2](https://www.msys2.org/) with the UCRT64 toolchain.
|
||||
- **git** — clone with submodules (`gpui/` is a submodule):
|
||||
```sh
|
||||
git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
|
||||
cd oak
|
||||
# or, on an existing clone: git submodule update --init --recursive
|
||||
```
|
||||
- **Rust stable** (via [rustup](https://rustup.rs/); on Windows use the
|
||||
MSYS2 toolchain instead — see the Windows section).
|
||||
- **C toolchain + cmake + pkg-config + nasm** — cmake and a C++ compiler
|
||||
are needed by the vendored OpenColorIO build (Linux/macOS), nasm by
|
||||
the FFmpeg assembly.
|
||||
- **FFmpeg 8.1, built by the project script.** Distro packages are too
|
||||
old for `ffmpeg-next` 9 and are deliberately not used:
|
||||
```sh
|
||||
tooling/install-deps.sh # codec/filter libraries + build tools
|
||||
tooling/ffmpeg/build-ffmpeg.sh # clones release/8.1, installs into .cache/ffmpeg
|
||||
```
|
||||
`FFMPEG_DIR` does not need exporting: the committed
|
||||
`.cargo/config.toml` sets it relative to the workspace root
|
||||
(`ffmpeg-sys-next` cannot read `.env` at build-script time — the
|
||||
config entry is the only machine-agnostic way). The `oakffmpeg-link`
|
||||
build script panics without it; run `build-ffmpeg.sh` once before the
|
||||
first `cargo build`.
|
||||
|
||||
### 1. Install MSYS2
|
||||
## Quick start (macOS / Linux)
|
||||
|
||||
Download and install MSYS2 from [https://www.msys2.org/](https://www.msys2.org/). Then open the **MSYS2 UCRT64** terminal.
|
||||
|
||||
### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```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 \
|
||||
-DOTIO_LOCATION="/path/to/otio-install" \
|
||||
-DBUILD_QT6=ON
|
||||
|
||||
# Build
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
### 5. Run Tests (Optional)
|
||||
|
||||
```bash
|
||||
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):
|
||||
|
||||
```bash
|
||||
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):
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
cmake -S . -B build -G Ninja \
|
||||
-DBUILD_TESTS=ON -DBUILD_QT6=ON \
|
||||
-DOTIO_LOCATION="$PWD/otio-install"
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
Run tests:
|
||||
|
||||
```bash
|
||||
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-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):
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
|
||||
-DOTIO_LOCATION="$PWD/otio-install"
|
||||
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 \
|
||||
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:
|
||||
|
||||
```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
|
||||
```sh
|
||||
tooling/install-deps.sh # Homebrew / apt / dnf / pacman
|
||||
tooling/ffmpeg/build-ffmpeg.sh # ~10–20 min, once
|
||||
cargo build --workspace
|
||||
cargo test --workspace # Linux: see "headless tests" below
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## macOS
|
||||
|
||||
macOS is now a fully supported platform. See [`build_macos.md`](build_macos.md) for a dedicated, step-by-step guide.
|
||||
- macOS 12+, Xcode Command Line Tools (`xcode-select --install`), Homebrew.
|
||||
- ```sh
|
||||
brew install cmake pkg-config
|
||||
tooling/install-deps.sh
|
||||
tooling/ffmpeg/build-ffmpeg.sh
|
||||
cargo build --workspace
|
||||
cargo test --workspace
|
||||
```
|
||||
- OpenColorIO is compiled from the vendored 2.5.2 sources and linked
|
||||
statically — no `brew install opencolorio` needed (cmake is required).
|
||||
- The GPU-gated tests (OFX GL overlay, hardware decode) run only with
|
||||
`OAK_GPU_TESTS=1`.
|
||||
|
||||
Install dependencies:
|
||||
## Linux
|
||||
|
||||
```bash
|
||||
brew update
|
||||
brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader
|
||||
```
|
||||
- Debian/Ubuntu, Fedora and Arch are supported by
|
||||
`tooling/install-deps.sh`. Additionally install:
|
||||
```sh
|
||||
# Debian/Ubuntu
|
||||
sudo apt-get install -y cmake \
|
||||
libpipewire-0.3-dev libspa-0.2-dev libjack-jackd2-dev \
|
||||
libasound2-dev libpulse-dev libsndfile1-dev \
|
||||
libgl1-mesa-dev libvulkan-dev libxkbcommon-dev libxkbcommon-x11-dev
|
||||
```
|
||||
(the PipeWire/JACK/ALSA/PulseAudio/sndfile dev packages are cpal's
|
||||
audio backends; GL/Vulkan/XKB are the wgpu windowing stack).
|
||||
- **Headless tests:** several gpui/UI tests open real windows through
|
||||
wgpu on Mesa's software Vulkan. Under a display-less session run:
|
||||
```sh
|
||||
sudo apt-get install -y xvfb mesa-vulkan-drivers
|
||||
xvfb-run -a -s "-screen 0 1920x1080x24" cargo test --workspace
|
||||
```
|
||||
- OpenColorIO is the vendored static build, as on macOS.
|
||||
|
||||
Build OpenTimelineIO (required):
|
||||
## Windows (MSYS2 UCRT64)
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
The Windows build targets **x86_64-pc-windows-gnu** with MSYS2's own
|
||||
Rust; the MSVC toolchain is not supported (the build scripts emit
|
||||
Unix-style link args the MSVC linker rejects).
|
||||
|
||||
Configure and build:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
ctest --test-dir build --output-on-failure -C Release
|
||||
```
|
||||
1. Install [MSYS2](https://www.msys2.org/) and open the **UCRT64** shell.
|
||||
2. ```sh
|
||||
pacman -Syu
|
||||
pacman -S --needed mingw-w64-ucrt-x86_64-rust \
|
||||
mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-opencolorio
|
||||
tooling/install-deps.sh # must run inside the UCRT64 shell
|
||||
tooling/ffmpeg/build-ffmpeg.sh
|
||||
```
|
||||
3. Environment (put in your shell rc or export per session):
|
||||
```sh
|
||||
# The vendored OCIO sources contain MSVC-only constructs, so Windows
|
||||
# links MSYS2's OpenColorIO 2.5.2 dynamically instead:
|
||||
export OCIO_RS_ENABLE_REAL=1 OCIO_INSTALL_DIR=/ucrt64 OCIO_RS_LINK=dynamic
|
||||
# mingw-w64 (Nov 2025+) forwards _assert to __msvcrt_assert inside
|
||||
# libmingwex.a while rustc's link order leaves -lmingwex last; the
|
||||
# trailing -lmsvcrt re-scans the CRT import library afterwards
|
||||
# (otherwise: undefined _fileno/_setmode/__imp___msvcrt_assert).
|
||||
export RUSTFLAGS="-C link-args=-lmsvcrt"
|
||||
# If your shell inherits the MSVC INCLUDE/LIB (some CI runners inject
|
||||
# them into every step), clear them — they poison the MinGW compiles:
|
||||
unset INCLUDE LIB
|
||||
```
|
||||
4. ```sh
|
||||
cargo build --workspace
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Options
|
||||
## OpenColorIO summary
|
||||
|
||||
| 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`) |
|
||||
| Platform | Source | Linkage | Notes |
|
||||
|----------|--------|---------|-------|
|
||||
| Linux / macOS | vendored 2.5.2 (`ocio-sys` `bundled` feature, on by default) | static | needs cmake + C++ compiler |
|
||||
| Windows | MSYS2 `mingw-w64-ucrt-x86_64-opencolorio` | dynamic | set `OCIO_INSTALL_DIR=/ucrt64`, `OCIO_RS_LINK=dynamic` |
|
||||
|
||||
---
|
||||
Without the `bundled` feature and without `OCIO_RS_ENABLE_REAL=1`,
|
||||
`ocio-sys` builds a stub and every colour test early-returns. The
|
||||
bundled feature is enabled unconditionally by `oakrender`, so a plain
|
||||
`cargo build` always gets the real thing on Linux/macOS.
|
||||
|
||||
## Packaging
|
||||
|
||||
Distribution packages are built in containers (no host dependencies
|
||||
beyond Docker/Podman):
|
||||
|
||||
```sh
|
||||
tooling/package/build-deb.sh # Debian 12 → .deb
|
||||
tooling/package/build-rpm.sh # Fedora 41 → .rpm
|
||||
tooling/package/build-pkg.sh # Arch Linux → .pkg.tar.zst
|
||||
```
|
||||
|
||||
All runtime dependencies are declared in the respective package metadata
|
||||
(`packaging/`, `tooling/package/oak.spec`, `tooling/package/PKGBUILD`) —
|
||||
the packages are self-contained except for the documented system
|
||||
libraries; see `docs/project-storage.md` for what lands where.
|
||||
|
||||
## 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="/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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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.
|
||||
- **`oakffmpeg-link` panics about `FFMPEG_DIR`** — run
|
||||
`tooling/ffmpeg/build-ffmpeg.sh` once; it installs into
|
||||
`.cache/ffmpeg`, which `.cargo/config.toml` points at.
|
||||
- **IDE builds fail (RustRover etc.)** — IDEs that cannot inject
|
||||
environment variables into cargo can read a git-ignored `.env` at the
|
||||
workspace root with `FFMPEG_DIR=...` (and `PKG_CONFIG_PATH=...` if
|
||||
your codec libraries live in a custom prefix).
|
||||
- **pacman stalls with "Operation too slow"** — MSYS2 mirrors hiccup;
|
||||
`install-deps.sh` retries three times, re-running it resumes via
|
||||
`--needed`.
|
||||
- **Windows: `undefined reference to _fileno/_setmode/__imp___msvcrt_assert`**
|
||||
— set `RUSTFLAGS="-C link-args=-lmsvcrt"` (see the Windows section).
|
||||
- **Windows: `AddInstanceForFactory: No factory registered` / MSVC-flavoured
|
||||
errors** — you are on the MSVC Rust toolchain; switch to MSYS2's Rust
|
||||
(`x86_64-pc-windows-gnu`).
|
||||
- **Empty `gpui/` directory** — `git submodule update --init --recursive`.
|
||||
- **Linux tests open windows and hang/fail** — use the `xvfb-run` line
|
||||
from the Linux section.
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# macOS Build Guide
|
||||
|
||||
> **Deprecated (2026):** this guide describes the old C++/CMake build.
|
||||
> The current Rust workspace build is documented in
|
||||
> [`build.md`](build.md) (中文：[`zh/build.md`](zh/build.md)).
|
||||
|
||||
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).
|
||||
|
||||
+132
-310
@@ -1,342 +1,164 @@
|
||||
# 构建指南
|
||||
|
||||
本文档介绍如何在 Windows、Linux 和 macOS 上从源码构建 Oak Video Editor。
|
||||
本文档介绍如何在 macOS、Linux 和 Windows 上从源码构建 Oak 视频编辑器。
|
||||
英文版见 [`../build.md`](../build.md)。
|
||||
|
||||
## 依赖
|
||||
|
||||
- CMake 3.20+
|
||||
- Ninja（推荐）
|
||||
- Qt 6（含私有头文件）
|
||||
- FFmpeg 6.0+ 开发库
|
||||
- OpenTimelineIO（0.16+，按下文从源码构建——大多数平台没有发行版软件包）
|
||||
- OpenImageIO
|
||||
- OpenColorIO（2.x）
|
||||
- OpenEXR
|
||||
- Expat
|
||||
- PortAudio
|
||||
- OpenGL 头文件
|
||||
- Vulkan SDK（可选，Vulkan 渲染后端需要）
|
||||
- XKB common（Linux）
|
||||
> **2026 年说明：** Oak 现在是纯 Rust workspace。在仓库根目录执行
|
||||
> `cargo build` 会产出应用（`oak-editor`）、命令行工具（`oak-cli`）
|
||||
> 和渲染进程（`oak-worker`）。旧的 C++/CMake 代码保留在
|
||||
> `cpp-legacy` 分支，本指南不涉及它。
|
||||
|
||||
---
|
||||
|
||||
## Windows（MSYS2）
|
||||
## 通用前置条件
|
||||
|
||||
本指南使用 [MSYS2](https://www.msys2.org/) 的 UCRT64 工具链。
|
||||
- **git** —— 克隆时必须带子模块（`gpui/` 是子模块）：
|
||||
```sh
|
||||
git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
|
||||
cd oak
|
||||
# 已有克隆则：git submodule update --init --recursive
|
||||
```
|
||||
- **Rust stable**（通过 [rustup](https://rustup.rs/) 安装；Windows
|
||||
请改用 MSYS2 自带 Rust——见 Windows 章节）。
|
||||
- **C 工具链 + cmake + pkg-config + nasm** —— cmake 和 C++ 编译器
|
||||
用于 vendored OpenColorIO 构建（Linux/macOS），nasm 用于 FFmpeg
|
||||
汇编。
|
||||
- **FFmpeg 8.1，由项目脚本构建。** 发行版自带版本对 `ffmpeg-next` 9
|
||||
来说太旧，刻意不使用：
|
||||
```sh
|
||||
tooling/install-deps.sh # 编解码/滤镜库 + 构建工具
|
||||
tooling/ffmpeg/build-ffmpeg.sh # 克隆 release/8.1，安装到 .cache/ffmpeg
|
||||
```
|
||||
`FFMPEG_DIR` 无需手动导出：仓库内提交的 `.cargo/config.toml` 已按
|
||||
workspace 根的相对路径设置（`ffmpeg-sys-next` 的构建脚本读不了
|
||||
`.env`，这是唯一与机器无关的方式）。缺少它时 `oakffmpeg-link` 的
|
||||
构建脚本会直接 panic：首次 `cargo build` 前请先跑一次
|
||||
`build-ffmpeg.sh`。
|
||||
|
||||
### 1. 安装 MSYS2
|
||||
## 快速开始（macOS / Linux）
|
||||
|
||||
从 [https://www.msys2.org/](https://www.msys2.org/) 下载并安装 MSYS2，然后打开 **MSYS2 UCRT64** 终端。
|
||||
|
||||
### 2. 安装依赖
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
> **注意：** Qt 6 私有头文件可能需要额外安装。如果 CMake 报告找不到私有头文件，请尝试安装 `mingw-w64-ucrt-x86_64-qt6-base-private`（如果仓库中有）。
|
||||
|
||||
### 3. 构建 OpenTimelineIO（必需）
|
||||
|
||||
MSYS2 仓库没有 OpenTimelineIO 软件包，需从源码构建：
|
||||
|
||||
```bash
|
||||
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. 克隆并构建
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
|
||||
cd oak
|
||||
|
||||
# 配置
|
||||
cmake -S . -B build -G Ninja \
|
||||
-DCMAKE_BUILD_TYPE=Release \
|
||||
-DOTIO_LOCATION="/path/to/otio-install" \
|
||||
-DBUILD_QT6=ON
|
||||
|
||||
# 构建
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
### 5. 运行测试（可选）
|
||||
|
||||
```bash
|
||||
ctest --test-dir build --output-on-failure -C Release
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Linux
|
||||
|
||||
### Debian / Ubuntu
|
||||
|
||||
安装依赖（Ubuntu 24.04+ 自带的 FFmpeg 6.1 已满足 6.0 最低要求；更旧的发行版请按"故障排除"一节从源码编译 FFmpeg）：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
从源码构建 OpenTimelineIO（必需，无发行版软件包）：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
配置并构建：
|
||||
|
||||
```bash
|
||||
cmake -S . -B build -G Ninja \
|
||||
-DBUILD_TESTS=ON -DBUILD_QT6=ON \
|
||||
-DOTIO_LOCATION="$PWD/otio-install"
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
运行测试：
|
||||
|
||||
```bash
|
||||
ctest --test-dir build --output-on-failure -C Release
|
||||
```
|
||||
|
||||
### Fedora
|
||||
|
||||
安装依赖：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
从源码构建 OpenTimelineIO（必需，无发行版软件包）：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
配置并构建：
|
||||
|
||||
```bash
|
||||
cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
|
||||
-DOTIO_LOCATION="$PWD/otio-install"
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
运行测试：
|
||||
|
||||
```bash
|
||||
ctest --test-dir build --output-on-failure -C Release
|
||||
```
|
||||
|
||||
### Arch Linux
|
||||
|
||||
安装依赖：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
> **注意：** Arch Linux 的 `qt6-base` 包已经包含私有头文件。
|
||||
|
||||
配置并构建：
|
||||
|
||||
```bash
|
||||
cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON
|
||||
cmake --build build --config Release
|
||||
```
|
||||
|
||||
运行测试：
|
||||
|
||||
```bash
|
||||
ctest --test-dir build --output-on-failure -C Release
|
||||
```sh
|
||||
tooling/install-deps.sh # Homebrew / apt / dnf / pacman
|
||||
tooling/ffmpeg/build-ffmpeg.sh # 约 10–20 分钟，只需一次
|
||||
cargo build --workspace
|
||||
cargo test --workspace # Linux：见下文"无头测试"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## macOS
|
||||
|
||||
macOS 现在是正式支持的平台。更详细的逐步指南请参见 [`build_macos-zh.md`](build_macos-zh.md)。
|
||||
- macOS 12+、Xcode Command Line Tools（`xcode-select --install`）、Homebrew。
|
||||
- ```sh
|
||||
brew install cmake pkg-config
|
||||
tooling/install-deps.sh
|
||||
tooling/ffmpeg/build-ffmpeg.sh
|
||||
cargo build --workspace
|
||||
cargo test --workspace
|
||||
```
|
||||
- OpenColorIO 由 vendored 2.5.2 源码编译并静态链接——不需要
|
||||
`brew install opencolorio`（但需要 cmake）。
|
||||
- GPU 相关测试（OFX GL 叠加层、硬件解码）仅在设置 `OAK_GPU_TESTS=1`
|
||||
时运行。
|
||||
|
||||
安装依赖：
|
||||
## Linux
|
||||
|
||||
```bash
|
||||
brew update
|
||||
brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader
|
||||
```
|
||||
- `tooling/install-deps.sh` 支持 Debian/Ubuntu、Fedora、Arch。
|
||||
另外需要安装：
|
||||
```sh
|
||||
# Debian/Ubuntu
|
||||
sudo apt-get install -y cmake \
|
||||
libpipewire-0.3-dev libspa-0.2-dev libjack-jackd2-dev \
|
||||
libasound2-dev libpulse-dev libsndfile1-dev \
|
||||
libgl1-mesa-dev libvulkan-dev libxkbcommon-dev libxkbcommon-x11-dev
|
||||
```
|
||||
（PipeWire/JACK/ALSA/PulseAudio/sndfile 开发包是 cpal 的音频后端；
|
||||
GL/Vulkan/XKB 是 wgpu 窗口栈。）
|
||||
- **无头测试：** 部分 gpui/UI 测试会通过 wgpu 在 Mesa 软件 Vulkan
|
||||
（lavapipe）上打开真实窗口。无显示环境下请运行：
|
||||
```sh
|
||||
sudo apt-get install -y xvfb mesa-vulkan-drivers
|
||||
xvfb-run -a -s "-screen 0 1920x1080x24" cargo test --workspace
|
||||
```
|
||||
- OpenColorIO 与 macOS 相同，使用 vendored 静态构建。
|
||||
|
||||
构建 OpenTimelineIO（必需）：
|
||||
## Windows（MSYS2 UCRT64）
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
Windows 构建目标是 **x86_64-pc-windows-gnu**，使用 MSYS2 自带 Rust；
|
||||
不支持 MSVC 工具链（构建脚本会发出 MSVC 链接器不接受的 Unix 风格
|
||||
链接参数）。
|
||||
|
||||
配置并构建：
|
||||
|
||||
```bash
|
||||
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)"
|
||||
# 让 CMake 的 FindVulkan 找到 Homebrew 的 Vulkan loader（可选，
|
||||
# 启用 Vulkan 渲染后端）
|
||||
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
|
||||
```
|
||||
|
||||
运行测试：
|
||||
|
||||
```bash
|
||||
ctest --test-dir build --output-on-failure -C Release
|
||||
```
|
||||
1. 安装 [MSYS2](https://www.msys2.org/)，打开 **UCRT64** 终端。
|
||||
2. ```sh
|
||||
pacman -Syu
|
||||
pacman -S --needed mingw-w64-ucrt-x86_64-rust \
|
||||
mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-opencolorio
|
||||
tooling/install-deps.sh # 必须在 UCRT64 终端内运行
|
||||
tooling/ffmpeg/build-ffmpeg.sh
|
||||
```
|
||||
3. 环境变量（写入 shell rc 或每次会话导出）：
|
||||
```sh
|
||||
# vendored OCIO 源码含有仅 MSVC 可编译的构造，Windows 改为动态链接
|
||||
# MSYS2 的 OpenColorIO 2.5.2：
|
||||
export OCIO_RS_ENABLE_REAL=1 OCIO_INSTALL_DIR=/ucrt64 OCIO_RS_LINK=dynamic
|
||||
# mingw-w64（2025 年 11 月后）把 _assert 转发到 libmingwex.a 里的
|
||||
# __msvcrt_assert，而 rustc 的链接顺序把 -lmingwex 放在最后；末尾
|
||||
# 追加 -lmsvcrt 让链接器再扫一遍 CRT 导入库
|
||||
# （否则报 undefined _fileno/_setmode/__imp___msvcrt_assert）。
|
||||
export RUSTFLAGS="-C link-args=-lmsvcrt"
|
||||
# 如果 shell 继承了 MSVC 的 INCLUDE/LIB（某些 CI runner 会向每个
|
||||
# 步骤注入），务必清除——它们会污染 MinGW 编译：
|
||||
unset INCLUDE LIB
|
||||
```
|
||||
4. ```sh
|
||||
cargo build --workspace
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 构建选项
|
||||
## OpenColorIO 一览
|
||||
|
||||
| 选项 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `BUILD_TESTS` | `OFF` | 构建单元测试 |
|
||||
| `BUILD_DOXYGEN` | `OFF` | 构建 Doxygen 文档 |
|
||||
| `USE_WERROR` | `OFF` | 将警告视为错误 |
|
||||
| `BUILD_QT6` | `ON` | 使用 Qt 6 而非 Qt 5 |
|
||||
| `OTIO_LOCATION` | - | OpenTimelineIO 安装路径（必需） |
|
||||
| `OAK_BUNDLE_OTIO` | `ON` | 随 Oak 一并安装 OTIO 运行库（发行版原生打包且 `opentimelineio` 是包依赖时设 `OFF`，如 Arch） |
|
||||
| `OCIO_LOCATION` | - | OpenColorIO 安装路径 |
|
||||
| `OAK_ENABLE_DYNAMIC_RENDER_BACKEND` | `ON` | 构建动态渲染后端库（`liboakgl.so` / `liboakvulkan.so`） |
|
||||
| 平台 | 来源 | 链接方式 | 备注 |
|
||||
|------|------|----------|------|
|
||||
| Linux / macOS | vendored 2.5.2（`ocio-sys` 的 `bundled` 特性，默认开启） | 静态 | 需要 cmake + C++ 编译器 |
|
||||
| Windows | MSYS2 `mingw-w64-ucrt-x86_64-opencolorio` | 动态 | 设置 `OCIO_INSTALL_DIR=/ucrt64`、`OCIO_RS_LINK=dynamic` |
|
||||
|
||||
---
|
||||
既没有 `bundled` 特性也没有 `OCIO_RS_ENABLE_REAL=1` 时，`ocio-sys`
|
||||
构建为 stub，所有色彩测试直接跳过。`oakrender` 无条件启用 bundled
|
||||
特性，因此在 Linux/macOS 上直接 `cargo build` 就会得到真实 OCIO。
|
||||
|
||||
## 故障排除
|
||||
## 打包
|
||||
|
||||
### 找不到 Qt 6
|
||||
发行版包在容器中构建（宿主机只需要 Docker/Podman）：
|
||||
|
||||
确保 Qt 6 在 PATH 和 CMake prefix path 中：
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
export PATH="/path/to/qt6/bin:$PATH"
|
||||
export CMAKE_PREFIX_PATH="/path/to/qt6"
|
||||
|
||||
# Windows（MSYS2）
|
||||
export PATH="/ucrt64/bin:$PATH"
|
||||
```sh
|
||||
tooling/package/build-deb.sh # Debian 12 → .deb
|
||||
tooling/package/build-rpm.sh # Fedora 41 → .rpm
|
||||
tooling/package/build-pkg.sh # Arch Linux → .pkg.tar.zst
|
||||
```
|
||||
|
||||
### 缺少私有头文件
|
||||
所有运行时依赖都声明在各自的打包元数据中（`packaging/`、
|
||||
`tooling/package/oak.spec`、`tooling/package/PKGBUILD`）——除文档
|
||||
列明的系统库外包是自包含的；文件安装位置见
|
||||
`docs/project-storage.md`。
|
||||
|
||||
如果看到缺少 Qt 私有头文件的错误，请安装对应发行版的私有开发包（例如 Debian/Ubuntu 上的 `qt6-base-private-dev`，Fedora 上的 `qt6-qtbase-private-devel`）。
|
||||
## 故障排查
|
||||
|
||||
### FFmpeg 版本太旧
|
||||
|
||||
Oak 要求 FFmpeg 6.0 或更新版本；版本不足时 CMake 配置阶段会报 `Could NOT find FFMPEG ... (Required is at least version "6.0")`。Ubuntu 24.04+ / Fedora / Arch / Homebrew / MSYS2 自带的版本都足够新。如果发行版过旧，请从源码编译：
|
||||
|
||||
```bash
|
||||
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 ..
|
||||
```
|
||||
|
||||
然后在 CMake 中加上 `-DFFMPEG_ROOT="$PWD/ffmpeg-install"`。
|
||||
|
||||
### 找不到 OpenTimelineIO
|
||||
|
||||
OpenTimelineIO 是必需依赖。按你所在平台章节的说明从源码构建，并在 CMake 中加上 `-DOTIO_LOCATION=/path/to/otio-install`。Arch Linux 可直接安装 `opentimelineio` 包。
|
||||
- **`oakffmpeg-link` 报 `FFMPEG_DIR` panic** —— 先跑一次
|
||||
`tooling/ffmpeg/build-ffmpeg.sh`；它安装到 `.cache/ffmpeg`，
|
||||
`.cargo/config.toml` 已指向该目录。
|
||||
- **IDE 构建失败（RustRover 等）** —— 无法向 cargo 注入环境变量的
|
||||
IDE 可以在 workspace 根放一个 git 忽略的 `.env`，写入
|
||||
`FFMPEG_DIR=...`（编解码库在自定义前缀时再加
|
||||
`PKG_CONFIG_PATH=...`）。
|
||||
- **pacman 报 "Operation too slow"** —— MSYS2 镜像偶尔卡顿；
|
||||
`install-deps.sh` 会自动重试三次，手动重跑也会借助 `--needed`
|
||||
断点续装。
|
||||
- **Windows：`undefined reference to _fileno/_setmode/__imp___msvcrt_assert`**
|
||||
—— 设置 `RUSTFLAGS="-C link-args=-lmsvcrt"`（见 Windows 章节）。
|
||||
- **Windows：出现 MSVC 风格的链接错误** —— 你用的是 MSVC 版 Rust；
|
||||
请改用 MSYS2 自带 Rust（`x86_64-pc-windows-gnu`）。
|
||||
- **`gpui/` 目录为空** —— `git submodule update --init --recursive`。
|
||||
- **Linux 测试开窗口卡死/失败** —— 使用 Linux 章节的 `xvfb-run`
|
||||
命令。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# macOS 编译指南
|
||||
|
||||
> **已过时（2026）：** 本文档描述旧的 C++/CMake 构建。当前 Rust
|
||||
> workspace 的构建方法见 [`build.md`](build.md)（英文：
|
||||
> [`../build.md`](../build.md)）。
|
||||
|
||||
本文档介绍如何在 macOS 上从源代码构建 Oak 视频编辑器。
|
||||
|
||||
英文版本请参见 [`build-macos.md`](../build_macos.md)。
|
||||
|
||||
@@ -18,8 +18,8 @@
|
||||
# Installs the system dependencies of the Oak Rust workspace:
|
||||
# the free-license external codec/filter libraries FFmpeg is configured
|
||||
# with (see crates/oakcodec/Cargo.toml), plus the build tools. FFmpeg
|
||||
# itself is built from source by cargo (ffmpeg-next `build` feature) and
|
||||
# is NOT installed here.
|
||||
# itself is built from source by tooling/ffmpeg/build-ffmpeg.sh (which
|
||||
# installs into .cache/ffmpeg) and is NOT installed here.
|
||||
#
|
||||
# Supported: Homebrew (macOS), MSYS2 UCRT64 (Windows), Debian/Ubuntu,
|
||||
# Fedora, Arch. Run it yourself — nothing in the build invokes it
|
||||
@@ -102,4 +102,4 @@ case "$(uname -s)" in
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "Done. 'cargo build' now compiles FFmpeg 8.1 from source with these libraries."
|
||||
echo "Done. Now run tooling/ffmpeg/build-ffmpeg.sh once, then 'cargo build'."
|
||||
|
||||
Reference in New Issue
Block a user