microsoft / microsoft/onnxruntime
[Feature Request] [Java] Configurable Native Library Extraction
- Dominant language
- C++
- Stars
- 21.9k
- Forks
- 4.2k
- Avg merge
- 4d 11h
- Merged PRs (30d)
- 184
Description
### Describe the feature request
**Goal:** Provide developers with granular control over the extraction location and persistence of bundled native libraries to support restricted environments, dependency enrichment, and startup optimization.
#### **Proposed Configuration Properties**
| Property | Description |
| --- | --- |
| **`onnxruntime.native.extract.path`** | Specifies a custom directory for extracting native libraries from the JAR. If unset, the system uses the default temporary directory. |
| **`onnxruntime.native.extract.cleanup`** | Boolean (default: `true`). If `false`, the extraction directory and its contents are NOT marked for deletion on JVM exit. |
#### **Differentiation from `onnxruntime.native.path`:**
The existing `onnxruntime.native.path` property is used to point the loader to a directory of *externally provided* binaries. This new request focuses on cases where the user *wants* to use the libraries bundled in the JAR, but needs to control exactly where they are unpacked.
#### **Suggested Workflow Changes**
1. **Init Logic:** Check `onnxruntime.native.extract.path`. If set, use it as the base for `tempDirectory`.
2. **Smart Extraction:** If a custom path is used and a library already exists there (optionally verifying version/size), skip the extraction I/O.
3. **Conditional Cleanup:** Only register `file.deleteOnExit()` if `onnxruntime.native.extract.cleanup` is `true`.
### Describe scenario use case
* **Dependency Enrichment:**
By defining a predictable extraction path, users can "enrich" that directory before the runtime initializes. For example, a user could place required CUDA runtime libraries (not bundled in the JAR) into the custom extraction folder. Since the OS dynamic linker typically checks the directory of the loading library first, this ensures the ONNX Runtime CUDA provider finds its dependencies without complex system-wide `PATH`/`LD_LIBRARY_PATH` modifications.
* **Startup Performance & Persistence:**
Currently, every JVM launch forces a new extraction to a randomized temp folder followed by a `deleteOnExit()`. For frequently restarted applications (e.g., CLI tools, serverless functions, or rapid development cycles), this adds significant I/O overhead. Allowing users to disable cleanup and reuse a persistent directory enables a "cache" mechanism that dramatically speeds up subsequent initializations.
Contributor guide
Research direction
Start by locating the Java native-library initialization and the existing handling for onnxruntime.native.path. Trace how bundled libraries are extracted, how tempDirectory is selected, and where deleteOnExit() is registered. Done means the two proposed properties control the extraction directory and cleanup behavior, with persistent reuse handled as specified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100