Building and Running

Building and running

How to build Open Wallpaper Engine from source, run it without touching your real data, and point it at test assets and libraries.

Prerequisites

Requirement	Version
macOS	14 or later to run the app; building needs Xcode 26's requirements
Xcode	26.3 or newer (the macOS 26 SDK, which Liquid Glass needs). CI and releases use 26.3.
Command Line Tools	Installed

Nothing else: glslang and SPIRV-Cross are built from source in Vendor/ShaderToolchain as a local Swift package. No Wallpaper Engine files are in the repository.

Build

git clone https://github.com/deepratna-awale/open-wallpaper-engine-mac.git
cd open-wallpaper-engine-mac
open OpenWallpaperEngine.xcodeproj

• Scheme: OpenWallpaperEngine. Press ⌘R.
• The app's deployment target is macOS 14.0; the bundle ID is app.openwallpaperengine.

Signing

• Debug and Release builds sign with Apple Development. macOS ties the audio-capture grant (System Audio Recording, or Screen Recording before macOS 14.2) to the signature, and ad-hoc signing loses it on every rebuild.
• Not on the project's team? Set your own team in Signing & Capabilities and don't commit that change. "Sign to Run Locally" also works, at the cost of re-granting audio access after rebuilds.
• Release signing (Developer ID, notarization) happens in CI; see Releasing.

Entitlements

Not sandboxed; cs.allow-jit (JavaScriptCore for SceneScript), network client, user-selected files, Downloads read-only, the Photos library. ScreenCaptureKit audio is a privacy (TCC) prompt, not an entitlement.

Assets for development

Scenes need WE's assets. Either:

• run the app and use Settings › Assets with your Steam account, or
• copy them from a local WE install with the helper:

Scripts/fill-assets-cache.sh <WE install or its assets dir> [destination]

The destination defaults to the app's cache in the default storage folder (~/Documents/Open Wallpaper Engine/.owe-assets). Point it at a folder of your own and set OWE_ASSETS to it to run the asset-dependent tests. Nothing it copies may be committed. See Assets system.

Isolated state

Every build shares the bundle ID, so a development copy would read and overwrite your real playlists, per-screen wallpapers and safe-restart sentinel. Launch development copies isolated:

OWE_ISOLATED_STATE=shots "<build>/Open Wallpaper Engine.app/Contents/MacOS/Open Wallpaper Engine" \
  -CustomWallpapersDirectory <library>

or pass -OWEIsolatedState <tag>. An isolated copy uses:

Store	Isolated location
Defaults	the suite app.openwallpaperengine.isolated.<tag>
Application Support, Caches	Open Wallpaper Engine (isolated <tag>)
Keychain services	under app.openwallpaperengine.isolated.<tag>

Launch arguments (-Key value) still override defaults in the isolated suite, e.g. -CustomWallpapersDirectory <path>. Under XCTest the app isolates itself with the tag tests. AppStorageIsolationTests guards this.

Warning

Never launch a development copy (screenshots, smoke runs, automated runs) against the real domain.

Useful environment variables

Variable	Use
OWE_ISOLATED_STATE	Isolate state, as above
OWE_ASSETS	Assets folder (or WE install) for tests
OWE_LIBRARY	Wallpaper library root(s) for library tests
OWE_STEAMCMD_SEARCH_ROOT	Pretend no SteamCMD is installed, to try the installer

The full list is on Environment variables.

Logs while developing

Debug builds log at .info and above. Use /usr/bin/log (a bare log may be shadowed by your shell):

/usr/bin/log stream --predicate 'subsystem == "app.openwallpaperengine"' --level debug

Shaders the compiler rejected are written to ~/Library/Caches/app.openwallpaperengine/FailedShaders (an isolated copy uses ~/Library/Caches/Open Wallpaper Engine (isolated <tag>)/app.openwallpaperengine/FailedShaders).

User guide: Installing