Building Releases

This guide explains how to build ZZAR releases for Windows and Linux using PyInstaller.

Overview

ZZAR uses PyInstaller to create standalone executables that bundle Python, dependencies, and assets into a single distributable file. The build configuration is defined in ZZAR.spec.

Prerequisites

Before building, ensure you have:

Python 3.14+ installed
All dependencies from requirements.txt installed
PyInstaller installed: pip install pyinstaller
A working ZZAR development environment (see Getting Started)

Build Configuration

The ZZAR.spec file controls the PyInstaller build. Key sections:

Included Files

added_files = [
    ('src/gui/qml', 'gui/qml'),                  # QML UI files
    ('src/gui/assets', 'gui/assets'),            # Images, logos
    ('src/gui/components', 'gui/components'),    # QML components
    ('src/gui/translations', 'gui/translations'),# i18n files
    ('src/resources', 'resources'),              # Other resources
    ('setup_wwise.py', '.'),                     # Wwise installer
    ('setup_windows_audio_tools.py', '.'),       # Windows audio tools
]

Hidden Imports

Modules that PyInstaller can’t auto-detect:

hiddenimports=[
    'gui.main_qml',
    'gui.backend.audio_browser_bridge',
    'gui.backend.audio_conversion_bridge',
    'gui.backend.import_worker',
    'gui.backend.mod_manager_bridge',
    'gui.backend.native_dialogs',
    'gui.backend.update_manager_bridge',
    'PIL',
    'PIL.Image',
    'PyQt5.QtMultimedia',
    'PyQt5.QtMultimediaWidgets',
    'PyQt5.QtNetwork',
]

Platform-Specific Settings

Windows

Bundles application icon: src/gui/assets/ZZAR-Logo2.ico
Creates windowed executable (no console)
Uses UPX compression

Linux

Bundles GStreamer plugins (for audio playback)
Bundles Qt Wayland plugins (for native Wayland support)
Bundles QtGraphicalEffects QML module
Excludes system libraries (libwayland, libssl) to avoid ABI mismatches

Flatpak Builds

For Flatpak builds, set the environment variable:

export ZZAR_FLATPAK_BUILD=1

This skips bundling system plugins that the Flatpak runtime provides.

Building on Windows

Prepare Environment

Ensure all dependencies are installed:

pip install -r requirements.txt
pip install pyinstaller

Run PyInstaller

Build the Windows executable:

pyinstaller ZZAR.spec

This creates:

build/ - Temporary build files (can be deleted)
dist/ZZAR.exe - Standalone executable

Test the Executable

Run the built executable:

dist\ZZAR.exe

Verify:

Application launches
GUI renders correctly
Audio conversion works
Mod installation works

Package for Distribution

Create a release archive:

# Create release folder
mkdir ZZAR-v1.1.0-Windows
copy dist\ZZAR.exe ZZAR-v1.1.0-Windows\

# Optional: Include README
copy README.md ZZAR-v1.1.0-Windows\

# Create ZIP archive
tar -a -c -f ZZAR-v1.1.0-Windows.zip ZZAR-v1.1.0-Windows

Building on Linux

Install System Dependencies

Install required system libraries:

# Debian/Ubuntu
sudo apt update
sudo apt install python3.14 python3-pip python3-pyqt5 \
  gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
  libxkbcommon-x11-0 libxcb-cursor0

# Arch Linux
sudo pacman -S python python-pip python-pyqt5 \
  gstreamer gst-plugins-good gst-plugins-bad \
  libxkbcommon-x11 xcb-util-cursor

Install Python Dependencies

pip install -r requirements.txt
pip install pyinstaller

Run PyInstaller

Build the Linux executable:

pyinstaller ZZAR.spec

This creates:

build/ - Temporary build files (can be deleted)
dist/ZZAR - Standalone executable

Test the Executable

Run the built executable:

./dist/ZZAR

Verify:

Application launches on Wayland and X11
Audio playback works (GStreamer)
Wwise conversion works (via Wine)
Mod installation works

Package for Distribution

Create a release archive:

# Create release folder
mkdir ZZAR-v1.1.0-Linux
cp dist/ZZAR ZZAR-v1.1.0-Linux/

