NVIDIA / NVIDIA/cuvs

[FEA] Inclusion of `libcuvs.so` in `cuvs-java*jar`

Open
#964 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Build feature request Java
Dominant language
Cuda
Stars
854
Forks
236
Avg merge
3d 3h
Merged PRs (30d)
62

Description

Requirement

We should evaluate the viability of including the libcuvs.so library as part of the cuvs-java*jar. My contention is that this will make released artifacts easier to deploy, thus improving the end-user experience.

Background

As things currently stand in the 25.06 release, the cuvs-java*jar includes a libcuvs_java.so, containing some legacy shim code to insulating the Java layer from API changes in libcuvs.so. There are currently discussion regarding the removal of this library, but that's another kettle of fish.

The current deployment model involves shipping the cuvs-java.jar via Maven, and resolving its native dependency on libcuvs via conda/mamba. The snag here is that if the user updates their Maven dependency (to say 25.08) and neglects to update conda/mamba in lockstep, they run the risk of incompatible binaries.
By packaging the native libs with the jar artifact, such botched deployments can be avoided.

This method is currently used in the https://github.com/NVIDIA/spark-rapids-jni/ project, for libcudf symbols.

Advantages
  1. Ease of deployment: The jar only need be dropped into the classpath of the user's program.
  2. Better foolproofing: With a self-contained jar, the risk of a botched update is reduced.
  3. Debuggability: The active libcuvs library is deterministic, and need not be guessed at.
Risks
  1. Library size: Including libcuvs.so will increase the jar artifact size.
    a. Building for compute-capability=75 yields a 200MB .so.
    b. Maven Central likely has limits on artifact size.
    c. Mitigation: Work is underway to reduce the library size already, with explicit template instantiations, etc. Also, the library will be compressed when included in the jar.
  2. Possibility of flagging by antivirus tools:
    a. Jar artifacts containing native code might be flagged by enterprise security tools.
    b. Mitigation: TBD.
    c. FWIW, spark-rapids-jni jars are yet to face being flagged.
  3. Multi-platform releases:
    a. If the jars do not contain native code, it might be viable to have a single jar for all platforms (x86-64, aarch64, etc.). Inclusion of native code will make that option unviable.
    b. My contention is that we're likely to need separate Java artifacts for x86-64 and aarch64 anyway.
    c. Mitigation: This isn't lost functionality yet. AFAICT, there hasn't been a cuvs-java release that hasn't included native code.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing how the cuvs-java*jar currently packages libcuvs_java.so and resolves libcuvs through conda/mamba. Compare that deployment model with the spark-rapids-jni approach mentioned in the issue, then document whether bundling libcuvs.so is viable given artifact size, platform, and security concerns.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
build-system, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.