Building and releases

Prerequisites

Install the Zig version listed in .zigversion. build.zig.zon records the application version and dependency versions. The source files and libraries in vendor/ are required for a build.

Platform	Additional requirements
Windows x86_64	PowerShell; the first build downloads the pinned SDL2 MinGW package
Linux x86_64	C/C++ build tools; the SDL2 static library is included in vendor/
macOS x86_64 or arm64	Xcode command-line tools and brew install sdl2, or SDL2.framework

Ubuntu/Debian development and desktop dependencies:

sudo apt install build-essential libc++-dev libc++abi-dev zenity xdg-utils desktop-file-utils shared-mime-info

Linux file dialogs use zenity or kdialog. File associations use xdg-utils or gio. Windows and Linux releases include SDL2 in the executable. Linux still needs the system's graphics, audio, and glibc libraries. macOS packages include SDL2.

Build and test

Run these commands from the repository root. You can also invoke a script by its absolute path from another directory; it changes to the repository before building.

Task	Windows (PowerShell)	Linux (Bash)	macOS (Bash)
Build	./scripts/build-windows.ps1	bash scripts/build-linux.sh	bash scripts/build-macos.sh
Build and run	./scripts/build-windows.ps1 run	bash scripts/build-linux.sh run	bash scripts/build-macos.sh run
Regression tests	./scripts/build-windows.ps1 test	bash scripts/build-linux.sh test	bash scripts/build-macos.sh test
Release build	./scripts/build-windows.ps1 -Optimize ReleaseSafe	OPTIMIZE=ReleaseSafe bash scripts/build-linux.sh	OPTIMIZE=ReleaseSafe bash scripts/build-macos.sh

To build a Linux executable from Windows, run ./scripts/build-linux.ps1. Use ./scripts/build-linux.ps1 test-build to compile the Linux tests without running them. The PowerShell scripts target x86_64. The macOS script uses the host CPU unless you set TARGET to another macOS architecture.

Development builds use Debug mode by default. run and test execute on the current machine, so run cross-compiled tests on their target system. The test command compiles the test executable without building the GUI executable.

PowerShell accepts -Zig, -Optimize, -Sdl2Prefix, -Prefix, and -BuildArgs. Bash uses ZIG, TARGET, OPTIMIZE, SDL2_PREFIX, and INSTALL_PREFIX. A Bash TARGET override must match the script's platform. Additional script arguments go to zig build:

./scripts/build-windows.ps1 run -BuildArgs @('--', '--version')
./scripts/build-windows.ps1 test -BuildArgs @('--summary', 'all')

bash scripts/build-linux.sh run -- --version
bash scripts/build-linux.sh test --summary all
bash scripts/build-macos.sh run -- --version

To use a local SDL2 installation, set its root directory with -Sdl2Prefix or SDL2_PREFIX. Windows expects x86_64-w64-mingw32/lib/ inside that directory; Linux and macOS expect lib/. On macOS, you can instead set SDL2_FRAMEWORK_PATH to the directory containing SDL2.framework.

Outputs and cleanup

Path	Purpose
out/build/<target>/bin/	Executable for that target
out/build/zig-cache/	Local compiler cache and temporary unit-test files
out/build/zig-global-cache/	Shared compiler cache, including the Windows resource compiler
out/dist/	Release ZIPs; packaging stages files in temporary folders here
out/docs/	Documentation site and npm download cache
docs/node_modules/	Installed documentation dependencies (ignored)
out/preview-qa/	Preview captures and playback measurements
out/compat/	Engine compatibility outputs

Each target gets its own executable directory. Packaging builds into a temporary folder and replaces the final ZIP only after the package is complete.

You can delete out/ to remove generated files. The build scripts recreate the directories they need. Running zig build directly uses Zig's default .zig-cache/ and zig-out/ directories unless you override them. Downloaded dependencies are stored in zig-pkg/. Git ignores these generated directories.

For a clean application build, remove out/build/ after builds have stopped. The next platform build recreates it. Remove out/docs/site/ to discard the built site, or docs/node_modules/ to remove installed documentation dependencies.

Release packages and publishing

Set .version in build.zig.zon before creating a release. Package commands use that version for the executable, application metadata, and ZIP filenames. They build in ReleaseSafe mode by default. Upload the resulting files with the separate publish command below.

# Both Windows and Linux portable ZIPs, built from Windows:
./scripts/release/package.ps1
# Or select one platform:
./scripts/release/package.ps1 -Platforms windows
./scripts/release/package.ps1 -Platforms linux

The PowerShell package script accepts -Zig, -Optimize, -Sdl2Prefix (Windows), and -LinuxSdl2Prefix. Archives include the CLI reference and dependency licenses. The Linux ZIP preserves the executable's Unix permissions.

bash scripts/release/package-linux.sh
TARGET=aarch64-macos bash scripts/release/package-macos.sh
TARGET=x86_64-macos bash scripts/release/package-macos.sh

Create the macOS package on macOS. Its ZIP contains an unsigned .app with its icons, SDL2, and dependency licenses. Extract the ZIP to use the app.

To upload the packages, install Butler and run:

./scripts/release/publish.ps1
./scripts/release/publish.ps1 -Platforms windows

The publish script reads the version from build.zig.zon and checks that every selected ZIP exists before it starts uploading. The destination channels are clydegames/packrat:windows and clydegames/packrat:linux. To upload a Linux archive directly, use butler push <zip> clydegames/packrat:linux --userversion <version>.

Preview and compatibility checks

The preview-smoke check opens a hidden OpenGL window and renders Preview Studio views. It checks playback, frame retention while loading, zoom, light dragging, and playback controls.

./scripts/build-windows.ps1 preview-smoke
./scripts/build-windows.ps1 preview-smoke -BuildArgs @('--', 'test/fixtures/game/characters', 'out/preview-qa/renders', 'compact')

bash scripts/build-linux.sh preview-smoke
bash scripts/build-linux.sh preview-smoke -- test/fixtures/game/characters out/preview-qa/renders compact

Use playback-benchmark to measure playback in the application. Its arguments, in order, are the source folder, loop count, background sprite count, FPS, and view (source, composite, or lit). Add hidden as the last argument to run offscreen. Hidden windows may be throttled by the graphics driver, so use a visible run to check on-screen playback. Wait for other builds and tests to finish before measuring:

bash scripts/build-linux.sh playback-benchmark -- test/fixtures/game/characters 10 5000 12 lit

The benchmark saves out/preview-qa/full-application.png. See the engine compatibility tests for checks in the target engines.

Documentation site

Install Node.js 22.12 or newer, then install the versions listed in the lockfile. The npm commands work on every platform:

npm ci --prefix docs --cache out/docs/npm-cache --no-audit --no-fund
npm --prefix docs run docs:dev
npm --prefix docs run docs:build
npm --prefix docs run docs:preview

Run these from the repository root. Rerun npm ci when the lockfile changes. Dependencies are installed in docs/node_modules/, which Git ignores. Development mode watches the files in docs/ and reloads when you edit them. The site uses the application icons from src/assets/.

The built site is written to out/docs/site/. On the Clyde Games server, choose Tools → Packrat → Rebuild Docs to rebuild it through the admin API. scripts/deploy-docs.sh updates the checkout with git pull --ff-only, then calls scripts/lib/install-docs-linux.sh to build and install the site at /var/www/packrat. Set DOCS_OUTPUT_DIR to use another destination. If the build fails, the existing site stays in place.

CI uses the same build, test, and package scripts. Compiler downloads are listed in the Zig download index. The macOS jobs select Intel and arm64 GitHub runners.