packaging: ship the Vulkan backend on all platforms, standard lib layout

- Linux CD builds no longer disable Vulkan: the AppImage, deb, rpm and
  Arch packages now build and ship liboakvulkan (the AppImage deploys
  it via linuxdeploy --library so libvulkan is bundled too, and the
  verify step checks both backend libraries); deb/rpm dependencies gain
  libvulkan1/vulkan-loader; the Arch PKGBUILD gains vulkan-headers
- macOS CD installs vulkan-loader and exports VULKAN_SDK so
  find_package(Vulkan) locates the Homebrew loader (previously the
  Vulkan backend silently never built there)
- ffmpeg_bridge now installs to the standard lib directory with
  /../lib RPATH instead of the non-standard ffmpeg_bridge/bin
  layout (verified: editor, worker, oakgl and oakvulkan all resolve it)
- build guides (EN/ZH) document the macOS Vulkan backend dependencies
  and the VULKAN_SDK variable

.github/workflows/cd.yml

@@ -104,7 +104,7 @@ jobs:
       - name: Install dependencies
         run: |
           brew update
-          brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers dylibbundler
+          brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader dylibbundler
 
       - name: Build OpenTimelineIO
         run: |
@@ -121,6 +121,8 @@ jobs:
         run: |
           export PATH="$(brew --prefix qt@6)/bin:$PATH"
           export CMAKE_PREFIX_PATH="$(brew --prefix qt@6)"
+          # CMake's FindVulkan locates the Homebrew loader via VULKAN_SDK
+          export VULKAN_SDK="$(brew --prefix vulkan-loader)"
           cmake -S . -B build -G Ninja \
             -DBUILD_QT6=ON \
             -DCMAKE_BUILD_TYPE=Release \
@@ -307,6 +309,7 @@ jobs:
             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 libxkbcommon-dev \
+            libvulkan-dev vulkan-headers \
             wget fuse3 desktop-file-utils
 
       - name: Build
@@ -314,8 +317,7 @@ jobs:
           cmake -S . -B build -G Ninja \
             -DCMAKE_BUILD_TYPE=Release \
             -DCMAKE_INSTALL_PREFIX=/usr \
-            -DBUILD_QT6=ON \
+            -DBUILD_QT6=ON
-            -DCMAKE_DISABLE_FIND_PACKAGE_Vulkan=ON
           cmake --build build
 
       - name: Install to AppDir
@@ -333,9 +335,16 @@ jobs:
           wget -q "https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage"
           chmod +x linuxdeploy-x86_64.AppImage linuxdeploy-plugin-qt-x86_64.AppImage appimagetool-x86_64.AppImage
           export PATH="${PWD}:${PATH}"
+          DEPLOY_ARGS=""
+          # The Vulkan backend is dlopen'ed at runtime, so linuxdeploy cannot
+          # discover it (and its dependencies) from the executable alone
+          if [ -f AppDir/usr/lib/liboakvulkan.so ]; then
+            DEPLOY_ARGS="--library AppDir/usr/lib/liboakvulkan.so"
+          fi
           ./linuxdeploy-x86_64.AppImage \
             --appdir AppDir \
             --plugin qt \
+            $DEPLOY_ARGS \
             --desktop-file AppDir/usr/share/applications/org.oakvideoeditor.Oak.desktop \
             --icon-file AppDir/usr/share/icons/hicolor/512x512/apps/org.oakvideoeditor.Oak.png \
             --output appimage
@@ -357,11 +366,14 @@ jobs:
           ls AppDir/usr/bin/oak-editor                       || (echo "Missing oak-editor" && exit 1)
           ls AppDir/usr/bin/oak-render-worker                || (echo "Missing oak-render-worker" && exit 1)
           ls AppDir/usr/lib/liboakgl.so                      || (echo "Missing liboakgl.so" && exit 1)
-          ls AppDir/usr/ffmpeg_bridge/bin/libffmpeg_bridge.so || (echo "Missing libffmpeg_bridge.so" && exit 1)
+          ls AppDir/usr/lib/liboakvulkan.so                  || (echo "Missing liboakvulkan.so" && exit 1)
+          ls AppDir/usr/lib/libvulkan.so*                    || (echo "Missing libvulkan" && exit 1)
+          ls AppDir/usr/lib/libffmpeg_bridge.so              || (echo "Missing libffmpeg_bridge.so" && exit 1)
           # Ensure every shipped binary resolves all of its dependencies
           ! ldd AppDir/usr/bin/oak-editor | grep "not found"
           ! ldd AppDir/usr/bin/oak-render-worker | grep "not found"
           ! ldd AppDir/usr/lib/liboakgl.so | grep "not found"
