feat: add AppImage build via GitHub Actions + vcpkg buildenv

Add AppImage build support using the project's vcpkg buildenv on GitHub
Actions (Ubuntu 24.04). Key changes:

- New CI workflow: .github/workflows/appimage.yml (workflow_call for publishing)
- AppImage matrix entry in build.yml (reuses configure/build/cache infrastructure)
- Build script: packaging/appimage/build-appimage.sh (bundles system libs
  via ldd loop, copies Qt plugins/QML with system fallback)
- AppRun entry point: packaging/appimage/AppRun.sh
- CMake: MIXXX_APPIMAGE option for codec bundling, LINK_GROUP:RESCAN for
  static FFmpeg cross-dependencies
- FindGLIB.cmake: prefer system shared GLib over vcpkg static GLib
- FindSndFile.cmake: add Opus dependency
- linux_appimage_buildenv.sh: buildenv setup + build dependencies
- release.yml: calls appimage.yml for publishing (like Flatpak)
- Buildenv: tools/linux_appimage_buildenv.sh

Author: sleepwalkera

.github/workflows/appimage.yml

@@ -0,0 +1,58 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow
+
+name: AppImage
+
+on:
+  workflow_call:
+    inputs:
+      run_id:
+        type: string
+        required: true
+      ref:
+        type: string
+        required: true
+    secrets:
+      DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY:
+        required: false
+      DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY_PASSWORD:
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  publish-appimage:
+    name: Publish AppImage
+    runs-on: ubuntu-24.04
+    steps:
+      - name: "Download AppImage artifact"
+        uses: actions/download-artifact@v4
+        with:
+          name: Mixxx-AppImage-x86_64
+          path: build/
+          run-id: ${{ inputs.run_id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: "Publish AppImage"
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY }}
+        if: env.SSH_PRIVATE_KEY != null
+        run: |
+          # TODO: Publish to downloads.mixxx.org
+          #
+          # Implementation steps (when secrets are available):
+          #
+          # 1. Set up SSH agent with DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY
+          #    (see flatpak.yml for the SSH agent setup pattern)
+          #
+          # 2. Determine deploy path (same logic as build.yml's prepare_deploy):
+          #    - Tags:  releases/{git_describe}/mixxx-{git_describe}-linux-appimage{ext}
+          #    - Main:  snapshots/{git_branch}/mixxx-{git_describe}-linux-appimage{ext}
+          #
+          # 3. Upload to downloads.mixxx.org using:
+          #    - rsync over SSH
+          #    - or tools/deploy.py prepare-deployment + rsync
+          #
+          # 4. After upload, update the download manifest (tools/deploy.py or similar).
+          echo "Publishing AppImage for ref: ${{ inputs.ref }}"
+          ls -la build/

.github/workflows/build.yml

@@ -194,6 +194,29 @@ jobs:
             compiler_cache_path: /home/runner/.cache/ccache
             crosscompile: true
             arch: arm64
