macOS ml support #2158

TheTripleV · 2025-10-24T08:12:54Z

Instead of managing jni in a separate repo, this takes the approach of monorepoing even platform specific native libs.

photon-apple builds swift code specific to macos.

On macos, it actually builds the swift code.
On non-macos, it uses stubs with matching types and declarations.

This way, photon-core can use apis in photon-apple without reflection and the classes will resolve.

This approach can be used to monorepo more native things in the future.

note: Swift does support linux arm64 so we could use it for linux too. Swift has c++ interop so it could be used as a nicer bridging layer where Java -> Swift is generated by swift-java over FFM/JNI and Swift->C++ is handled by the swift runtime so y'all don't have to touch jni.

- Use Java 24 for photonvision app builds (build-gradle, playwright-tests, build-package, run-smoketest-native) - Keep Java 17 for photonlib builds (build-examples, build-photonlib-host) for FRC compatibility - Exclude SwiftJava samples from CI to prevent jextract failures - Add PhotonAppleLibraryLoader stub for non-macOS platforms to fix Linux compilation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

- Remove SwiftKit publish from photonlib jobs (build-examples, build-photonlib-host) - Add photonAppleForceStubs property to use stubs even on macOS for photonlib builds - Disable photon-apple test compilation on non-macOS (tests require Java 24 APIs) - Only photon-server builds on macOS use real photon-apple implementation This ensures photonlib (which targets Java 17 for FRC) doesn't depend on Java 24 or Swift libraries, while photon-server can still use native Apple object detection on macOS. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

JaCoCo 0.8.10 doesn't support Java 24 class files (major version 68). Upgrading to 0.8.13 which supports Java 24. Fixes jacocoTestReport task failure: "Unsupported class file major version 68" 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

- SwiftKit requires Java 25 minimum - Java 25 is the LTS release - Update photon-apple to use Java 25 for real implementation and stubs - photon-apple uses Java 17 when photonAppleForceStubs is set (for photonlib) - Update CI workflows to install Java 25 instead of Java 24 - Update CLAUDE.md documentation Fixes build failures: - macOS: "swiftkit-ffm:1.0-SNAPSHOT is only compatible with JVM runtime version 25 or newer" - Windows/Linux: Java 25 installed but photon-apple was looking for Java 17 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

- Java 24 works locally, no need for Java 25 - Java 25 requires Gradle 9 upgrade (not ready for that) - SwiftKit submodule hardcodes Java 25 in build.gradle - Add Gradle init script in CI to force SwiftKit to use Java 24 toolchain - FFM API is in preview in Java 24 (already using --enable-preview) - Revert photon-apple from Java 25 back to Java 24 - Revert CI workflows from Java 25 back to Java 24 - Update CLAUDE.md documentation This avoids the Gradle major version upgrade while keeping builds working. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

SwiftKit requires Java 25 and is only needed on macOS builds. Changes: - build-package job: Install Java 25 on macOS, Java 24 on Linux/Windows - photon-apple: Use Java 25 on macOS (real impl), Java 24 on Linux/Windows (stubs) - PhotonLib: Still uses Java 17 with photonAppleForceStubs flag - Remove Gradle init script workaround (no longer needed) This fixes the macOS build failure where SwiftKit libraries compiled with Java 25 couldn't be used by Java 24 builds. Gradle 8 supports both Java 24 and Java 25, no Gradle upgrade needed. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

The issue: Gradle 8.14.3 can't RUN on Java 25 (only supports up to Java 24). However, Gradle 8 CAN use Java 25 as a toolchain for compilation. Error was: "Unsupported class file major version 69" (Java 25) Solution: - Install Java 24 FIRST (sets JAVA_HOME to Java 24) - Install Java 25 SECOND on macOS (available as toolchain) - Gradle runs on Java 24 (via JAVA_HOME) - photon-apple compiles with Java 25 toolchain (via gradle toolchain API) This matches local development where Gradle runs on Java 24 but can still compile code targeting Java 25. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

The actions/setup-java action always sets the newly installed version as the default (JAVA_HOME). By installing Java 25 first, then Java 24 second, we ensure JAVA_HOME points to Java 24 (which Gradle 8 can run on) while keeping Java 25 available as a toolchain for SwiftKit compilation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Set sourceCompatibility/targetCompatibility to Java 24 for photon-apple to make it compatible with Java 24 consumers during Gradle dependency resolution. Compilation still uses Java 25 toolchain for SwiftKit. This fixes the error: "Dependency resolution is looking for a library compatible with JVM runtime version 24, but 'project :photon-apple' is only compatible with JVM runtime version 25 or newer." 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Change from excluding specific sample to excluding all :Samples:build. The swift-java submodule uses Gradle 9 which has stricter parsing, causing build failures in sample projects we don't need to build. Fixes SwiftJavaExtractFFMSampleApp JSON parsing error in CI. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Document the sourceCompatibility/targetCompatibility approach for photon-apple to resolve the dependency resolution vs runtime requirements conflict. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Update swift-java submodule to commit fe857f6156c319c9c424e457e9529973d0de308d which includes Swift libraries loading from JAR resources. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

mcm001 · 2025-12-31T02:02:47Z

photon-apple/build.gradle

+def forceStubs = project.hasProperty('photonAppleForceStubs')
+def useRealImplementation = isMacOS && !forceStubs
+
+// Configure Java version based on build mode


Can we document somewhere the reason driving all this trickery around java versions? I know some of this is in Discord, but would like this captured

documented in docs/source/docs/contributing/building-photon.md

mcm001 · 2025-12-31T02:06:24Z

photon-core/src/main/java/org/photonvision/vision/objects/AppleObjectDetector.java