+          ! ldd AppDir/usr/lib/liboakvulkan.so | grep "not found"
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
@@ -387,15 +399,15 @@ jobs:
             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 libxkbcommon-dev
+            portaudio19-dev libgl1-mesa-dev libxkbcommon-dev \
+            libvulkan-dev vulkan-headers
 
       - name: Build
         run: |
           cmake -S . -B build -G Ninja \
             -DCMAKE_BUILD_TYPE=Release \
             -DCMAKE_INSTALL_PREFIX=/usr \
-            -DBUILD_QT6=ON \
+            -DBUILD_QT6=ON
-            -DCMAKE_DISABLE_FIND_PACKAGE_Vulkan=ON
           cmake --build build
 
       - name: Create DEB package
@@ -449,8 +461,7 @@ jobs:
           cmake -S . -B build -G Ninja \
             -DCMAKE_BUILD_TYPE=Release \
             -DCMAKE_INSTALL_PREFIX=/usr \
-            -DBUILD_QT6=ON \
+            -DBUILD_QT6=ON
-            -DCMAKE_DISABLE_FIND_PACKAGE_Vulkan=ON
           cmake --build build
 
       - name: Create RPM package
@@ -503,7 +514,7 @@ jobs:
               pacman -S --noconfirm --needed \
                 cmake ninja git pkgconf \
                 qt6-base qt6-tools ffmpeg openimageio opencolorio openexr expat portaudio \
-                mesa vulkan-icd-loader libxkbcommon fmt
+                mesa vulkan-headers vulkan-icd-loader libxkbcommon fmt
               useradd -m builder
               chown -R builder /build
               su builder -c "makepkg -s --noconfirm"

CMakeLists.txt

@@ -331,14 +331,14 @@ set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Oak Video Editor Team")
 set(CPACK_DEBIAN_FILE_NAME "DEB-DEFAULT")
 set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS OFF)
 set(CPACK_DEBIAN_PACKAGE_DEPENDS
-  "libqt6core6, libqt6gui6, libqt6widgets6, libqt6opengl6, libqt6openglwidgets6, libqt6network6, libqt6concurrent6, libavcodec60, libavformat60, libavutil58, libswscale7, libswresample4, libavfilter9, libopenimageio2.4, libopencolorio2, libopenexr-3-1-30, libexpat1, libportaudio2, libgl1, libxkbcommon0")
+  "libqt6core6, libqt6gui6, libqt6widgets6, libqt6opengl6, libqt6openglwidgets6, libqt6network6, libqt6concurrent6, libavcodec60, libavformat60, libavutil58, libswscale7, libswresample4, libavfilter9, libopenimageio2.4, libopencolorio2, libopenexr-3-1-30, libexpat1, libportaudio2, libgl1, libvulkan1, libxkbcommon0")
 
 # RPM
 set(CPACK_RPM_PACKAGE_LICENSE "GPLv3")
 set(CPACK_RPM_PACKAGE_GROUP "Applications/Multimedia")
 set(CPACK_RPM_PACKAGE_URL "https://oakvideoeditor.org")
 set(CPACK_RPM_PACKAGE_REQUIRES
-  "qt6-qtbase >= 6.0, qt6-qtbase-gui >= 6.0, qt6-qttools, ffmpeg-libs >= 6.0, OpenImageIO >= 2.4, OpenColorIO >= 2.0, openexr >= 3.1, expat, portaudio, mesa-libGL, libxkbcommon")
+  "qt6-qtbase >= 6.0, qt6-qtbase-gui >= 6.0, qt6-qttools, ffmpeg-libs >= 6.0, OpenImageIO >= 2.4, OpenColorIO >= 2.0, openexr >= 3.1, expat, portaudio, mesa-libGL, vulkan-loader, libxkbcommon")
 
 include(CPack)
 

app/CMakeLists.txt

@@ -342,9 +342,8 @@ target_link_libraries(libolive-editor PRIVATE ${OLIVE_LIBRARIES})
 target_link_libraries(olive-render-worker PRIVATE ${OLIVE_LIBRARIES})
 
 # The ffmpeg_bridge shared library ships next to the binaries: inside the
-# macOS app bundle (Contents/MacOS, resolved via @loader_path), and in
+# macOS app bundle (Contents/MacOS, resolved via @loader_path), and in the
-# ffmpeg_bridge/bin beside bin/ on other platforms. (Build-tree binaries get
+# standard lib directory on other platforms.
-# the correct RPATH from CMake automatically.)
 if (APPLE)
     # macOS bundles are distributed via POST_BUILD copies (not install()), so
     # @loader_path must already be in the build-tree binaries' RPATH.