+          - name: AppImage Linux x86_64
+            os: ubuntu-24.04
+            cmake_args: >-
+              -DQT6=ON
+              -DQML=ON
+              -DMIXXX_APPIMAGE=ON
+              -DINSTALL_USER_UDEV_RULES=OFF
+              -DPKG_CONFIG_EXECUTABLE=/usr/bin/pkg-config
+              -DCMAKE_MODULE_PATH="${GITHUB_WORKSPACE}/packaging/appimage"
+              -DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O2 -DNDEBUG"
+              -DCMAKE_INSTALL_PREFIX=/
+            ctest_args: []
+            cpack_generator: AppImage
+            crosscompile: true
+            compiler_cache: ccache
+            compiler_cache_path: /home/runner/.cache/ccache
+            compiler_cache_id: appimage-qt6
+            buildenv_basepath: /home/runner/buildenv
+            buildenv_script: tools/linux_appimage_buildenv.sh
+            artifacts_name: AppImage Linux x86_64
+            artifacts_path: build/*.AppImage
+            artifacts_slug: linux-appimage
+            arch: x86_64
 
     env:
       # macOS codesigning
@@ -481,9 +504,13 @@ jobs:
           dotnet.exe tool install --global wix --version 6.0.2
           wix extension add --global WixToolset.UI.wixext/6.0.2
 
+      - name: "[AppImage] Install appimagetool"
+        if: matrix.cpack_generator == 'AppImage'
+        run: packaging/appimage/install-appimagetool.sh ${{ matrix.arch }}
+
       - name: "Package"
         id: package
-        if: matrix.cpack_generator != null
+        if: matrix.cpack_generator != null && matrix.cpack_generator != 'AppImage'
         # Use retry loop to work around a race condition on macOS causing
         # 'Resource busy' errors with 'hdiutil'. See
         # https://github.com/actions/runner-images/issues/7522
@@ -496,6 +523,21 @@ jobs:
             cd build
             cpack -G ${{ matrix.cpack_generator }} -V
 
+      - name: "[AppImage] Package"
+        if: matrix.cpack_generator == 'AppImage'
+        run: |
+          GIT_DESC=$(git describe --always --first-parent --dirty=-modified)
+          packaging/appimage/build-appimage.sh build ${{ matrix.arch }}
+          mv build/Mixxx-${{ matrix.arch }}.AppImage "build/Mixxx-${GIT_DESC}-${{ matrix.arch }}.AppImage"
+
+      - name: "[AppImage] Upload AppImage"
+        if: matrix.cpack_generator == 'AppImage'
+        uses: actions/upload-artifact@v4
+        with:
+          name: Mixxx-AppImage-${{ matrix.arch }}
+          path: ${{ matrix.artifacts_path }}
+          if-no-files-found: error
+
       - name: Upload failed packaging logs
         if: always() && steps.package.outcome == 'failure' && runner.os == 'windows'
         uses: actions/upload-artifact@v7

.github/workflows/release.yml

@@ -65,6 +65,18 @@ jobs:
       DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY: ${{ secrets.DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY }}
       RRYAN_AT_MIXXX_DOT_ORG_GPG_PRIVATE_KEY: ${{ secrets.RRYAN_AT_MIXXX_DOT_ORG_GPG_PRIVATE_KEY }}
 
+  publish-appimage:
+    needs:
+      - build
+    uses: ./.github/workflows/appimage.yml
+    if: ${{ (github.ref_type == 'tag' && !contains('-', github.ref_name)) || github.ref_name == 'main' }}
+    with:
+      ref: ${{ github.ref }}
+      run_id: ${{ github.run_id }}
+    secrets:
+      DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY: ${{ secrets.DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY }}
+      DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY_PASSWORD: ${{ secrets.DOWNLOADS_HOSTGATOR_DOT_MIXXX_DOT_ORG_KEY_PASSWORD }}
+
   sync:
     if: ${{ github.ref_type != 'tag' && github.ref != 'refs/heads/main' && github.repository == 'mixxxdj/mixxx' }}
     uses: ./.github/workflows/sync_branches.yml

CMakeLists.txt

@@ -99,7 +99,7 @@ if(CMAKE_SYSTEM_NAME STREQUAL Android)
 endif()
 
 if(
-  ((APPLE AND NOT IOS) OR WIN32 OR ANDROID)
+  (DEFINED ENV{BUILDENV_URL} OR (APPLE AND NOT IOS) OR WIN32 OR ANDROID)
   AND NOT IS_DIRECTORY "${MIXXX_VCPKG_ROOT}"
 )
   if(NOT DEFINED BUILDENV_BASEPATH)
@@ -403,6 +403,7 @@ endif()
 include(CMakeDependentOption)
 
 option(QT6 "Build with Qt6" ON)
+option(MIXXX_APPIMAGE "Build for AppImage distribution (bundle dlopen dependencies)" OFF)
 cmake_dependent_option(
   QML
   "Build with QML"
@@ -540,6 +541,19 @@ include(GNUInstallDirs)
 include(DefaultOption)
 include(IsStaticLibrary)
 
+if(DEFINED MIXXX_VCPKG_ROOT AND UNIX AND NOT APPLE)
+  # Prepend system paths to find the system's shared GLib instead of the
+  # vcpkg static GLib (which causes constructor-ordering issues when linked
+  # alongside static FFmpeg via LINK_GROUP:RESCAN).
+  # CMAKE_LIBRARY_ARCHITECTURE is set automatically on Debian-based systems.
+  if(CMAKE_LIBRARY_ARCHITECTURE)
+    list(PREPEND CMAKE_PREFIX_PATH
+      "/usr/lib/${CMAKE_LIBRARY_ARCHITECTURE}"
+      "/usr/lib/${CMAKE_LIBRARY_ARCHITECTURE}/cmake"
+    )
+  endif()
+endif()
+
 # Verify VCPKG settings
 if(DEFINED _VCPKG_INSTALLED_DIR)
   if(NOT EXISTS "${_VCPKG_INSTALLED_DIR}/${VCPKG_TARGET_TRIPLET}")
@@ -2632,6 +2646,19 @@ if(UNIX AND NOT APPLE)
     DESTINATION "${CMAKE_INSTALL_DATADIR}/applications"
   )
 
+  # AppImage desktop file (simplified Exec=mixxx)
+  if(MIXXX_APPIMAGE)
+    set(MIXXX_APPIMAGE_DESKTOP_FILE "${CMAKE_CURRENT_BINARY_DIR}/mixxx-appimage.desktop")
+    file(READ "${CMAKE_CURRENT_SOURCE_DIR}/res/linux/org.mixxx.Mixxx.desktop" MIXXX_APPIMAGE_DESKTOP_CONTENT)
+    string(REGEX REPLACE "\nExec=[^\n]*" "\nExec=mixxx" MIXXX_APPIMAGE_DESKTOP_CONTENT "${MIXXX_APPIMAGE_DESKTOP_CONTENT}")
+    file(WRITE "${MIXXX_APPIMAGE_DESKTOP_FILE}" "${MIXXX_APPIMAGE_DESKTOP_CONTENT}")
+    install(
+      FILES "${MIXXX_APPIMAGE_DESKTOP_FILE}"
+      DESTINATION "${CMAKE_INSTALL_DATADIR}/applications"
+      RENAME "mixxx-appimage.desktop"
+    )
+  endif()
+
   # Icon files for menu entry
   install(
     DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/res/images/icons/"
@@ -2843,7 +2870,19 @@ if(FFMPEG)
       __STDC_FORMAT_MACROS
   )
 
-  target_link_libraries(mixxx-lib PRIVATE FFmpeg::FFmpeg)
+  # Static FFmpeg libraries have cross-references (e.g. libavformat references
+  # av_adts_header_parse from libavcodec).  LINK_GROUP:RESCAN wraps them in
+  # --start-group/--end-group so the GNU linker resolves these.  Harmless for
+  # shared builds; Apple's ld64 does not support the group flags.
+  if(UNIX AND NOT APPLE)
+    target_link_libraries(
+      mixxx-lib
+      PRIVATE
+        "$<LINK_GROUP:RESCAN,FFmpeg::avformat,FFmpeg::avcodec,FFmpeg::avutil,FFmpeg::swresample>"
+    )
+  else()
+    target_link_libraries(mixxx-lib PRIVATE FFmpeg::FFmpeg)
+  endif()
   target_include_directories(mixxx-lib PUBLIC "${FFmpeg_INCLUDE_DIRS}")
 endif()
 
@@ -5009,6 +5048,37 @@ else()
   message(STATUS "Could NOT find fdk-aac (FdkAac_FOUND is FALSE)")
 endif()
 
+# Bundle codec libraries that Mixxx loads at runtime via QLibrary (dlopen).
+# The vcpkg buildenv provides static (.a) versions, but QLibrary needs the
+# shared (.so.*) files with versioned sonames (e.g. libfaad.so.2).
+if(MIXXX_APPIMAGE)
+  set(_suffixes "${CMAKE_FIND_LIBRARY_SUFFIXES}")
+
+  # libfaad: loader always expects libfaad.so.2
+  set(CMAKE_FIND_LIBRARY_SUFFIXES ".so.2")
+  find_library(FAAD_LIBRARY NAMES faad)
+  if(FAAD_LIBRARY)
+    install(FILES "${FAAD_LIBRARY}" DESTINATION "${CMAKE_INSTALL_LIBDIR}")
+  endif()
+
+  # libfdk-aac: loader probes .so.1 first, then .so.2 — try both
+  unset(FDKAAC_LIBRARY CACHE)
+  foreach(_soname IN ITEMS 1 2)
+    set(CMAKE_FIND_LIBRARY_SUFFIXES ".so.${_soname}")
+    find_library(FDKAAC_LIBRARY NAMES fdk-aac)
+    if(FDKAAC_LIBRARY)
+      break()
+    endif()
+  endforeach()
+  if(FDKAAC_LIBRARY)
+    install(FILES "${FDKAAC_LIBRARY}" DESTINATION "${CMAKE_INSTALL_LIBDIR}")
+  else()
+    message(WARNING "libfdk-aac not found — fdk-aac encoding will be unavailable in the AppImage")
+  endif()
+
+  set(CMAKE_FIND_LIBRARY_SUFFIXES "${_suffixes}")
+endif()
+
 # Google PerfTools
 option(GPERFTOOLS "Google PerfTools libtcmalloc linkage" OFF)
 option(GPERFTOOLSPROFILER "Google PerfTools libprofiler linkage" OFF)

cmake/modules/FindGLIB.cmake

@@ -46,10 +46,24 @@ if(PkgConfig_FOUND)
   pkg_check_modules(PC_GLIB QUIET glib-2.0)
 endif()
 
+# Prefer the system's shared GLib over the vcpkg buildenv's static GLib.
+# The vcpkg static GLib, when linked alongside static FFmpeg via
+# LINK_GROUP:RESCAN, pulls in extra symbols whose constructor ordering
+# crashes on startup. Search the system library dir first.
+# CMAKE_LIBRARY_ARCHITECTURE is set automatically on Debian-based systems.
+if(CMAKE_LIBRARY_ARCHITECTURE)
+  set(_glib_system_libdir "/usr/lib/${CMAKE_LIBRARY_ARCHITECTURE}")
+else()
+  set(_glib_system_libdir "")
+endif()
 find_library(
   GLIB_LIBRARIES
   NAMES glib-2.0
-  HINTS ${PC_GLIB_LIBDIR} ${PC_GLIB_LIBRARY_DIRS}
+  HINTS
+    ${_glib_system_libdir}
+    ${PC_GLIB_LIBDIR}
+    ${PC_GLIB_LIBRARY_DIRS}
+  NO_CMAKE_FIND_ROOT_PATH
 )
 
 # Files in glib's main include path may include glibconfig.h, which,
@@ -111,13 +125,14 @@ endif()
 # glib ones.
 foreach(component ${GLIB_FIND_COMPONENTS})
   if(${component} STREQUAL "gio")
-    find_library(GLIB_GIO_LIBRARIES NAMES gio-2.0 HINTS ${_GLIB_LIBRARY_DIR})
+    find_library(GLIB_GIO_LIBRARIES NAMES gio-2.0 HINTS ${_GLIB_LIBRARY_DIR} NO_CMAKE_FIND_ROOT_PATH)
     set(ADDITIONAL_REQUIRED_VARS ${ADDITIONAL_REQUIRED_VARS} GLIB_GIO_LIBRARIES)
   elseif(${component} STREQUAL "gobject")
     find_library(
       GLIB_GOBJECT_LIBRARIES
       NAMES gobject-2.0
       HINTS ${_GLIB_LIBRARY_DIR}
+      NO_CMAKE_FIND_ROOT_PATH
     )
     set(
       ADDITIONAL_REQUIRED_VARS
@@ -129,6 +144,7 @@ foreach(component ${GLIB_FIND_COMPONENTS})
       GLIB_GMODULE_LIBRARIES
       NAMES gmodule-2.0
       HINTS ${_GLIB_LIBRARY_DIR}
+      NO_CMAKE_FIND_ROOT_PATH
     )
     set(
       ADDITIONAL_REQUIRED_VARS
@@ -140,6 +156,7 @@ foreach(component ${GLIB_FIND_COMPONENTS})
       GLIB_GTHREAD_LIBRARIES
       NAMES gthread-2.0
       HINTS ${_GLIB_LIBRARY_DIR}
+      NO_CMAKE_FIND_ROOT_PATH
     )
     set(
       ADDITIONAL_REQUIRED_VARS

cmake/modules/FindSndFile.cmake

@@ -111,6 +111,15 @@ if(SndFile_FOUND)
         )
       endif()
 
+      find_package(Opus)
+      if(Opus_FOUND)
+        set_property(
+          TARGET SndFile::sndfile
+          APPEND
+          PROPERTY INTERFACE_LINK_LIBRARIES Opus::Opus
+        )
+      endif()
+
       # The mpg123 dependency was introduced in libsndfile 1.1.0
       if(SndFile_VERSION VERSION_GREATER_EQUAL "1.1.0")
         find_package(mpg123 CONFIG)

packaging/appimage/AppRun.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# AppImage entry point (AppRun).
+# Sets up the environment so the bundled libraries, Qt plugins, QML modules,
+# and data files are found at runtime.
+set -euo pipefail
+
+APPDIR="$(dirname "$(readlink -f "$0")")"
+
+# Library and Qt paths
+export LD_LIBRARY_PATH="${APPDIR}/usr/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
+export QT_PLUGIN_PATH="${APPDIR}/usr/plugins"
+export QML2_IMPORT_PATH="${APPDIR}/usr/qml"
+export QT_QPA_PLATFORM_PLUGIN_PATH="${APPDIR}/usr/plugins/platforms"
+
+# XDG data dirs
+export XDG_DATA_DIRS="${APPDIR}/usr/share:${XDG_DATA_DIRS:-}"
+
+# Set HOME if not set (minimal environments)
+if [ -z "${HOME:-}" ]; then
+  HOME="${APPDIR}/../.mixxx-home"
+  mkdir -p "$HOME" 2>/dev/null || true
+fi
+
+exec "${APPDIR}/usr/bin/mixxx" "$@"

packaging/appimage/FindXKB.cmake

@@ -0,0 +1,31 @@
+# FindXKB module for the vcpkg buildenv, which does not bundle Qt6's XKB config.
+if(NOT TARGET XKB::XKB)
+  find_package(PkgConfig QUIET)
+  if(PkgConfig_FOUND)
+    pkg_check_modules(xkbcommon IMPORTED_TARGET xkbcommon)
+    if(xkbcommon_FOUND)
+      add_library(XKB::XKB ALIAS PkgConfig::xkbcommon)
+      set(XKB_FOUND TRUE)
+      set(XKB_LIBRARY ${xkbcommon_LIBRARIES})
+      set(XKB_INCLUDE_DIR ${xkbcommon_INCLUDE_DIRS})
+      set(XKB_VERSION ${xkbcommon_VERSION})
+    endif()
+  endif()
+endif()
+if(NOT XKB_FOUND)
+  find_path(XKB_INCLUDE_DIR xkbcommon/xkbcommon.h)
+  find_library(XKB_LIBRARY xkbcommon)
+  if(XKB_INCLUDE_DIR AND XKB_LIBRARY)
+    set(XKB_FOUND TRUE)
+  endif()
+endif()
+if(XKB_FOUND)
+  if(NOT TARGET XKB::XKB)
+    add_library(XKB::XKB UNKNOWN IMPORTED)
+    set_target_properties(XKB::XKB PROPERTIES
+      IMPORTED_LOCATION "${XKB_LIBRARY}"
+      INTERFACE_INCLUDE_DIRECTORIES "${XKB_INCLUDE_DIR}"
+    )
+  endif()
+endif()
+mark_as_advanced(XKB_LIBRARY XKB_INCLUDE_DIR)