+    /** Cleaner instance to release the detector when it goes out of scope */
+    private final Cleaner cleaner = Cleaner.create();


Other classes use Releaseable because we don't have control over when this cleanup happens. Prefer to manually destroy objects rather than relying on GC to do this

Most of it is cleaned up manually after each detection. The detector object itself is long lived and GC'd. There were thread safety issues otherwise.

photon-core/build.gradle

mcm001 · 2025-12-31T02:08:08Z

photon-targeting/src/main/java/org/photonvision/common/hardware/Platform.java

    // Completely unsupported
+    MACOS("Mac OS", Platform::getUnknownModel, false, OSType.MACOS, true),


if somewhat supported, correct this comment

mcm001 · 2025-12-31T02:10:03Z

CLAUDE.md

+On macOS, you must manually publish the SwiftKit libraries to your local Maven repository before building:
+
+```bash
+cd photon-apple/swift-java
+./gradlew publishToMavenLocal
+cd ../..
+```


This feels goofy. the whole point of submodules and gradle is that they can be resolved and built as part of the overall build right?

So swift-java isn't available on Maven :(. They haven't setup publishing. And they only support building with Gradle 9 so it has to be done with its own gradle daemon.

can we not patch their build for that?

How much extra work is this for both Mac and non Mac users trying to build photon? Will they need to go read docs and remember to publish this magic library to maven local?

I feel like a better solution is to include the library as part of our build system, and have photon-apple depend on it.

Only needs to be published on mac.

And even on mac, if you use the flag -PphotonAppleForceStubs on any of the Gradle commands, it will build on Mac with all of swift turned off just like on windows. Everything should work except any object detection vision threads will crash.

platform_specific_native_wrappers.md

CLAUDE.md

platform_specific_native_wrappers.md

crossplatform.md

The macOS CI build was taking 40 minutes with 30 minutes spent building swift-java. This adds caching for the photon-apple/swift-java/.build directory to significantly speed up subsequent builds. The cache key is based on Package.swift, gradle.properties, and settings.gradle to ensure the cache is invalidated when dependencies change.

- Update macOS build matrix to use aarch64/macarm64 for primary macOS job - Change cache keys from runner.os to matrix.artifact-name for proper architecture separation - Remove debug output now that Swift build directory locations are confirmed 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

github-actions bot added the backend Things relating to photon-core and photon-server label Oct 24, 2025

TheTripleV added 2 commits December 28, 2025 22:23

detections work

0210740

zero copy

4af212d

TheTripleV force-pushed the mac branch from 8968c12 to 4af212d Compare December 29, 2025 06:05

cleanup stale dylibs before build

2c45546

TheTripleV force-pushed the mac branch from a30fc9d to 2c45546 Compare December 29, 2025 06:41

TheTripleV and others added 18 commits December 29, 2025 12:27

fix building on non-mac?

d3bbc35

format

f28c436

include photon-apple on all platforms

15d73ec

use macos 26 and java 24 on mac

5a50d03

split java version - 17 for photonlib, 24 for photonvision

8eb5d96

spotless

bb41408

the jar works

6822efc

TheTripleV mentioned this pull request Dec 30, 2025

Load Swift Libraries manually instead of System.loadLibrary swiftlang/swift-java#510

Closed

TheTripleV and others added 2 commits December 30, 2025 18:06

jar works locally

ac6d387

TheTripleV marked this pull request as ready for review December 31, 2025 01:46

TheTripleV requested a review from a team as a code owner December 31, 2025 01:46

mcm001 reviewed Dec 31, 2025

View reviewed changes

photon-core/build.gradle Outdated Show resolved Hide resolved

mcm001 reviewed Dec 31, 2025

View reviewed changes

spacey-sooty requested changes Dec 31, 2025

View reviewed changes

platform_specific_native_wrappers.md Outdated Show resolved Hide resolved

CLAUDE.md Outdated Show resolved Hide resolved

platform_specific_native_wrappers.md Outdated Show resolved Hide resolved

crossplatform.md Outdated Show resolved Hide resolved

some review comments

adf7076

github-actions bot added the documentation Anything relating to https://docs.photonvision.org label Dec 31, 2025

TheTripleV added 8 commits December 31, 2025 11:33

build fixes and docs

d1817eb

use java 17 for all non-macos

b701fe1

dont hardcode java 24

21134f4

stub memorysegment

6c49c07

use swift 6.2

e70d036

use arm64 java

a58dfab

update submodule

4299732

use java 25 for smoketest on macos

4ec3f9c

TheTripleV changed the title ~~macOS ml support [draft]~~ macOS ml support Dec 31, 2025

claude and others added 10 commits January 1, 2026 00:59

Trigger second CI run to test Swift build cache

f4c6616

Add debug output to inspect Swift build directory locations

c3d32bf

cache path

44adc6e

changes

61a539a

build examples on old macos

86e162c

bump

0174b21

yaml anchors

dab64ef

bump

cc59c89

samfreund force-pushed the mac branch from 72e89bb to cc59c89 Compare January 1, 2026 20:24

don't spam from swift as much

111678b

samfreund mentioned this pull request Jan 4, 2026

Bump actions for node 24 #2274

Merged

7 tasks

Merge remote-tracking branch 'origin/main' into mac

25480bd

		/** Cleaner instance to release the detector when it goes out of scope */
		private final Cleaner cleaner = Cleaner.create();

		// Completely unsupported
		MACOS("Mac OS", Platform::getUnknownModel, false, OSType.MACOS, true),

macOS ml support #2158

Are you sure you want to change the base?

macOS ml support #2158

Uh oh!

Conversation

TheTripleV commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

TheTripleV commented Oct 24, 2025 •

edited

Loading