# Optional: Include README
cp README.md ZZAR-v1.1.0-Linux/

# Create tarball
tar -czf ZZAR-v1.1.0-Linux.tar.gz ZZAR-v1.1.0-Linux

Build Options

Debug Build

For debugging, enable console output:

# In ZZAR.spec, change:
exe = EXE(
    ...
    console=True,  # Changed from False
    debug=True,     # Enable debug output
    ...
)

Then rebuild:

pyinstaller ZZAR.spec

Clean Build

Remove build artifacts before rebuilding:

rmdir /s /q build dist
del /q *.spec~
pyinstaller ZZAR.spec

Disable UPX Compression

If UPX causes issues (some antivirus flags it), disable it:

# In ZZAR.spec, change:
exe = EXE(
    ...
    upx=False,  # Changed from True
    ...
)

Troubleshooting

ImportError in Built Executable

Problem: Module not found when running built executable Solution: Add the module to hiddenimports in ZZAR.spec:

hiddenimports=[
    # ... existing imports ...
    'your.missing.module',
]

Missing QML Files

Problem: GUI doesn’t render, QML errors Solution: Verify QML files are included in added_files:

added_files = [
    ('src/gui/qml', 'gui/qml'),
    # ...
]

GStreamer Not Found (Linux)

Problem: Audio playback fails Solution: GStreamer plugins may not be bundled correctly. Check ZZAR.spec lines 38-54:

gst_plugin_dir = next((p for p in gst_search_paths if os.path.exists(p)), None)

if gst_plugin_dir:
    extra_binaries.append((gst_plugin_dir, 'gstreamer-1.0/'))

Ensure GStreamer is installed:

sudo apt install gstreamer1.0-plugins-good

libwayland ABI Mismatch (Linux)

Problem: Application crashes on startup with Wayland errors Solution: This is intentional. ZZAR excludes libwayland from the bundle (lines 150-152 in ZZAR.spec):

if not sys.platform.startswith('win'):
    exclude_prefixes = ('libwayland-', 'libssl', 'libcrypto')
    a.binaries = [b for b in a.binaries if not os.path.basename(b[0]).startswith(exclude_prefixes)]

These libraries must come from the user’s system to match their compositor.

Wwise Test Fails

Problem: Wwise conversion doesn’t work in built executable Solution: Ensure setup_wwise.py is bundled:

added_files = [
    ('setup_wwise.py', '.'),
    # ...
]

Wwise is downloaded on first launch, not bundled with the executable.

Build Automation

For CI/CD, automate builds with GitHub Actions:

name: Build Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.14'
      - run: pip install -r requirements.txt
      - run: pip install pyinstaller
      - run: pyinstaller ZZAR.spec
      - uses: actions/upload-artifact@v3
        with:
          name: ZZAR-Windows
          path: dist/ZZAR.exe

  build-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.14'
      - run: sudo apt install python3-pyqt5 gstreamer1.0-plugins-good
      - run: pip install -r requirements.txt
      - run: pip install pyinstaller
      - run: pyinstaller ZZAR.spec
      - uses: actions/upload-artifact@v3
        with:
          name: ZZAR-Linux
          path: dist/ZZAR

Release Checklist

Before releasing:

Update version in ZZAR.py (__version__)
Update README.md with new version
Test build on Windows
Test build on Linux
Verify audio playback works
Verify Wwise conversion works
Verify mod installation works
Create GitHub release with binaries
Update documentation site

Next Steps

Read the Development Guide to understand the codebase
Check GitHub Releases for build examples
Report build issues on GitHub Issues

Development

​Overview

​Prerequisites

​Build Configuration

​Included Files

​Hidden Imports

​Platform-Specific Settings

​Windows

​Linux

​Flatpak Builds

​Building on Windows

​Building on Linux

​Build Options

​Debug Build

​Clean Build

​Disable UPX Compression

​Troubleshooting

​ImportError in Built Executable

​Missing QML Files

​GStreamer Not Found (Linux)

​libwayland ABI Mismatch (Linux)

​Wwise Test Fails

​Build Automation

​Release Checklist

​Next Steps

Build docs developers (and LLMs) love