Class NativeLibrary

java.lang.Object

smile.linalg.NativeLibrary

public final class NativeLibrary
extends Object

Resolver and loader for SMILE's jextract-generated linear algebra bindings, mirroring smile.onnx.NativeLibrary for the ONNX Runtime.

The generated bindings obtain their symbols through SymbolLookup.libraryLookup(System.mapLibraryName(name)), which calls dlopen on a bare name. That lookup consults neither java.library.path nor LD_LIBRARY_PATH, and on macOS the system integrity protection (SIP) strips DYLD_* variables when the JVM is started through the /usr/bin/java stub. A Homebrew libarpack.dylib is therefore not found unless the working directory happens to contain it — which used to force a copy or symlink.

An explicit absolute-path System.load does not go through dyld's name search, so SIP cannot interfere with it. Loading the library first binds the image into the process; the binding's SymbolLookup.loaderLookup() then resolves the symbols from that image.

Resolution order

1. a JVM system property (e.g. -Darpack.native.path)
2. an environment variable (e.g. ARPACK_NATIVE_PATH)
3. the well-known installation directories for the platform
4. PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH

The search-path scan deliberately skips System32 and SysWOW64, so a stale Windows system copy is never treated as the intended one.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ARPACK_LIBRARY	Bare (unmapped) name of the ARPACK library.
static final String	ARPACK_NATIVE_PATH_ENV	Environment variable counterpart of ARPACK_NATIVE_PATH_PROPERTY.
static final String	ARPACK_NATIVE_PATH_PROPERTY	System property naming the directory that contains ARPACK.
static final String	BACKEND_ENV	Environment variable counterpart of BACKEND_PROPERTY.
static final String	BACKEND_PROPERTY	System property to select linear algebra backend ("auto", "native", "java").
static final String	BLAS_LIBRARY	Bare (unmapped) default name of the BLAS library.
static final String	BLAS_NATIVE_PATH_ENV	Environment variable counterpart of BLAS_NATIVE_PATH_PROPERTY.
static final String	BLAS_NATIVE_PATH_PROPERTY	System property naming the directory that contains BLAS.
static final String	LAPACK_LIBRARY	Bare (unmapped) default name of the LAPACK library.
static final String	LAPACK_NATIVE_PATH_ENV	Environment variable counterpart of LAPACK_NATIVE_PATH_PROPERTY.
static final String	LAPACK_NATIVE_PATH_PROPERTY	System property naming the directory that contains LAPACK.

Method Summary

Modifier and Type	Method	Description
static String	backend()	Returns the configured linear algebra backend mode ("auto", "native", or "java").
static boolean	ensureArpackLoaded()	Loads the ARPACK library by absolute path, if it can be resolved.
static boolean	ensureBlasLoaded()	Loads the BLAS library by absolute path, if it can be resolved.
static boolean	ensureLapackLoaded()	Loads the LAPACK library by absolute path, if it can be resolved.
static boolean	ensureLoaded(String property, String env, String bareName)	Loads a native library by absolute path, at most once per library stem.
static String	findLibraryFile(String bareName)	Finds a mapped library file under the well-known directories or on the OS library search path.
static boolean	isBlasAvailable()	Returns whether native CBLAS is available and enabled.
static boolean	isLapackAvailable()	Returns whether native CLAPACK is available and enabled.
static boolean	libraryFilePresent(String bareName)	Returns whether a mapped library file is present (loaded or not).
static String	resolveDir(String property, String env, String bareName)	Resolves the directory holding a mapped native library.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

BACKEND_PROPERTY

public static final String BACKEND_PROPERTY

System property to select linear algebra backend ("auto", "native", "java").

See Also:

• Constant Field Values

BACKEND_ENV

public static final String BACKEND_ENV

Environment variable counterpart of BACKEND_PROPERTY.

See Also:

• Constant Field Values

BLAS_NATIVE_PATH_PROPERTY

public static final String BLAS_NATIVE_PATH_PROPERTY

System property naming the directory that contains BLAS.

See Also:

• Constant Field Values

