WIP: Meson/Maven build for MMCoreJ

.github/workflows/ci-mmdevice-mmcore.yml

@@ -1,23 +1,29 @@
-name: MMDevice/MMCore experimental Meson build & tests
+name: MMDevice/MMCore/MMCoreJ Meson build & tests
 
 on:
   pull_request:
     paths:
       - MMDevice/**
       - MMCore/**
+      - MMCoreJ_wrap/**
       - .github/workflows/ci-mmdevice-mmcore.yml
   push:
     branches:
       - main
     paths:
       - MMDevice/**
       - MMCore/**
+      - MMCoreJ_wrap/**
       - .github/workflows/ci-mmdevice-mmcore.yml
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  CJDK_HIDE_PROGRESS_BARS: '1'
+  MAVEN_ARGS: '--batch-mode --no-transfer-progress'
+
 jobs:
   test:
     strategy:
@@ -76,3 +82,111 @@ jobs:
           cd MMCore
           meson setup builddir --buildtype debug -Dcpp_std=${{ matrix.cppstd }}
           meson test -C builddir --print-errorlogs
+
+  mmcorej-natives:
+    name: mmcorej-${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            name: linux-x86_64
+          - os: windows-2025
+            name: windows-x86_64
+            cxx: cl
+          - os: macos-15
+            name: macos-arm64
+            deployment_target: "11.0"
+          - os: macos-15
+            name: macos-x86_64
+            meson_cross_args: --cross-file=scripts/meson-cross-macos-x86_64.txt
+            jdk_arch: x86_64
+            deployment_target: "10.15"
+    env:
+      CXX: ${{ matrix.cxx }}
+      CJDK_ARCH: ${{ matrix.jdk_arch }}
+      MACOSX_DEPLOYMENT_TARGET: ${{ matrix.deployment_target }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: 3.14
+      - run: |
+          uv tool install cjdk
+          uv tool install meson
+          uv tool install ninja
+          uv tool install 'swig<4'
+      - name: Build in manylinux container
+        if: startsWith(matrix.os, 'ubuntu-')
+        run: |
+          docker run --rm -v "${{ github.workspace }}"/MMCoreJ_wrap:/work \
+            -w /work \
+            quay.io/pypa/manylinux_2_28_x86_64 \
+            bash scripts/build_jni_linux.sh
+      - name: Build (non-Linux)
+        if: "!startsWith(matrix.os, 'ubuntu-')"
+        shell: bash
+        run: |
+          cp -R MMDevice MMCoreJ_wrap/subprojects/mmdevice
+          cp -R MMCore MMCoreJ_wrap/subprojects/mmcore
+          cd MMCoreJ_wrap
+          export JAVA_HOME=$(cjdk -j zulu:8 java-home)
+          export PATH="$JAVA_HOME/bin:$PATH"
+          meson setup builddir --vsenv --buildtype=release \
+            ${{ matrix.meson_cross_args }} \
+            -Dmmdevice:tests=disabled -Dmmcore:tests=disabled
+          meson compile -C builddir
+      - name: Check SWIG-generated sources are correct in meson.build
+        run: |
+          cd MMCoreJ_wrap
+          uv run --no-project scripts/verify_swig_gensrc.py builddir
+      - name: Package & test (non-Windows)
+        if: "!startsWith(matrix.os, 'windows-')"
+        run: |
+          cd MMCoreJ_wrap
+          cjdk -j zulu:8 exec -- mvn verify
+      - name: Package & test (Windows)
+        if: startsWith(matrix.os, 'windows-')
+        run: |
+          cd MMCoreJ_wrap
+          cjdk -j zulu:8 exec -- mvn.cmd verify
+      - uses: actions/upload-artifact@v6
+        with:
+          name: mmcorej-natives-${{ matrix.name }}
+          path: MMCoreJ_wrap/target/MMCoreJ-*-natives-*.jar
+
+  mmcorej-java:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: 3.14
+      - run: |
+          uv tool install cjdk
+          uv tool install meson
+          uv tool install ninja
+          uv tool install 'swig<4'
+      - run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen
+      - run: |
+          cp -R MMDevice MMCoreJ_wrap/subprojects/mmdevice
+          cp -R MMCore MMCoreJ_wrap/subprojects/mmcore
+          cd MMCoreJ_wrap
+          export JAVA_HOME=$(cjdk -j zulu:8 java-home)
+          export PATH="$JAVA_HOME/bin:$PATH"
+          meson setup builddir -Djavadoc_from_doxygen=true \
+            -Dmmdevice:tests=disabled -Dmmcore:tests=disabled
+          meson compile -C builddir
+          cjdk -j zulu:8 exec -- mvn package \
+            -Dskip.natives=true -DskipTests=true
+      - name: Verify full sources JAR
+        run: |
+          cd MMCoreJ_wrap
+          ./scripts/verify-full-sources-jar.sh target/MMCoreJ-*-full-sources.jar
+      - uses: actions/upload-artifact@v6
+        with:
+          name: mmcorej-java
+          path: MMCoreJ_wrap/target/MMCoreJ-*.jar

MMCore/docs/Doxyfile.in

@@ -16,6 +16,9 @@ EXCLUDE_SYMBOLS        = internal std
 EXTRACT_ALL            = YES
 RECURSIVE              = YES
 
+# Changing this changes the HTML file names; stick to what we had
+CASE_SENSE_NAMES       = NO
+
 CLASS_GRAPH            = TEXT
 COLLABORATION_GRAPH    = NO
 GROUP_GRAPHS           = NO

MMCore/docs/meson.build

@@ -22,7 +22,7 @@ doxyfile = configure_file(
 
 doc_install_dir = get_option('datadir') / 'doc' / meson.project_name()
 
-custom_target(
+mmcore_docs_target = custom_target(
     'docs',
     command: [doxygen, '-q', doxyfile],
     output: ['apidoc'],

MMCoreJ_wrap/.gitignore

@@ -0,0 +1,3 @@
+.wraplock
+/target/
+.flattened-pom.xml

MMCoreJ_wrap/MMCoreJ.i

@@ -130,7 +130,7 @@
       }
 
       if (useStdErr) {
-         System.err.println("Load " + NATIVE_LIBRARY_NAME + ": " + message);
+         System.err.println("MMCoreJ native library loading: " + message);
       }
    }
 
@@ -197,10 +197,6 @@
       }
 
       if (loaded) {
-         // TODO If the library is already loaded, we still want to make sure
-         // that it was loaded from the right copy. The Core now has this
-         // information, so we should check it.
-         logLibraryLoading("Already loaded");
          return true;
       }
       return false;
@@ -253,6 +249,20 @@
    // Load the MMCoreJ_wrap native library.
    static {
       logLibraryLoading("Start loading...");
+
+      // New-style loading (extract from JAR, fall back to java.library.path,
+      // both with 'mmcorej').
+      if (!checkIfAlreadyLoaded()) {
+         try {
+            NativeLibraryLoader.load("mmcorej");
+            logLibraryLoading("Loaded 'mmcorej' library");
+         }
+         catch (UnsatisfiedLinkError e) {
+            logLibraryLoading("Falling back to 'MMCoreJ_wrap' loading mode...");
+         }
+      }
+
+      // Legacy loading ('MMCoreJ_wrap')
       if (!checkIfAlreadyLoaded()) {
          // The most reliable method for locating (the correct copy of)
          // MMCoreJ_wrap is to look in the single path given as a Java system

MMCoreJ_wrap/README.md

@@ -0,0 +1,90 @@
+# MMCoreJ
+
+MMCoreJ provides Java bindings for MMCore, Micro-Manager's hardware abstraction
+layer, written in C++.
+
+## Building MMCoreJ
+
+The currently "supported" way to build MMCoreJ is to run the full Micro-Manager
+build (using Ant on Windows and Autoconf/Automake elsewhere).
+
+However, we are working to make MMCoreJ an independent project with its own
+build system using Meson for the C++ parts and Maven for the Java parts.
+
+You can test the new build system as follows. Note that SWIG version 2.x or 3.x
+(not 4.x) must be available on the path.
+
+```sh
+# Copy over matching sources for MMDevice and MMCore (otherwise they will be
+# fetched by Meson but may not be the correct versions).
+rm -rf subprojects/mmdevice subprojects/mmcore
+cp -R ../MMDeivce subprojects/mmdevice
+cp -R ../MMCore subprojects/mmcore
+
+meson setup --vsenv builddir  # --vsenv recommended on Windows
+meson compile -C builddir
+mvn package
+```
+
+This should place the built JARs in target/. There is a main JAR containing the
+Java classes and a separate per-OS/architecture "natives" JAR containing the
+native library.
+
+## Native Library Loading
+
+MMCoreJ requires a native library containing the C++ MMCore. The library is
+loaded automatically when the `CMMCore` class is first accessed.
+
+There is a "modern" and "legacy" search order for the native library. The
+modern way can be used when MMCoreJ is built by Meson + Maven; when it fails,
+loading falls back to the legacy search order. (As of this writing, MMStudio
+still uses the legacy method.)
+
+### Modern Search Order (for Meson build)
+
+**Library file names:**
+
+- **Linux**: `libmmcorej.so`
+- **macOS**: `libmmcorej.dylib`
+- **Windows**: `mmcorej.dll`
+
+The native library `mmcorej` is located in the following order:
+
+1. **JAR resource extraction**: The library is extracted from JAR resources at
+   `/natives/<os>/<arch>/` where `<os>` is `linux`, `macos`, or `windows` and
+   `<arch>` is `arm64` or `x86_64`. These are provided as "natives" classifier
+   JARs (e.g., `MMCoreJ-<version>-natives-macos-arm64.jar`).
+
+2. **System library path**: If not found as a JAR resource, `java.library.path`
+   is searched.
+
+If the above fails, the legacy loading mechanism is used (see below).
+
+### Legacy Search Order
+
+**Library file names:**
+
+- **Linux**: `libMMCoreJ_wrap.so`
+- **macOS**: `libMMCoreJ_wrap.jnilib` or `.dylib`
+- **Windows**: `MMCoreJ_wrap.dll`
+
+The legacy loading mechanism searches for `MMCoreJ_wrap` as follows:
+
+1. **System property path**: If `mmcorej.library.path` is set, the library is
+   loaded exclusively from that directory (no fallback to other locations).
+
+2. **Relative to the JAR**: These paths are searched in order:
+   - The directory containing the MMCoreJ JAR
+   - The parent directory of the JAR
+   - _[deprecated]_ `../mm/<platform>/` relative to the JAR
+   - The grandparent directory of the JAR
+   - _[deprecated]_ `../../mm/<platform>/` relative to the JAR
+
+   Where `<platform>` is one of: `macosx`, `win32`, `win64`, `linux32`,
+   `linux64`. The `mm/<platform>/` locations are obsolete and were never used
+   by Micro-Manager.
+
+3. **Compile-time path**: _[deprecated]_ A path optionally set at build time
+   (Autoconf/Automake build only).
+
+4. **System default**: `java.library.path` is used as a last resort.