macOS ml support

.github/workflows/build.yml

@@ -43,6 +43,7 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          submodules: recursive
       - name: Fetch tags
         run: git fetch --tags --force
       - name: Install Java 17
@@ -240,21 +241,22 @@ jobs:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          submodules: recursive
       - name: Install Java 17
         uses: actions/setup-java@v5
         with:
           java-version: 17
           distribution: temurin
       - run: git fetch --tags --force
-      - run: ./gradlew photon-targeting:build photon-lib:build
+      - run: ./gradlew photon-targeting:build photon-lib:build -PphotonAppleForceStubs
         name: Build with Gradle
-      - run: ./gradlew photon-lib:publish photon-targeting:publish
+      - run: ./gradlew photon-lib:publish photon-targeting:publish -PphotonAppleForceStubs
         name: Publish
         env:
           ARTIFACTORY_API_KEY: ${{ secrets.ARTIFACTORY_API_KEY }}
         if: github.event_name == 'push' && github.repository_owner == 'photonvision'
       # Copy artifacts to build/outputs/maven
-      - run: ./gradlew photon-lib:publish photon-targeting:publish -PcopyOfflineArtifacts
+      - run: ./gradlew photon-lib:publish photon-targeting:publish -PcopyOfflineArtifacts -PphotonAppleForceStubs
       - uses: actions/upload-artifact@v6
         with:
           name: maven-${{ matrix.artifact-name }}
@@ -417,6 +419,90 @@ jobs:
 
     steps: *build-package-steps
 
+  build-package-macos:
+    needs: [build-gradle, build-offline-docs]
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-26
+            artifact-name: macOS
+            architecture: aarch64
+            arch-override: macarm64
+
+    runs-on: ${{ matrix.os }}
+    name: "Build fat JAR - ${{ matrix.artifact-name }}"
+
+    steps: &build-package-steps-macos
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          submodules: recursive
+      - name: Install Java 25 (macOS toolchain for SwiftKit)
+        uses: actions/setup-java@v5
+        if: runner.os == 'macOS'
+        with:
+          java-version: 25
+          distribution: temurin
+          architecture: ${{ matrix.architecture }}
+      - name: Install Java 24 (for Gradle on macOS)
+        uses: actions/setup-java@v5
+        if: runner.os == 'macOS'
+        with:
+          java-version: 24
+          distribution: temurin
+          architecture: ${{ matrix.architecture }}
+      - name: Install Java 17 (for Gradle on non-macOS)
+        uses: actions/setup-java@v5
+        if: runner.os != 'macOS'
+        with:
+          java-version: 17
+          distribution: temurin
+          architecture: ${{ matrix.architecture }}
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: photon-client/pnpm-lock.yaml
+      - name: Cache Swift build artifacts (macOS only)
+        uses: actions/cache@v4
+        if: runner.os == 'macOS'
+        with:
+          path: photon-apple/.build
+          key: ${{ matrix.artifact-name }}-photon-apple-build-${{ hashFiles('photon-apple/swift-java/Package.swift', 'photon-apple/swift-java/gradle.properties', 'photon-apple/swift-java/settings.gradle') }}
+          restore-keys: |
+            ${{ matrix.artifact-name }}-photon-apple-build-
+      - name: Publish SwiftKit to Maven Local (macOS only)
+        if: runner.os == 'macOS'
+        run: |
+          cd photon-apple/swift-java
+          ./gradlew publishToMavenLocal -PskipSamples=true
+      - name: Install Arm64 Toolchain
+        run: ./gradlew installArm64Toolchain
+        if: ${{ (matrix.artifact-name) == 'LinuxArm64' }}
+      - uses: actions/download-artifact@v6
+        with:
+          name: built-docs
+          path: photon-server/src/main/resources/web/docs
+      - run: ./gradlew photon-targeting:jar photon-server:shadowJar -PArchOverride=${{ matrix.arch-override }}
+        if: ${{ (matrix.arch-override != 'none') }}
+      - run: ./gradlew photon-server:shadowJar
+        if: ${{ (matrix.arch-override == 'none') }}
+      - uses: actions/upload-artifact@v6
+        with:
+          name: jar-${{ matrix.artifact-name }}
+          path: photon-server/build/libs
+      - uses: actions/upload-artifact@v6
+        with:
+          name: photon-targeting_jar-${{ matrix.artifact-name }}
+          path: photon-targeting/build/libs
+
   run-smoketest-native:
     needs: [build-package-linux, build-package-macos, build-package-windows]
 
