Skip to content

Development Build and Test

smallketchup82 edited this page Oct 29, 2026 · 1 revision

Prepare the development environment first. Commands below run from the ZkMacOS repository root.

Build a local app

./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.sh

That 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.

Incremental builds

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.sh

Ordinary 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.

Checks

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; done
luajit 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.py

The 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.py

For native rendering probes and retained measurements, see MetalFX/GPU sharing/DisplayLink and HDR. Development Validation tracks broader testing that automated checks do not replace.

Build failures

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.

Clone this wiki locally