[[native-libloader]] = native-libloader

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

== Description

When using the https://docs.oracle.com/javase/8/docs/technotes/guides/jni/index.html[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 https://github.com/scijava/native-lib-loader[scijava/native-lib-loader] and the https://github.com/trustin/os-maven-plugin[trustin/os-maven-plugin].

== Requirements

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

== Usage

[source,java]

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 https://developer.arm.com/architectures/instruction-sets/floating-point[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 https://github.com/trustin/os-maven-plugin/[os-maven-plugin]. It follows the same conventions as the https://github.com/google/osdetector-gradle-plugin[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