Skip to content

fix(jni): select the native library by OS and architecture - #460

Merged
manusa merged 1 commit into
mainfrom
fix/native-library-platform-selection
Nov 15, 2026
Merged

manusa merged 1 commit into
mainfrom
fix/native-library-platform-selection

Conversation

@manusa

@manusa manusa commented Nov 15, 2026

Copy link
Copy Markdown
Owner

Fixes #459

Summary

NativeLibrary.getInstance() used the first ServiceLoader provider, so with more than one platform JAR on the classpath the classpath order decided which native binary was loaded. Extraction was also tied to java.io.tmpdir, which fails on noexec mounts.

  • Selection by OS and architecture. NativeLibrary gets getOs()/getArch() default methods (returning null), and the five platform providers declare their platform. Selection now works in this order:

    1. the first provider whose declared OS/architecture match the running JVM;
    2. otherwise, the first provider that declares nothing (third-party providers, or platform JARs older than this change);
    3. otherwise, an IllegalStateException naming os.name/os.arch and the providers found.

    OS/arch detection moves from RemoteJarLoader into a shared Platform helper.

  • System properties. Both follow the existing com.marcnuri.jkube-helm.* convention:

    • com.marcnuri.jkube-helm.nativeLibrary: fully qualified class name of a registered NativeLibrary to use regardless of platform. A blank value is ignored.
    • com.marcnuri.jkube-helm.tempDir: base directory for extracting the native library, created if missing (defaults to java.io.tmpdir).
  • Build. New linux-aarch64 profile, since Linux JVMs report os.arch=aarch64. It is restricted to os.name=linux so Apple Silicon Macs (also family unix) don't pick it up.

  • Docs.

    • README: version bumped to 0.0.22, plus how the platform artifact is chosen (build-host profiles), cross-build guidance, the selection order and the new properties (marked "since 0.0.23").
    • AGENTS.md: the native-loading paragraph is updated.

Release notes

NativeLibrary.serviceProviderLibrary(ClassLoader) can now throw an IllegalStateException when native library implementations are registered but none can be used on the current platform, or when the class forced with com.marcnuri.jkube-helm.nativeLibrary isn't registered; before, it always returned the first registered implementation.

Testing

  • lib/api on Java 8: 34 new tests, no mocking library (NativeLibrarySelectorTest, PlatformTest, NativeLibraryServiceProviderTest). They cover:
    • selection with fake providers;
    • a URLClassLoader with a wrong-platform provider registered first, and the mixed-version case;
    • the no-match error;
    • the override property, including a blank value;
    • the extraction directory: created if missing, a symbolic link to a directory, and a path that is a file.
  • helm-java on Java 8, with the native library built for linux/amd64: NativeLibraryTest (including the remote-JAR tests), HelmVersionTest, HelmCreateTest, HelmTemplateTest and HelmLintTest pass.
  • Reproduction from Native library loading ignores OS/arch and cannot extract outside java.io.tmpdir #459 on Linux x86_64, with a linux-arm64 JAR before linux-amd64 on the classpath: linux-amd64 is now selected and Helm.version() succeeds. The same holds with a 0.0.22 linux-arm64 JAR first.
  • Profile: linux-aarch64 is the active profile when os.arch=aarch64.
  • Left to CI: the KinD-based tests, and the macOS and Windows jobs.

NativeLibrary.getInstance() returned the first ServiceLoader provider,
so with several platform JARs on the classpath the classpath order
decided which binary was loaded, and the wrong one failed with
UnsatisfiedLinkError. The library could also only be extracted under
java.io.tmpdir, which fails on hosts where /tmp is mounted noexec.

- Platform providers declare their OS and architecture. The first
  matching provider is preferred, then the first one declaring
  nothing (custom or older providers). A clear IllegalStateException
  lists the providers when none can be used.
- com.marcnuri.jkube-helm.nativeLibrary forces a registered provider
  and com.marcnuri.jkube-helm.tempDir sets the extraction directory.
- Add a linux-aarch64 profile, since Linux JVMs report aarch64.
- Document how the platform artifact is chosen, cross-building and
  the new properties in the README, and bump its version to 0.0.22.

Fixes #459

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Marc Nuri <marc@marcnuri.com>

@manusa manusa left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review of #460: native library selection by OS/arch (fixes #459)

