# 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:

```bash
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:

```bash
mvn package
```

This does two things:

1. Compiles all classes under `src/main/java` with the `maven-compiler-plugin`.
2. 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:

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

Other useful Maven targets:

```bash
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`](../src/main/resources/native/HeicBuilder.swift),
as a resource inside the jar.

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

1. 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`.
2. 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:
   ```bash
   xcrun swiftc -O HeicBuilder.swift -o heic-builder
   ```
   in that same directory, and records the new hash.
3. 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:

```bash
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](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](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):

```bash
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.