@@ -429,14 +515,21 @@ jobs:
             extraOpts: -Djdk.lang.Process.launchMechanism=vfork
           - os: windows-latest
             artifact-name: jar-Win64
-          - os: macos-latest
+          - os: macos-26
             artifact-name: jar-macOS
 
     runs-on: ${{ matrix.os }}
 
     steps:
-      - name: Install Java 17
+      - name: Install Java 25 (macOS)
+        uses: actions/setup-java@v5
+        if: runner.os == 'macOS'
+        with:
+          java-version: 25
+          distribution: temurin
+      - name: Install Java 17 (non-macOS)
         uses: actions/setup-java@v5
+        if: runner.os != 'macOS'
         with:
           java-version: 17
           distribution: temurin

.gitignore

@@ -156,3 +156,5 @@ photon-client/playwright-report/
 photon-client/blob-report/
 photon-client/playwright/.cache/
 photon-client/playwright/.auth/
+
+.build/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "photon-apple/swift-java"]
+	path = photon-apple/swift-java
+	url = https://github.com/swiftlang/swift-java.git

.wpiformat

@@ -6,4 +6,7 @@ modifiableFileExclude {
   photon-lib/py/photonlibpy/generated/
   photon-targeting/src/generated/
   photon-targeting/src/main/native/cpp/photon/constrained_solvepnp/generate/
+  .build/
+  photon-apple/.build/
+  photon-apple/swift-java/
 }

README.md

