Class NativeLibrary

java.lang.Object
smile.onnx.NativeLibrary
public final class NativeLibrary extends Object
Shared resolver and loader for the ONNX Runtime native libraries.

Both the classic ONNX Runtime bindings (smile.onnx) and the GenAI bindings (smile.onnx.genai) need the same onnxruntime shared library loaded before the jextract-generated foreign bindings perform their lookup. This class is the single place that resolves, guards, and loads it, so the two paths cannot drift apart.

Why an explicit absolute-path load at all

The generated bindings load by bare library name (SymbolLookup.libraryLookup(System.mapLibraryName("onnxruntime"))), which delegates to the operating system's usual search. On Windows an older onnxruntime.dll shipped in C:\Windows\System32 wins that search over a pip-installed copy on PATH — the system directory precedes user directories in the default DLL search order. Loading the intended copy first, by absolute path, binds the process to it and makes the later bare-name lookup resolve to the already-loaded copy. On most Unix-like systems loading the library first is also required because its dependencies are not on the loader's search path.

Resolution order

A library directory is resolved from, in order:

  1. a JVM system property (e.g. -Donnxruntime.native.path)
  2. an environment variable (e.g. ONNXRUNTIME_NATIVE_PATH)
  3. directories on PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH that contain the mapped library file

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

  • Field Details

    • ORT_NATIVE_PATH_PROPERTY

      public static final String ORT_NATIVE_PATH_PROPERTY
      System property naming the directory that contains onnxruntime (environment variable ONNXRUNTIME_NATIVE_PATH).
      See Also:

    • GENAI_NATIVE_PATH_PROPERTY

      public static final String GENAI_NATIVE_PATH_PROPERTY
      System property naming the directory that contains onnxruntime-genai (environment variable ONNXRUNTIME_GENAI_NATIVE_PATH).
      See Also:

    • ORT_NATIVE_PATH_ENV

      public static final String ORT_NATIVE_PATH_ENV
      Environment variable counterpart of ORT_NATIVE_PATH_PROPERTY.
      See Also:

    • GENAI_NATIVE_PATH_ENV

      public static final String GENAI_NATIVE_PATH_ENV
      Environment variable counterpart of GENAI_NATIVE_PATH_PROPERTY.
      See Also:

    • ORT_LIBRARY

      public static final String ORT_LIBRARY
      Bare (unmapped) name of the ONNX Runtime library.
      See Also:

    • GENAI_LIBRARY

      public static final String GENAI_LIBRARY
      Bare (unmapped) name of the ONNX Runtime GenAI library.
      See Also:

  • Method Details

    • 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 search path is 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. onnxruntime.
      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. onnxruntime.
      Returns:
      true when the library is loaded after this call.

    • findLibraryFile

      public static String findLibraryFile(String bareName)
      Finds a mapped library file under the resolved native directories or on the OS library search path.
      Parameters:
      bareName - the bare library stem, e.g. QnnHtp.
      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. onnxruntime_providers_cuda.
      Returns:
      true when the file exists somewhere resolvable.