Repository navigation
Development Build and Test
Prepare the development environment first. Commands below run from the ZkMacOS repository root.
./scripts/build-app.sh --iterm--iterm opens a new iTerm window so the build remains visible. Omit it to use the current terminal. The script fetches pinned source/dependencies, builds Mesa, the engine/AI, lobby and ARM64 helper, then packages and audits dist/Zero-K.app.
The terminal shows named stages and elapsed time. A separate Engine compilation bar uses Ninja’s completed/total task counts and percentage. Compiler warnings and elapsed time do not advance it. Cached builds report no compilation work; tasks without measurable progress use a spinner. Use --verbose for full live output or --plain for ordinary text. CI and redirected output use plain logs automatically.
Full logs are in build/logs/; build.log contains the pipeline output and build-result.json records completion. Stage logs include engine-build.log, client-build.log, helper-build.log, package.log and app-audit.json. The older Mono build also writes build/launcher-build.log. A checkout lock prevents concurrent build/release pipelines from replacing each other’s outputs.
Close a running copy of dist/Zero-K.app before rebuilding it. To open the result:
./scripts/run-app.shThat command launches another app instance; do not use it when a game you want to keep is already running. You can instead open the built app yourself when ready.
Ninja recompiles affected engine files and relinks. Lobby, helper, defaults and packaging edits do not require cleaning the engine. Existing source downloads, Mesa and compiler outputs are reused when their inputs match. Adjust BUILD_JOBS for your machine; the normal default is five engine jobs.
When changing toolchain options, force configuration without deleting the cache:
RECONFIGURE_ENGINE=1 ./scripts/build-app.shOrdinary local builds without SPARKLE_PUBLIC_ED_KEY omit updater configuration and do not check for updates. A release build embeds the production public key; see Creating a Release.
Run checks appropriate to the code changed. All Lua settings checks can be run together:
for check in tests/check-*.lua; do luajit "$check" || break; doneluajit tests/check-settings.lua
luajit tests/check-display-sync.lua
luajit tests/check-display-link-settings.lua
luajit tests/check-trackpad-settings.lua
luajit tests/check-macos-announcement.lua
uv run --python python3 tests/check-cask.py
uv run --no-project --python python3 --with cryptography==46.0.3 python tests/check-appcast.py
swiftc -D UPDATE_CHECK_TESTS -framework AppKit -F .cache/sparkle-2.10.1 -framework Sparkle \
-Xlinker -rpath -Xlinker "$PWD/.cache/sparkle-2.10.1" \
app/main.swift tests/check-updates.swift -o build/check-updates
build/check-updates
clang++ -std=c++17 -fblocks -framework AppKit -I external/recoil/rts \
$(sdl2-config --cflags) tests/check-update-menu.mm \
external/recoil/rts/System/Platform/Mac/WindowManagerHelper.cpp \
$(sdl2-config --libs) -o build/check-update-menu
build/check-update-menu
uv run --python python3 scripts/audit-app.py
uv run --python python3 scripts/smoke-app.py --seconds 90
uv run --python python3 scripts/smoke-download.pyThe relocation smoke test rebuilds the app, runs a bounded AI skirmish from a
moved copy, and checks bundle writes and host dependencies. It uses existing
game/map downloads without bundling them, limits engine unified memory to
8 GiB, and writes results under .local/relocation-test/. The downloader test
uses a private profile under .local/download-test/.
For graphics changes, test water reflections and refraction at Medium and High quality, all Retina modes, camera gestures, and window resizing. Keep test profiles separate from your normal Application Support data. See engine updates before changing the engine version; changing its reported version alone does not make a different simulation compatible with Zero-K's servers.
Generated builds, downloads, external source checkouts, and private test data are ignored by Git. Keep personal data and compiled applications out of source commits. Migration notes describe the original port's layout and where its changes now live.
The local release also runs tests/check-local-release.py with its pinned Rich/cryptography dependencies. To run it directly:
UV_CACHE_DIR="$PWD/build/uv-cache" uv run --no-project --python python3 \
--with rich==14.2.0 --with cryptography==46.0.3 python tests/check-local-release.pyFor native rendering probes and retained measurements, see MetalFX/GPU sharing/DisplayLink and HDR. Development Validation tracks broader testing that automated checks do not replace.
Read the first failing stage and its full log. Check that the SDK selected by global.json, Xcode SDK, GCC 16, Mono msbuild, and Homebrew dependencies are available. A permissions or missing-tool error is not evidence of a source-code defect.
If configuration still contains an old engine version after changing pins, reconfigure with RECONFIGURE_ENGINE=1, then check the app audit and spring --sync-version. Do not delete all caches as the first response to a packaging-only change.
If the error says another pipeline is running, let that build/release finish. If packaging says the built app is running, finish or quit that specific app before replacing it. Preserve failing logs for a bug report.
ZkMacOS source · Download the DMG · Report a bug · Get help
Unofficial, experimental Zero-K client. These guides describe the current source; older releases may differ.
- Getting Started
- Playing Zero-K
- Development
- Contributing
- Environment Setup
- Build and Release
- Internals and Validation
- Licensing and Credits
- Source · Downloads