@@ -6,7 +6,7 @@ PhotonVision is the free, fast, and easy-to-use computer vision solution for the
 
 The latest release of platform-specific jars and images is found [here](https://github.com/PhotonVision/photonvision/releases).
 
-If you are interested in contributing code or documentation to the project, please [read our getting started page for contributors](https://docs.photonvision.org/en/latest/docs/contributing/index.html) and **[join the Discord](https://discord.gg/wYxTwym) to introduce yourself!** We hope to provide a welcoming community to anyone who is interested in helping.
+If you are interested in contributing code or documentation to the project, please [read our getting started page for contributors](https://docs.photonvision.org/en/latest/docs/contributing/index.html) and **[join the Discord](https://discord.gg/wYxTwym) to introduce yourself!** We hope to provide a welcoming community to anyone who is interested in helping out.
 
 ## Documentation
 

build.gradle

@@ -23,6 +23,23 @@ allprojects {
     }
     wpilibRepositories.addAllReleaseRepositories(it)
     wpilibRepositories.addAllDevelopmentRepositories(it)
+
+    // Allow Java 25 dependencies (SwiftKit) to be consumed by Java 24 projects
+    // This is needed because photon-apple requires SwiftKit which needs Java 25,
+    // but photon-server runs on Java 24
+    dependencies {
+        components {
+            all { ComponentMetadataDetails details ->
+                if (details.id.group == 'org.swift.swiftkit') {
+                    details.allVariants { VariantMetadata variant ->
+                        variant.attributes {
+                            attribute(TargetJvmVersion.TARGET_JVM_VERSION_ATTRIBUTE, 24)
+                        }
+                    }
+                }
+            }
+        }
+    }
 }
 
 ext.localMavenURL = file("$project.buildDir/outputs/maven")
@@ -62,7 +79,8 @@ spotless {
     java {
         target fileTree('.') {
             include '**/*.java'
-            exclude '**/build/**', '**/build-*/**', '**/src/generated/**'
+            exclude '**/build/**', '**/build-*/**', '**/src/generated/**',
+                    '**/.build/**', '**/photon-apple/swift-java/**'
         }
         toggleOffOn()
         googleJavaFormat()
@@ -75,7 +93,8 @@ spotless {
     groovyGradle {
         target fileTree('.') {
             include '**/*.gradle'
-            exclude '**/build/**', '**/build-*/**'
+            exclude '**/build/**', '**/build-*/**',
+                    '**/.build/**', '**/photon-apple/swift-java/**'
         }
         greclipse()
         indentWithSpaces(4)
@@ -85,7 +104,8 @@ spotless {
     format 'misc', {
         target fileTree('.') {
             include '**/*.md', '**/.gitignore'
-            exclude '**/build/**', '**/build-*/**', '**/node_modules/**'
+            exclude '**/build/**', '**/build-*/**', '**/node_modules/**',
+                    '**/.build/**', '**/photon-apple/swift-java/**'
         }
         trimTrailingWhitespace()
         indentWithSpaces(2)

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

@@ -8,7 +8,18 @@ This section contains the build instructions from the source code available at [
 
 **Java Development Kit:**
 
- This project requires Java Development Kit (JDK) 17 to be compiled. This is the same Java version that comes with WPILib for 2026+. **Windows Users must use the JDK that ships with WPILib.** For other platforms, you can follow the instructions to install JDK 17 for your platform [here](https://bell-sw.com/pages/downloads/#jdk-17-lts).
+ PhotonLib requires Java Development Kit (JDK) 17 to be compiled. This is the same Java version that comes with WPILib for 2026+. **Windows Users must use the JDK that ships with WPILib.** For other platforms, you can follow the instructions to install JDK 17 for your platform [here](https://bell-sw.com/pages/downloads/#jdk-17-lts).
+
+ The PhotonVision server application requires JDK 17 to be compiled on Windows and Linux.
+ On macOS, it requires JDK 24 and JDK 25 (both JDK 24 and JDK 25 must be installed with JAVA_HOME pointing at JDK 24).
+
+ **JDK Version Split**
+
+ WPILib uses JDK 17 for the 2026 season. Photonlib must be built with JDK 17 compatibility.
+
+ PhotonVision on macOS uses a library (swift-java) to wrap swift code in java for CoreML based object detection.
+ swift-java requires Java 25 to build. Photonvision and WPILib use Gradle 8. Gradle 8 does not support Java 25. Gradle 9 is required for Java 25. So we build swift-java using Gradle 9 and Java 25 then use Gradle 8 and Java 24 to build photonvision.
+
 
 **Node JS:**
 
@@ -57,6 +68,41 @@ pnpm run dev
 
 This allows you to make UI changes quickly without having to spend time rebuilding the jar. Hot reload is enabled, so changes that you make and save are reflected in the UI immediately. Running this command will give you the URL for accessing the UI, which is on a different port than normal. You must use the printed URL to use hot reload.
 
+### One time build the UI
+
+To build the UI once and have it be served directly by PhotonVision, issue the following command in the root directory:
+
+```{eval-rst}
+.. tab-set::
+
+   .. tab-item:: Linux
+      :sync: linux
+
+      ``./gradlew buildAndCopyUI``
+
+   .. tab-item:: macOS
+      :sync: macos
+
+      ``./gradlew buildAndCopyUI``
+
+   .. tab-item:: Windows (cmd)
+      :sync: windows
+
+      ``gradlew buildAndCopyUI``
+```
+
+### macOS only - Compile swift-java
+
+On macOS, before building PhotonVision, it is required to build swift-java one time.
+
+To build swift-java, issue the following from the root directory:
+
+```bash
+git submodule update --init --recursive
+cd photon-apple/swift-java
+./gradlew publishToMavenLocal -x :Samples:build
+```
+
 ### Build and Run PhotonVision
 
 To compile and run the project, issue the following command in the root directory:
@@ -308,3 +354,8 @@ build action, which can be found [here](https://github.com/PhotonVision/photonvi
 In order to force the Object Detection interface to be visible, it's necessary to hardcode the platform that `Platform.java` returns. This can be done by changing the function that detects the RK3588S/QCS6490 platform to always return true, and changing the `getCurrentPlatform()` function to always return the RK3588S/QCS6490 architecture.
 Alternatively, it's possible to modify the frontend code by changing all instances of `useSettingsStore().general.supportedBackends.length > 0` to `true`, which will force the card to render.
 Make sure to revert these changes before submitting a Pull Request.
+
+#### Building platform specific native code in the monorepo
+
+Platform specific native code can be built in the monorepo by isolating the native code to a new subfolder with its own build.gradle.
+On the desired platform, CI will build the native code and the java wrappers for it. On other platforms, configure the project to use stubs. See photon-apple/build.gradle.