Building & Compiling

This document covers everything involved in turning the source tree into a running application: the Java/Maven build, and the native Swift helper that Java compiles for itself the first time it needs it.

1. Prerequisites

Tool	Why	Check
macOS	Dynamic Desktop is a macOS-only feature	`sw_vers`
JDK 17 or newer	Compiles and runs the Swing application	`java -version`
Apache Maven 3.6+	Drives the Java build	`mvn -version`
Xcode Command Line Tools	Provides `swiftc`, used to compile the native HEIC helper	`xcrun --find swiftc`

If xcrun --find swiftc fails, install the Command Line Tools with:

xcode-select --install

You do not need the full Xcode IDE — the Command Line Tools package is enough, and is what most Mac developer machines already have.

2. Building the Java application

From the project root:

mvn package

This does two things:

Compiles all classes under src/main/java with the maven-compiler-plugin.
Uses the maven-assembly-plugin to produce a single runnable, self-contained jar at target/dynamic-wallpaper-creator.jar (there are no third-party runtime dependencies to bundle — the app only uses the JDK's own Swing, AWT and I/O APIs — so this step mainly just sets the executable Main-Class manifest entry).

Run it with:

java -jar target/dynamic-wallpaper-creator.jar

Other useful Maven targets:

mvn compile     # compile only, no jar
mvn clean       # remove target/
mvn -q package  # quieter output

There are no automated tests in this project (see "Testing strategy" below for why, and how the app was actually validated).

3. Building the native helper (`heic-builder`)

Java cannot write HEIC files with multiple embedded images and custom XMP metadata on its own — those capabilities only exist in Apple's ImageIO and CoreGraphics frameworks, which are Objective-C/Swift APIs. To bridge that gap, the app ships the source for a small command-line tool, src/main/resources/native/HeicBuilder.swift, as a resource inside the jar.

You never compile this file yourself — the Java app does it automatically:

On startup (specifically, the first time you click Generate Wallpaper), com.dynamicwallpaper.core.NativeHelper extracts the bundled .swift source to ~/Library/Application Support/DynamicWallpaperCreator/HeicBuilder.swift.
It computes a SHA-256 hash of that source and compares it against the hash recorded the last time it compiled. If they differ (first run, or you built a newer version of the app with an updated helper), it invokes:
```
xcrun swiftc -O HeicBuilder.swift -o heic-builder
```
in that same directory, and records the new hash.
Every subsequent run just reuses the cached heic-builder binary — no recompilation, effectively instant startup.

If you want to trigger this manually (e.g. to debug it in isolation), you can compile and run it directly:

xcrun swiftc -O src/main/resources/native/HeicBuilder.swift -o /tmp/heic-builder
/tmp/heic-builder build path/to/job.json
/tmp/heic-builder inspect path/to/some.heic   # dumps embedded apple_desktop metadata, for debugging

See FILE_FORMAT.md for the job.json schema this tool expects.

4. Testing strategy

There is no JUnit suite bundled with this project. The reasons and what was actually done instead:

The two things worth testing — "does the GUI look/behave right" and "is the generated .heic file byte-for-byte structured the way macOS expects" — are not meaningfully covered by unit tests. The second one can be verified programmatically, and was: during development, the native helper's inspect command was used to decode the metadata out of a freshly generated file and diff it against the metadata pulled from a real Apple-shipped wallpaper (/System/Library/Desktop Pictures/Sonoma.heic). They match exactly (see FILE_FORMAT.md).
If you're extending this project and want a smoke test, the fastest way is the inspect command above: generate a file, inspect it, and confirm the apple_desktop:apr or apple_desktop:solar tag decodes to the plist structure you expect.
For a full manual test, generate a wallpaper, click Set as Desktop Picture, then toggle System Settings → Appearance between Light and Dark (for appearance-mode wallpapers) and confirm the desktop image changes.

5. Packaging for distribution (optional)

The runnable jar from mvn package is enough to hand to another Mac user — they just need Java 17+ and Xcode Command Line Tools installed, and can run java -jar dynamic-wallpaper-creator.jar. If you want a double-clickable .app bundle instead, wrap the jar with jpackage (bundled with the JDK):

jpackage \
  --input target \
  --name "Dynamic Wallpaper Creator" \
  --main-jar dynamic-wallpaper-creator.jar \
  --main-class com.dynamicwallpaper.Main \
  --type app-image

This is optional and not required for local development or use.

5.1 KiB Raw Permalink Blame History