Add a module-info.java to enable use on the module path and build a binary with jlink

[julesjacobsen]

Is there any desire to make the HTSJDK a modernised modular Java library? It would be useful for people trying to build and distribute applications as it can be used to create smaller standalone applications independent of any system-level JDK, smaller docker images and improve startup time and security.

Before you submit

Make sure your issue is not already in the htsjdk issue tracker

Not that I could find

Description of the issue:

Describe your issue here.
Provide screenshots , stacktraces , or logs where appropriate.

Trying to include htsjdk in a module-info.java file will prevent the build on Gradle and will stop jlink with an error as the HTSJDK is not a modular library. This prevents Java 9+ modular applications from being able to build nice small stand-alone binaries using jlink

Your environment:

• version of htsjdk - 4.1.3
• version of java - graalvm-jdk-23.0.1+11.1
• which OS - Linux Mint 22 base: Ubuntu 24.04 noble

Steps to reproduce

If you're reporting a bug, tell us how to reproduce this issue. If possible, include a short code snippet or attach test data to demonstrate the problem.

Adding a module-info.java file under src/main/java in a project depending on htsjdk will result in build issues and jlink errors when trying to use the module path. e.g.

module my-module {
    requires htsjdk;

    exports my-module;
}

Expected behaviour

modular jars will build under Gradle, jlink will complete without errors.

Actual behaviour

Under Gradle, when trying to build jar the error Not a module and no mapping defined: htsjdk-4.1.3.jar

With Maven and the jlink plugin running mvn jlink:jlink
jlink error:

[ERROR] Error: automatic module cannot be used with jlink: htsjdk from file:///home/user/.m2/repository/com/github/samtools/htsjdk/4.1.3/htsjdk-4.1.3.jar

I tried building a modularised version by adding src/main/java/module-info.java to the project:

module htsjdk {
    requires org.apache.commons.jexl; // not modular - jexl3 is modular requires org.apache.commons:commons-jexl3:3.4.0
    requires java.scripting;
    requires java.desktop;
    requires ngs.java; // not modular
    requires org.apache.commons.compress;
    requires org.json;
    requires snappy.java; // not modular

    exports htsjdk.annotations;
    exports htsjdk.beta.codecs.hapref.fasta;
    exports htsjdk.beta.codecs.reads;
    exports htsjdk.beta.codecs.variants.vcf;
    exports htsjdk.beta.exception;
    exports htsjdk.beta.io;
    exports htsjdk.beta.io.bundle;
    exports htsjdk.beta.plugin;
    exports htsjdk.io;
    exports htsjdk.samtools;
    // there are lot of packages under samtools - should they all be public?
    exports htsjdk.samtools.cram;
    exports htsjdk.samtools.fastq;
    exports htsjdk.samtools.filter;
    exports htsjdk.samtools.liftover;
    exports htsjdk.samtools.metrics;
    exports htsjdk.samtools.reference;
    exports htsjdk.samtools.seekablestream;
    exports htsjdk.samtools.sra; // only use of ngs.java
    exports htsjdk.samtools.util; // uses snappy.java as optional dependency
    exports htsjdk.samtools.util.nio;
    exports htsjdk.samtools.util.ftp;
    exports htsjdk.samtools.util.zip;
    exports htsjdk.samtools.util.htsget;
    exports htsjdk.utils;
    exports htsjdk.variant.bcf2;
//    exports htsjdk.variant.example; // looks like this should be a test
    exports htsjdk.variant.utils;
    exports htsjdk.variant.variantcontext; // only use of org.apache.commons.jexl in VariantContextUtils
    exports htsjdk.variant.variantcontext.filter;
    exports htsjdk.variant.variantcontext.writer;
    exports htsjdk.variant.vcf;
}

Attempting to run gradle jar results in failure as there are three libraries which are not modular which prevent HTSJDK from being modularised:

• org.apache.commons.jexl,
• snappy.java
• ngs.java

org.apache.commons.jexl can be updated to jexl3 which is modular, but has some incompatibilities with jexl 2 (I didn't look into the details). snappy.java and ngs.java don't appear to have any open issues related to modularisation and I think the only path forward is to either try and persuade the maintainers to add a module-info.java or a Automatic-Module-Name: to the jar's MANIFEST.MF or find alternatives to these libs.