Optional Vulkan preview and Linux packaging

Make the Vulkan 3D preview optional and improve Linux portable packaging.

- Add meson option 'vulkan_preview' (auto/enable/disable). Detect Qt private RHI headers (qrhi.h, qshader.h) and set PAKFU_WITH_VULKAN_PREVIEW accordingly. Fail configuration if the feature is explicitly required but headers are missing. Conditionally add Vulkan source files and moc headers when enabled.
- Emit PAKFU_WITH_VULKAN_PREVIEW in generated pakfu_config.h and guard preview renderer includes on that macro.
- Provide lightweight QWidget stubs for bsp/model Vulkan widgets when Vulkan preview is disabled so the app can build & run with OpenGL-only preview.
- Revamp scripts/package_linux.sh to produce a portable tarball from the deployed AppDir produced by linuxdeployqt, verify libQt6Core is bundled and the pakfu binary resolves Qt from the AppDir, require AppRun presence, and create a top-level pakfu launcher that runs AppRun. Fail packaging on missing Qt Core or unresolved dependencies.
- Update README, docs/DEPENDENCIES.md, docs/RELEASES.md and CHANGELOG to document the portable Linux archive contents and the optional Vulkan preview behavior.

Author: themuffinator

CHANGELOG.md

@@ -10,6 +10,8 @@ All notable changes to PakFu are documented here.
 - Fix stale folder listings when navigating newly added folders in a new PAK tab by using canonical archive paths for navigation/listing.
 - Revise all open/save file and folder dialogs to use platform-native navigation by default, with persistent recent locations, filters, and sidebar bookmarks across sessions.
 - Fix potential GUI hangs when opening file dialogs on systems with slow/unreachable volumes by removing synchronous volume probing from dialog state restore.
+- Bundle the deployed Linux runtime into portable tarballs and fail packaging if Qt Core is missing from the deployed AppDir.
+- Allow distro builds without Qt private RHI headers by auto-disabling the Vulkan preview renderer and keeping the OpenGL renderer available.
 
 ## [0.1.18.1] - 2026-02-19
 ### Other

README.md

@@ -59,6 +59,10 @@ Get PakFu from GitHub Releases:
 - macOS: `installer.pkg` (recommended) or `portable.zip`
 - Linux: `installer.AppImage` (recommended) or `portable.tar.gz`
 
+The Linux portable archive is a deployed runtime tree with Qt and non-Qt
+runtime libraries bundled. After extracting it, run `./pakfu` from the extracted
+directory.
+
 PakFu can also check for updates at runtime (GUI) and via CLI (`--check-updates`).
 
 ## Highlights
@@ -122,6 +126,11 @@ Notes:
 - Qt6 (Core, Gui, Network, Widgets, OpenGL, OpenGLWidgets, Multimedia, MultimediaWidgets)
 - Windows: `DbgHelp` (system library, used for crash reporting)
 
+The Vulkan 3D preview renderer is optional at build time. If Qt private RHI
+headers are unavailable, Meson builds the OpenGL preview path instead; use
+`-Dvulkan_preview=enabled` to require Vulkan or `-Dvulkan_preview=disabled` to
+force the portable OpenGL-only build.
+
 See `docs/DEPENDENCIES.md` for full dependency details and packaging toolchain requirements.
 
 ### Windows Helper Build

docs/DEPENDENCIES.md

@@ -13,6 +13,10 @@
   - OpenGLWidgets (model preview: MDL/MD2/MD3/MDC/MD4/MDR/SKB/SKD/MDM/GLM/IQM/MD5/LWO/OBJ)
   - Multimedia (audio/video playback via available backend codecs; prefers FFmpeg when available)
   - MultimediaWidgets (video output: QVideoWidget)
+- Vulkan preview builds additionally need Qt's private RHI headers
+  (`rhi/qrhi.h` and `rhi/qshader.h`, for example from `qt6-base-private-dev`
+  on Debian-family distributions). When they are not available, Meson disables
+  the Vulkan preview automatically and keeps the OpenGL preview renderer.
 
 ## Release Packaging Toolchain
 - Windows:
@@ -22,7 +26,7 @@
   - `macdeployqt` (Qt deployment)
   - `pkgbuild` (native `.pkg` installer generation)
 - Linux:
