Initial Application

docs/BUILD.md

@@ -0,0 +1,133 @@
+# 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.