QSS-MBuild Guide

Quakespasm Spiked · Multiplayer

Build QSS-M
from source.

Copy-paste, caveman-proof instructions for every platform — Linux (all the popular distros), macOS, and Windows. These are the exact same recipes our GitHub Actions CI runs, so if it builds here, it builds for you.

Linux · one script macOS · universal Windows · MSYS2 / VS 📦 GitHub source

You need the retail Quake data first

QSS-M is the engine only. It cannot run without pak0.pak and pak1.pak from a registered copy of Quake, placed in an id1 folder next to the binary. Buy Quake on Steam (files live in steamapps/common/Quake/Id1) or dig out the original CD.

Get the code

Every platform below starts the same way. Clone once, then jump to your OS.

git clone https://github.com/timbergeron/QSS-M.git
cd QSS-M

Linux

Install the dev libraries for your distro, then run the one build script. Pick your family:

1Install dependencies
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libsdl2-dev \
  libgnutls28-dev libmad0-dev libopus-dev libopusfile-dev \
  libvorbis-dev zlib1g-dev libcurl4-openssl-dev zip
2Build & package
./build-linux.sh

Done. You get the QSS-M-l64 binary and a ready-to-ship Quake/QSS-M-l64.zip. Drop your id1 folder beside the binary and run it.

Prefer to drive make yourself?

Skip the script and compile directly — handy for quick dev iteration. The QSS_LDFLAGS below is required on GCC 10+ (Ubuntu 22.04+, current Fedora/Arch); without it the link fails with “multiple definition” errors:

cd Quake
make USE_SDL2=1 QSS_LDFLAGS="-Wl,--allow-multiple-definition" -j8

macOS

Builds a Universal app (Intel + Apple Silicon) via Xcode. Audio and TLS libraries are compiled statically with vcpkg on the first run.

1Install Xcode + build tools

Install Xcode from the App Store (the full IDE, not just the command-line tools), then the Homebrew helpers the crypto libraries need:

brew install autoconf automake libtool pkg-config autoconf-archive
2Build & package

One command does everything — it runs setup-vcpkg.sh to fetch and compile the static deps, then builds and zips the app. Run it as your normal user, never with sudo.

cd macOS
./build-macos.sh

# The first run pulls a pinned vcpkg checkout and builds every static dep
# (GnuTLS, Nettle, Opus, Vorbis, FLAC, ...) for both x86_64 and arm64 — go get a coffee.
# Later builds reuse the vcpkg cache and are much faster.

Done. Your universal QSS-M.app and QSS-M-macOS.zip land in macOS/build/Release/.

Working in Xcode directly?

If you skip the script and build the target yourself, run the dependency setup once first — otherwise the static libraries won't exist:

cd macOS
./setup-vcpkg.sh            # builds libs_universal/ for both arches
xcodebuild -project QuakeSpasm.xcodeproj -target QSS-M -configuration Release

Windows

Three proven paths. MSYS2 is the easiest if you're on Windows. You can also cross-compile the .exe from Linux — that's what our CI does. Visual Studio is there if you'd rather stay in the IDE.

Recommended · MSYS2 (MinGW-w64)
1Install MSYS2

Grab the installer from msys2.org. From the Start menu open the “MSYS2 MINGW64” shell (the blue one — not the plain UCRT/MSYS shell).

2Install the toolchain & libraries
pacman -S --needed git make zip \
  mingw-w64-x86_64-gcc mingw-w64-x86_64-pkgconf mingw-w64-x86_64-gnutls \
  mingw-w64-x86_64-SDL2 mingw-w64-x86_64-opus mingw-w64-x86_64-libvorbis \
  mingw-w64-x86_64-zlib mingw-w64-x86_64-curl
3Clone & build (64-bit)
git clone https://github.com/timbergeron/QSS-M.git
cd QSS-M/Quake
make -f Makefile.w64 USE_SDL2=1 SDL_CONFIG=sdl2-config -j8

Done. Out comes Quake/quakespasm.exe. Keep the SDL2/codec DLLs from the Windows/ folder beside it (the CI build scripts do this for you when packaging).

Want a 32-bit build?

Open the MSYS2 MINGW32 shell instead, install the matching mingw-w64-i686-* packages, and build with Makefile.w32.

Alternative · Cross-compile from Linux (MinGW-w64)

No Windows machine needed — these commands use the same cross-build scripts and targets as the windows.yml workflow. SDL2, curl, zlib and the audio codec import libraries are already vendored in the repo's Windows/ folder, so a normal local build only needs the cross toolchain and basic build utilities. CI additionally bootstraps GnuTLS for TLS-enabled artifacts.

1Install the MinGW-w64 cross toolchain
# Debian / Ubuntu / Mint — one package covers both 64- and 32-bit targets
sudo apt-get install -y build-essential git zip mingw-w64

On Fedora/RHEL that's mingw64-gcc mingw32-gcc; on Arch it's mingw-w64-gcc.

2Build & package
sh ./build-w64.sh          # 64-bit
sh ./build-w32.sh          # 32-bit

Done. The 64-bit command produces Quake/QSS-M-w64.exe and Quake/QSS-M-w64.zip; the 32-bit command produces the matching QSS-M-w32.exe and QSS-M-w32.zip. Each ZIP includes the required runtime DLLs.

# These scripts are checked in without the executable bit, so run them via sh
# (or chmod +x build-w64.sh first). Override the defaults with environment
# variables: MAKEARGS=-j16, TARGET_TRIPLET=, CROSS_PREFIX=, PKG_CONFIG=.

A word about TLS

Debian and friends ship no MinGW GnuTLS package. If pkg-config can't find a cross GnuTLS, the makefile prints building without USE_GNUTLS and carries on — you still get a perfectly good .exe, just without TLS support. To get a TLS-enabled build you have to cross-compile GnuTLS and its dependencies (GMP, Nettle, libtasn1) as static libraries first; the windows.yml workflow does this step by step and is the recipe to copy.

Alternative · Visual Studio 2022

Open Windows/VisualStudio/quakespasm.sln, select Release / x64, and hit Build. Or from a Developer prompt:

msbuild Windows\VisualStudio\quakespasm-sdl2.vcxproj ^
  -p:Configuration=Release -p:Platform=x64

Stuck? Read the CI

Every command on this page comes straight from the automated build recipes. If something drifts, the workflows are the source of truth:

linux.yml · macos.yml · MSYS2.yml · msvs.yml  —  plus the build-linux.sh, build-w64.sh, and macOS/build-macos.sh scripts in the repo root.