134 lines
5.1 KiB
Markdown
134 lines
5.1 KiB
Markdown
# 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.
|