native-libloader

A configurable and extendable loader for native libraries to use with JNI.

Description

When using the Java Native Interface, one faces the problem to ship the corresponding libraries (.dll for Windows, .dylib for Mac and .so for others) with their app.

Imagine you could use a mechanism to load those from .jar files you included in your application.

The Native LibLoader aims to provide such a mechanism. It was inspired by the scijava/native-lib-loader and the trustin/os-maven-plugin.

Requirements

This library only requires Java 6 and has no runtime dependencies.

Usage

import io.github.java_native.libloader.LibLoader;
import io.github.java_native.libloader.LibLoaderResult;
import io.github.java_native.libloader.NativeLibLoader;

public class Demo {
    public static void main(String[] args) {
        NativeLibLoader libLoader = LibLoader.getLibLoader();

        /* will load 'natives/linux-x86_64-64/libjssc.so' on linux. */
        final LibLoaderResult loadLibrary = libLoader.loadLibrary("jssc");

        /* LibLoaderResult has no fields at the moment. */
    }
}

The LibLoader is fully configurable, read below for more information.

Enhancements

This library loader has the following advancements over the existing lib loaders:

• Configurable paths. If you do not use the standard convention, just supply your own LibraryPathFormatter in the config.

• Extensible through various mechanisms.

  • Programatically: Add new Implementations of the interface SystemDefinition to the config.

  • Dynamically: Implement the SPI SystemDefinitionProvider and drop your .jar file in the classpath.

• Prepared for the HardFloat- and SoftFloat-Distinction for ARM platforms.

• Overridable

  • The default formatter can be overridden using -Dnative.libloader.systempath=libs/linux_64.

  • You can also supply a custom formatter in a configuration. The system property native.libloader.systempath will take precedence, though.

• Configurable

  • You can configure the temporary directory using the config, or using the system property native.libloader.tempdir.

  • The system property will take precedence.

Naming convention

The path names inside the .jar files are aligned to the os-maven-plugin. It follows the same conventions as the osdetector-gradle-plugin.

osname-arch-bitness[-qualifier]

• OS names are taken from System.getProperty("os.name").getLowerCase(Locale.ENGLISH).

• The architecture is normalized from System.getProperty("os.name").

• The bitness (bits in long) is added as an identifying measure, as the bitness of the JVM may not be the same as the operating system’s bitness.
  Example: You are running a 32bit jvm on a 64bit system. In this case, this should be 32.

• An optional qualifier can be added for add-on chips, like _hf for ARM.

Supported systems

Currently, the following systems are built in:

• Linux x86_64 natives/linux-x86_64-64

• Linux x86_32 natives/linux-x86_32-32

• Linux arm_32 natives/linux-arm_32-32

• Linux arm_32 with VFP registers natives/linux-arm_32-32-hf

• MacOS x64_64 natives/osx-x86_64-64

• Windows x86_64 natives/windows-x86_64-64

• Windows x86_32 natives/windows-x86_32-32