The change was reviewed in two rounds before the PR was opened. All round-1 findings were addressed in the branch. Line numbers refer to the pre-commit worktree and may differ slightly from the final commit.

Verdict (round 2): approve. No Critical or Important findings remain, and all 7 items of the issue's Proposed fix are delivered.

Round 1: NEEDS_CHANGES (1 Important, 8 Minor)

Important

  1. An undeclared provider beat a matching one that came later on the classpath. The first version returned the first compatible provider, and a provider that declares no OS/arch (every platform jar up to 0.0.22) counted as compatible everywhere.
    • Reproduced on Java 8, Linux x86_64: new lib-api, then linux-arm64-0.0.22.jar, then the new linux-amd64 jar. That selected helm-linux-arm64.so, the exact #459 failure.
    • Realistic trigger: a version-pinned linux-${arch} dependency plus an upgraded helm-java.
    • Resolved: two-pass selection. A declared match is preferred, and the first undeclared provider is only the fallback. Covered by NativeLibrarySelectorTest and by the MixedVersions cases in NativeLibraryServiceProviderTest.

Minor. All resolved unless noted.

  1. Versions. The README presented next-release behaviour under 0.0.22. It is now marked "(since 0.0.23)".
  2. No remote-jar fallback when local providers exist but none match. Kept by design, and now documented in the README.
  3. Blank override. A blank com.marcnuri.jkube-helm.nativeLibrary was treated as a class name. It is now trimmed and treated as unset, with tests.
  4. Extraction directory.
    • The error didn't name the path or property. It now names both, and InvalidPathException is also caught.
    • The README now says the directory is created if missing and holds a helm-java* subdirectory.
  5. Override docs. The README now says the forced class must be registered in META-INF/services.
  6. Test isolation. Tests cleared the system properties instead of restoring them. Values are now saved and restored, and the temp directory is cleaned up.
  7. Platform coverage. The new PlatformTest covers Windows 10, Mac OS X, Linux, SunOS and null os.name, and amd64, x86_64, aarch64, arm64, sparcv9 and null os.arch.
  8. Release notes. serviceProviderLibrary can now throw. This is covered in the PR description.

Round 2: APPROVE

  • The Files.isDirectory guard in NativeLibrary.createTempDirectory() is justified.
    • On JDK 1.8.0_512, Files.createDirectories(link) throws FileAlreadyExistsException for an existing symlink to a directory, for example /tmp on macOS. On JDK 21 it succeeds.
    • With the guard removed, usesSymbolicLinkToDirectorySetWithSystemProperty fails on Java 8. The Java 11 macOS and Windows jobs wouldn't catch that, so the comment now says why the guard stays.
  • Three optional nits, all applied before the commit:
    • README wording for partially declared providers ("declared OS and/or architecture match");
    • the symlink test now skips only on UnsupportedOperationException, or on a FileSystemException on Windows;
    • the guard's comment.
  • Checked and fine:
    • partially declared providers never match an unknown OS/arch;
    • the override never silently falls back;
    • undeclared providers are still listed in the no-match error;
    • Java 8 compilation and Javadoc;
    • the linux-aarch64 profile is the only active one with os.arch=aarch64, and <name>linux</name> keeps Apple Silicon out;
    • README and AGENTS.md match the code;
    • license headers are present.
  • For awareness, not a finding. An old and a new copy of the same platform artifact share one class name, so the old one can shadow the new one. Maven never resolves two versions of one artifact, so only a hand-built or fat-jar classpath can hit this, and no selector change could fix it.

Verified by running (Java 8, Linux x86_64)

  • lib/api: 34 tests, 0 failures, 0 skipped.
  • Selected helm-java tests: NativeLibraryTest, HelmVersionTest (loads the .so through the new selection), HelmCreateTest, HelmTemplateTest, HelmLintTest.
  • The #459 reproduction and the mixed-version case now select linux-amd64 and Helm.version() succeeds.
  • help:active-profiles with os.arch=aarch64.

Not run locally: the KinD tests and the macOS/Windows jobs, which are left to CI.

@manusa
manusa merged commit 315f9b0 into main Nov 15, 2026
3 checks passed
@manusa
manusa deleted the fix/native-library-platform-selection branch November 15, 2026 18:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Native library loading ignores OS/arch and cannot extract outside java.io.tmpdir

1 participant