-  - `linuxdeployqt` (downloaded in CI for AppImage packaging)
+  - `linuxdeployqt` (downloaded in CI for AppImage and portable runtime packaging)
   - AppImage runtime tooling (`APPIMAGE_EXTRACT_AND_RUN` flow in CI)
 
 ## Planned / Optional

docs/RELEASES.md

@@ -43,6 +43,10 @@ Required assets per platform:
 Current updater behavior prefers installer assets and falls back to portable
 archives when needed.
 
+Linux portable archives are produced from the same deployed AppDir used for the
+AppImage, so Qt and other runtime libraries are bundled in both Linux assets.
+The archive includes a top-level `pakfu` launcher for extracted-directory use.
+
 The release pipeline also emits:
 - `pakfu-<version>-release-manifest.json` (checksums + distribution metadata)
 - `CHANGELOG-<version>.md`

meson_options.txt

@@ -12,3 +12,10 @@ option(
   value: 'stable',
   description: 'Update channel selection.'
 )
+
+option(
+  'vulkan_preview',
+  type: 'feature',
+  value: 'auto',
+  description: 'Build the Vulkan 3D preview renderer when Qt private RHI headers are available.'
+)

scripts/package_linux.sh

@@ -52,15 +52,6 @@ icon_file="${app_dir}/usr/share/icons/hicolor/256x256/apps/pakfu-app.png"
 linuxdeployqt_tool="${out_dir}/linuxdeployqt-${linuxdeploy_arch}.AppImage"
 
 rm -rf "${portable_dir}" "${portable_archive}" "${installer_appimage}" "${app_dir}"
-mkdir -p "${portable_dir}"
-cp "${binary}" "${portable_dir}/pakfu"
-chmod +x "${portable_dir}/pakfu"
-if [[ -d "${root_dir}/assets" ]]; then
-  cp -R "${root_dir}/assets" "${portable_dir}/assets"
-fi
-tar -czf "${portable_archive}" -C "${out_dir}" "$(basename "${portable_dir}")"
-echo "Packaged portable archive: ${portable_archive}"
-
 mkdir -p "$(dirname "${desktop_file}")" "$(dirname "${icon_file}")" "${app_dir}/usr/bin" "${app_dir}/usr/share/pakfu"
 cp "${binary}" "${app_dir}/usr/bin/pakfu"
 chmod +x "${app_dir}/usr/bin/pakfu"
@@ -93,7 +84,7 @@ if [[ ! -f "${linuxdeployqt_tool}" ]]; then
   chmod +x "${linuxdeployqt_tool}"
 fi
 