BLAS_NATIVE_PATH_ENV

public static final String BLAS_NATIVE_PATH_ENV

Environment variable counterpart of BLAS_NATIVE_PATH_PROPERTY.

See Also:

• Constant Field Values

LAPACK_NATIVE_PATH_PROPERTY

public static final String LAPACK_NATIVE_PATH_PROPERTY

System property naming the directory that contains LAPACK.

See Also:

• Constant Field Values

LAPACK_NATIVE_PATH_ENV

public static final String LAPACK_NATIVE_PATH_ENV

Environment variable counterpart of LAPACK_NATIVE_PATH_PROPERTY.

See Also:

• Constant Field Values

ARPACK_NATIVE_PATH_PROPERTY

public static final String ARPACK_NATIVE_PATH_PROPERTY

System property naming the directory that contains ARPACK.

See Also:

• Constant Field Values

ARPACK_NATIVE_PATH_ENV

public static final String ARPACK_NATIVE_PATH_ENV

Environment variable counterpart of ARPACK_NATIVE_PATH_PROPERTY.

See Also:

• Constant Field Values

BLAS_LIBRARY

public static final String BLAS_LIBRARY

Bare (unmapped) default name of the BLAS library.

LAPACK_LIBRARY

public static final String LAPACK_LIBRARY

Bare (unmapped) default name of the LAPACK library.

ARPACK_LIBRARY

public static final String ARPACK_LIBRARY

Bare (unmapped) name of the ARPACK library.

See Also:

• Constant Field Values

Method Details

backend

public static String backend()

Returns the configured linear algebra backend mode ("auto", "native", or "java").

Returns:

the backend mode in lowercase.

isBlasAvailable

public static boolean isBlasAvailable()

Returns whether native CBLAS is available and enabled.

Returns:

true if native CBLAS should be used; false to use pure Java.

isLapackAvailable

public static boolean isLapackAvailable()

Returns whether native CLAPACK is available and enabled.

Returns:

true if native CLAPACK should be used; false to use pure Java.

resolveDir

public static String resolveDir(String property,
 String env,
 String bareName)

Resolves the directory holding a mapped native library.

An explicitly configured system property or environment variable wins outright, even if the named library is not actually there: silently falling back to a different copy found on the search path would be worse than letting the load fail with an honest "not found". The well-known directories and the search path are consulted only when neither is set.

Parameters:

property - the JVM system property name (may be null).

env - the environment variable name (may be null).

bareName - the bare library stem, e.g. arpack.

Returns:

the absolute directory path, or null when not found.

ensureLoaded

public static boolean ensureLoaded(String property,
 String env,
 String bareName)

Loads a native library by absolute path, at most once per library stem.

Safe to call from several classes' static initializers: the first call performs the load, later calls are no-ops. A failure to load is swallowed — the caller's own native lookup will produce a clearer error than this best-effort preload could.

Parameters:

property - the JVM system property name (may be null).

env - the environment variable name (may be null).

bareName - the bare library stem, e.g. arpack.

Returns:

true when the library is loaded after this call.

ensureBlasLoaded

public static boolean ensureBlasLoaded()

Loads the BLAS library by absolute path, if it can be resolved.

Returns:

true when the library is loaded after this call.

ensureLapackLoaded

public static boolean ensureLapackLoaded()

Loads the LAPACK library by absolute path, if it can be resolved.

Returns:

true when the library is loaded after this call.

ensureArpackLoaded

public static boolean ensureArpackLoaded()

Loads the ARPACK library by absolute path, if it can be resolved.

Returns:

true when the library is loaded after this call.

findLibraryFile

public static String findLibraryFile(String bareName)

Finds a mapped library file under the well-known directories or on the OS library search path.

Parameters:

bareName - the bare library stem, e.g. arpack.

Returns:

the absolute path, or null when the file is absent.

libraryFilePresent

public static boolean libraryFilePresent(String bareName)

Returns whether a mapped library file is present (loaded or not).

Parameters:

bareName - the bare library stem, e.g. arpack.

Returns:

true when the file exists somewhere resolvable.