@@ -352,7 +351,7 @@ if (APPLE)
     set_target_properties(olive-editor olive-render-worker PROPERTIES
             BUILD_RPATH "@loader_path")
 elseif (UNIX)
-    set(OLIVE_FB_RPATH "$ORIGIN/../ffmpeg_bridge/bin")
+    set(OLIVE_FB_RPATH "$ORIGIN/../lib")
 endif ()
 if (OLIVE_FB_RPATH)
     set_target_properties(olive-editor olive-render-worker PROPERTIES

app/packaging/arch/PKGBUILD.in

@@ -7,7 +7,7 @@ arch=('x86_64')
 url="https://oakvideoeditor.org"
 license=('GPL3')
 depends=('qt6-base' 'qt6-tools' 'ffmpeg' 'openimageio' 'opencolorio' 'openexr' 'expat' 'portaudio' 'mesa' 'vulkan-icd-loader' 'libxkbcommon' 'fmt')
-makedepends=('cmake' 'ninja' 'git' 'pkgconf')
+makedepends=('cmake' 'ninja' 'git' 'pkgconf' 'vulkan-headers')
 source=("${pkgname}-${pkgver}.tar.gz")
 md5sums=('SKIP')
 
@@ -16,8 +16,7 @@ build() {
   cmake -S . -B build -G Ninja \
     -DCMAKE_BUILD_TYPE=Release \
     -DCMAKE_INSTALL_PREFIX=/usr \
-    -DBUILD_QT6=ON \
+    -DBUILD_QT6=ON
-    -DCMAKE_DISABLE_FIND_PACKAGE_Vulkan=ON
   cmake --build build
 }
 

docs/build.md

@@ -208,7 +208,7 @@ Install dependencies:
 
 ```bash
 brew update
-brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers
+brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader
 ```
 
 Build OpenTimelineIO (optional, required for OTIO support):
@@ -231,6 +231,9 @@ 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}" \

docs/build_macos.md

@@ -66,7 +66,21 @@ brew install openimageio opencolorio openexr
 brew install portaudio expat
 ```
 
-### 7. Install Test Framework (Optional)
+### 7. Install Vulkan Backend Dependencies (Optional)
+
+Only needed for the Vulkan render backend. Oak builds the OpenGL backend regardless and falls back to it at runtime if Vulkan is unavailable:
+
+```bash
+brew install molten-vk vulkan-headers vulkan-loader
+```
+
+Point CMake at the loader so `find_package(Vulkan)` succeeds (add to `~/.zshrc` if you build regularly):
+
+```bash
+export VULKAN_SDK="$(brew --prefix vulkan-loader)"
+```
+
+### 8. Install Test Framework (Optional)
 
 Only needed if you plan to build and run tests:
 

docs/zh/build.md

@@ -208,7 +208,7 @@ macOS 现在是正式支持的平台。更详细的逐步指南请参见 [`build
 
 ```bash
 brew update
-brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers
+brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader
 ```
 
 构建 OpenTimelineIO（可选，如需 OTIO 支持）：
@@ -231,6 +231,9 @@ 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}" \

docs/zh/build_macos-zh.md

@@ -66,7 +66,21 @@ brew install openimageio opencolorio openexr
 brew install portaudio expat
 ```
 
-### 7. 安装测试框架（可选）
+### 7. 安装 Vulkan 后端依赖（可选）
+
+仅在需要 Vulkan 渲染后端时需要。Oak 始终构建 OpenGL 后端，当 Vulkan 不可用时会自动回退到它：
+
+```bash
+brew install molten-vk vulkan-headers vulkan-loader
+```
+
+让 CMake 能找到 loader，使 `find_package(Vulkan)` 成功（经常构建的话可以写入 `~/.zshrc`）：
+
+```bash
+export VULKAN_SDK="$(brew --prefix vulkan-loader)"
+```
+
+### 8. 安装测试框架（可选）
 
 仅在需要构建和运行测试时需要：
 

ffmpeg_bridge/CMakeLists.txt

@@ -101,8 +101,8 @@ if (WIN32)
   )
 else()
   install(TARGETS ffmpeg_bridge
-    RUNTIME DESTINATION ffmpeg_bridge/bin
+    RUNTIME DESTINATION bin
-    LIBRARY DESTINATION ffmpeg_bridge/bin
+    LIBRARY DESTINATION lib
     ARCHIVE DESTINATION ffmpeg_bridge/lib
   )
 endif ()