-find "${out_dir}" . -maxdepth 1 -type f -name "*.AppImage" ! -name "$(basename "${linuxdeployqt_tool}")" -delete
+find "${out_dir}" -maxdepth 1 -type f -name "*.AppImage" ! -name "$(basename "${linuxdeployqt_tool}")" -delete
 
 disabled_plugins=()
 restore_disabled_plugins() {
@@ -120,16 +111,55 @@ if [[ -n "${qt_plugins_dir}" && -d "${qt_plugins_dir}" ]]; then
   done < <(find "${qt_plugins_dir}" -type f -name "*.so" | sort)
 fi
 
-export VERSION="${version}"
-APPIMAGE_EXTRACT_AND_RUN=1 "${linuxdeployqt_tool}" \
-  "${desktop_file}" \
-  -qmake="${qmake_bin}" \
-  -unsupported-allow-new-glibc \
-  -no-copy-copyright-files \
-  -bundle-non-qt-libs \
-  -appimage
+(
+  cd "${out_dir}"
+  export VERSION="${version}"
+  APPIMAGE_EXTRACT_AND_RUN=1 "./$(basename "${linuxdeployqt_tool}")" \
+    "PakFu.AppDir/usr/share/applications/pakfu.desktop" \
+    -qmake="${qmake_bin}" \
+    -unsupported-allow-new-glibc \
+    -no-copy-copyright-files \
+    -bundle-non-qt-libs \
+    -appimage
+)
+
+if [[ ! -e "${app_dir}/usr/lib/libQt6Core.so.6" ]]; then
+  echo "linuxdeployqt did not bundle libQt6Core.so.6 into ${app_dir}." >&2
+  exit 1
+fi
+
+pakfu_ldd="$(ldd "${app_dir}/usr/bin/pakfu" 2>/dev/null || true)"
+if printf "%s\n" "${pakfu_ldd}" | grep -q "not found"; then
+  echo "Packaged pakfu binary still has unresolved runtime dependencies:" >&2
+  printf "%s\n" "${pakfu_ldd}" >&2
+  exit 1
+fi
+
+app_dir_abs="$(cd "${app_dir}" && pwd)"
+if ! printf "%s\n" "${pakfu_ldd}" | grep -F "libQt6Core.so.6 => ${app_dir_abs}/" >/dev/null; then
+  echo "Packaged pakfu binary is not resolving Qt Core from the deployed AppDir." >&2
+  printf "%s\n" "${pakfu_ldd}" >&2
+  exit 1
+fi
+
+if [[ ! -x "${app_dir}/AppRun" ]]; then
+  echo "linuxdeployqt did not create an executable AppRun launcher in ${app_dir}." >&2
+  exit 1
+fi
+
+mkdir -p "${portable_dir}"
+cp -a "${app_dir}/." "${portable_dir}/"
+cat > "${portable_dir}/pakfu" <<'LAUNCHER'
+#!/usr/bin/env sh
+set -eu
+HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec "$HERE/AppRun" "$@"
+LAUNCHER
+chmod +x "${portable_dir}/pakfu"
+tar -czf "${portable_archive}" -C "${out_dir}" "$(basename "${portable_dir}")"
+echo "Packaged portable archive: ${portable_archive}"
 
-generated_appimage="$(find "${out_dir}" . -maxdepth 1 -type f -name "*.AppImage" ! -name "$(basename "${linuxdeployqt_tool}")" | head -n1)"
+generated_appimage="$(find "${out_dir}" -maxdepth 1 -type f -name "*.AppImage" ! -name "$(basename "${linuxdeployqt_tool}")" | sort | head -n1)"
 if [[ -z "${generated_appimage}" ]]; then
   echo "linuxdeployqt did not produce an AppImage." >&2
   exit 1

src/meson.build

@@ -5,12 +5,6 @@ conf.set('PAKFU_UPDATE_CHANNEL', get_option('update_channel'))
 
 cpp_compiler = meson.get_compiler('cpp')
 
-configure_file(
-  input: 'pakfu_config.h.in',
-  output: 'pakfu_config.h',
-  configuration: conf,
-)
-
 miniz_lib = static_library(
   'pakfu_miniz',
   files(
@@ -30,8 +24,10 @@ qt_libs = qt6_dep.get_variable(configtool: 'QT_INSTALL_LIBS', default_value: '')
 qt_version = qt6_dep.get_variable(configtool: 'QT_VERSION', default_value: '')
 
 fs = import('fs')
+vulkan_preview_opt = get_option('vulkan_preview')
 qt_rhi_includes = []
 qt_rhi_candidates = []
+qt_rhi_headers_found = false
 if qt_headers != '' and qt_version != ''
   qt_rhi_candidates += join_paths(qt_headers, 'QtGui', qt_version, 'QtGui')
   qt_rhi_candidates += join_paths(qt_headers, 'QtGui.framework', 'Headers', qt_version, 'QtGui')
@@ -50,12 +46,32 @@ if qt_libs != ''
 endif
 
 foreach path : qt_rhi_candidates
-  if fs.exists(join_paths(path, 'rhi', 'qshader.h'))
+  if fs.exists(join_paths(path, 'rhi', 'qrhi.h')) and fs.exists(join_paths(path, 'rhi', 'qshader.h'))
+    qt_rhi_headers_found = true
     qt_rhi_includes += include_directories(path)
     break
   endif
 endforeach
 
+if vulkan_preview_opt.enabled() and not qt_rhi_headers_found
+  error('Vulkan preview requires Qt private RHI headers (rhi/qrhi.h and rhi/qshader.h). Install the Qt private development headers or configure with -Dvulkan_preview=disabled.')
+endif
+
+vulkan_preview_enabled = qt_rhi_headers_found and not vulkan_preview_opt.disabled()
+conf.set('PAKFU_WITH_VULKAN_PREVIEW', vulkan_preview_enabled ? 1 : 0)
+
+if vulkan_preview_enabled
+  message('Vulkan preview renderer enabled.')
+else
+  message('Vulkan preview renderer disabled; OpenGL preview remains available.')
+endif
+
+configure_file(
+  input: 'pakfu_config.h.in',
+  output: 'pakfu_config.h',
+  configuration: conf,
+)
+
 pakfu_includes = [include_directories('.')] + qt_rhi_includes
 
 sources = files(
@@ -111,9 +127,7 @@ sources = files(
   'ui/cinematic_player_widget.cpp',
   'ui/video_player_widget.cpp',
   'ui/bsp_preview_widget.cpp',
-  'ui/bsp_preview_vulkan_widget.cpp',
   'ui/model_viewer_widget.cpp',
-  'ui/model_viewer_vulkan_widget.cpp',
   'ui/shader_viewer_widget.cpp',
   'ui/preview_pane.cpp',
   'ui/pak_tab.cpp',
@@ -124,23 +138,40 @@ sources = files(
   'update/update_service.cpp',
 )
 
+if vulkan_preview_enabled
+  sources += files(
+    'ui/bsp_preview_vulkan_widget.cpp',
+    'ui/model_viewer_vulkan_widget.cpp',
+  )
+endif
+
 rcc_sources = qt6.preprocess(
   qresources: ['resources.qrc'],
 )
 
-moc_sources = qt6.preprocess(
-  moc_headers: [
-    'update/update_service.h',
-    'ui/splash_screen.h',
-    'ui/breadcrumb_bar.h',
-    'ui/cinematic_player_widget.h',
-    'ui/video_player_widget.h',
+moc_headers = [
+  'update/update_service.h',
+  'ui/splash_screen.h',
+  'ui/breadcrumb_bar.h',
+  'ui/cinematic_player_widget.h',
+  'ui/video_player_widget.h',
+  'ui/preview_pane.h',
+  'ui/pak_tab.h',
+  'ui/preferences_tab.h',
+]
+moc_extra_arguments = []
+
+if vulkan_preview_enabled
+  moc_headers += [
     'ui/bsp_preview_vulkan_widget.h',
     'ui/model_viewer_vulkan_widget.h',
-    'ui/preview_pane.h',
-    'ui/pak_tab.h',
-    'ui/preferences_tab.h',
-  ],
+  ]
+  moc_extra_arguments += ['-DPAKFU_WITH_VULKAN_PREVIEW=1']
+endif
+
+moc_sources = qt6.preprocess(
+  moc_headers: moc_headers,
+  moc_extra_arguments: moc_extra_arguments,
 )
 sources += rcc_sources
 sources += moc_sources

src/pakfu_config.h.in

@@ -3,3 +3,4 @@
 #define PAKFU_VERSION "@PAKFU_VERSION@"
 #define PAKFU_GITHUB_REPO "@PAKFU_GITHUB_REPO@"
 #define PAKFU_UPDATE_CHANNEL "@PAKFU_UPDATE_CHANNEL@"
+#define PAKFU_WITH_VULKAN_PREVIEW @PAKFU_WITH_VULKAN_PREVIEW@

src/ui/bsp_preview_vulkan_widget.h

@@ -1,5 +1,9 @@
 #pragma once
 
+#include "pakfu_config.h"
+
+#if PAKFU_WITH_VULKAN_PREVIEW
+
 #include <QtWidgets/qrhiwidget.h>
 #include <QColor>
 #include <QElapsedTimer>
@@ -212,3 +216,33 @@ class BspPreviewVulkanWidget final : public QRhiWidget {
 	bool pipeline_dirty_ = true;
 	bool uniform_dirty_ = true;
 };
+
+#else
+
+#include <QColor>
+#include <QHash>
+#include <QImage>
+#include <QString>
+#include <QWidget>
+
+#include "formats/bsp_preview.h"
+#include "ui/preview_3d_options.h"
+
+class BspPreviewVulkanWidget final : public QWidget {
+public:
+	explicit BspPreviewVulkanWidget(QWidget* parent = nullptr) : QWidget(parent) {}
+	~BspPreviewVulkanWidget() override = default;
+
+	void set_mesh(BspMesh, QHash<QString, QImage>) {}
+	void set_lightmap_enabled(bool) {}
+	void set_grid_mode(PreviewGridMode) {}
+	void set_background_mode(PreviewBackgroundMode, const QColor&) {}
+	void set_wireframe_enabled(bool) {}
+	void set_textured_enabled(bool) {}
+	void set_fov_degrees(int) {}
+	[[nodiscard]] PreviewCameraState camera_state() const { return {}; }
+	void set_camera_state(const PreviewCameraState&) {}
+	void clear() {}
+};
+
+#endif