[EduardoRadieske]

Closes #1694

Summary

Allow multiple Linux native library variants compiled for glibc and musl to coexist on the classpath, selecting the matching variant at runtime based on the libc used by the current process.

Resource layout

For example, on Linux x86-64, resources can be packaged using the following layout:

linux-x86-64-glibc/
    libexample.so
linux-x86-64-musl/
    libexample.so
linux-x86-64/
    libexample.so

The libc-specific directories follow the naming convention <RESOURCE_PREFIX>-<libc>, where <libc> is glibc or musl.

The existing linux-x86-64/ resource path remains available as a legacy fallback, preserving compatibility with existing resource layouts.

Changes

• Detect the libc implementation used by the current Linux process through /proc/self/maps.
• Prefer the matching libc-specific resource when resolving non-absolute classpath resource names.
• Fall back to the legacy resource when the libc is unknown or the matching variant is unavailable.
• Preserve existing resource lookup behavior for absolute resource paths and non-Linux platforms.

Tests

• Add PlatformTest coverage for libc detection, ambiguous or missing indicators, read failures, deleted mappings, and false-positive paths.
• Add LibraryLoadTest coverage for variant selection, prevention of selecting the opposite libc variant, and fallback behavior.

[almson]

Can we also fix JNA itself to work with musl without extra hoops?

[EduardoRadieske]

Can we also fix JNA itself to work with musl without extra hoops?

Good point. JNA already bundles its own libjnidispatch native library inside jna.jar, but the bundled Linux native binaries are currently organized by OS and architecture, without distinguishing between glibc and musl.

This PR currently focuses on selecting libc-specific variants of native libraries used by client applications. Extending this to JNA's own dispatch library would also involve deciding how a musl-compatible variant should be built, packaged, and selected during JNA initialization.

Would you prefer to address this as part of this PR, or would it make more sense to track it in a separate issue?

[almson]

Would you prefer to address this as part of this PR, or would it make more sense to track it in a separate issue?

I think it should be a separate issue.

I know very little about the C ecosystem. I know that it's much more of a "build every time, don't run anywhere else" sort of setup. Hopefully libjnidispatch can be compiled in a general way that will simply run on both glibc and musl, otherwise the project should make it easier for OS distributions to build and distribute libjnidispatch. As a user, I'm primarily confused about versioning. libjnidispatch should be versioned separately, and guarantee backward compatibility.