Usage

JarHC is available as command line application:

java -jar jarhc-app.jar [options] <artifact> [<artifact>]*

Arguments

<artifact> is an absolute or relative path to a JAR file, a WAR file, a JMOD file, a directory with JAR, WAR, and JMOD files, or Maven artifact coordinates of the form "<GroupID>:<ArtifactID>:<Version>". In case of a directory, all files found in that directory and any subdirectories (recursive) are included in the analysis.

If <artifact> is a path to a WAR file, JarHC includes all JAR files from /WEB-INF/lib folder in the analysis.

Options

Help

--help
--version

Print usage information or version information, and then exit.

Debug and trace output

--debug
--trace

Enable verbose output.

Report file path

-o <file> | --output <file>

Report file path. If this option is not present, the report is printed to STDOUT. This option can be specified multiple times to generate multiple reports with different formats. JarHC tries to guess the format based on the filename extension:

• *.txt -> text report
• *-list.txt -> list report
• *.html -> HTML report
• *.json -> JSON report

Example: -o report.html -o report.txt -o report-list.txt -o report.json

Report title

-t <title> | --title <title>

Report title.

Default: "JAR Health Check Report".

Example: -t "MyApp 1.0"

Report sections

-s <sections> | --sections <sections>

List of sections to include in the report.

Default: [none] (include all sections).

Example: -s "jf,cv,jd"

If the list of sections is prefixed with '-' the given sections are excluded. Example: -s "-p,bc,bl"

Sections:

• jf - JAR Files
• jm - JAR Manifests
• m - JPMS Modules
• ob - OSGi Bundles
• cv - Class Versions
• u - Updates
• jd - JAR Dependencies
• d - Dependencies
• p - Packages
• dc - Duplicate Classes
• bc - Binary Compatibility
• bl - Blacklist
• jr - Java Runtime

Skip empty sections

--skip-empty

Empty sections will not be included in the report.

Example: If an analysis shows that there are no duplicate classes and resources, the section "Duplicate Classes" is not included in the report.

This option mainly applies to the sections listing issues:

• Duplicate Classes
• Binary Compatibility
• Blacklist

Other sections are never empty.

Release

-r <number> | --release <number>

Specify the Java release used when loading classes and resources from multi-release JAR files.

The value for this option must be a Java major version number greater or equal to 8.

Default: Major version of Java runtime used to run JarHC.

Example: --release 11

Classpath

-cp <path> | --classpath <path>

Instead of passing JAR files as arguments, you can also use the option "--classpath". As for arguments, this option supports passing a JAR file, a directory with JAR files, a WAR file, or Maven artifact coordinates.

Example: --classpath myapp-1.0.jar,mylib-1.0.jar,libs

Provided and runtime classpath

--provided <path>
--runtime <path>

Specify additional paths to JAR files or directories with JAR files handled as "provided" or "runtime" (JDK/JRE) libraries. Those JAR files are not analyzed, but references to them are validated.

The value for these options can be a single JAR file, a single directory, or a comma-separated list of JAR files and/or directories. These options can also be used multiple times to add multiple JAR files or directories.

Example: --provided servlet-api-3.0.jar,jsp-api-3.0.jar --runtime $JAVA_HOME/jre/lib

Class loading strategy

--strategy ParentLast|ParentFirst

Define the strategy when searching for classes on the classpath.

With "ParentFirst", JarHC will first try to find the class on the runtime classpath, then on the provided classpath, and finally on the normal classpath.

With "ParentLast", JarHC will first try to find the class on the normal classpath, then on the provided classpath, and finally on the runtime classpath.

Default: "ParentLast"

Example: --strategy ParentFirst

Custom Maven repository

--repository-url <url>
--repository-username <username>
--repository-password <password>

Specify a custom Maven repository URL. Username and password are optional.

Ignore missing annotations

--ignore-missing-annotations

Binary Compatibility will not report an issue if no class definition is found for an annotation.

This can be used to suppress warnings if libraries make heavy use of annotations for code analysis like @NonNull or @SuppressFBWarnings.

Ignore exact copy

--ignore-exact-copy

Duplicate Classes section does not list classes and resources which are identical.

Path to cache directory

--data <path>

Specify the path to a local data directory used to cache information about artifacts. The special value "TEMP" can be used to create a temporary data directory. If this option is not present, JarHC will check if environment variable JARHC_DATA is set and use its value.

Default: "~/.jarhc"

Example: --data /tmp/jarhc or export JARHC_DATA=/tmp/jarhc

If the directory does not exist, it is automatically created.

Load options from a file

--options <path>

Load additional options from a file. The file must contain one option per line. Empty lines and lines starting with '#' are ignored. Use '${...}' to reference environment variables.

Example options file:

--title MyApp 1.0
--classpath myapp-1.0.jar,mylib-1.0.jar,libs
--release 8
--runtime ${JDK_8_HOME}/jre/lib
--output report.html

Java System Properties

A set of low-level options can be set using Java System Properties.

HTTP client for Maven Search API

URL pattern with %s as placeholder for checksum:

jarhc.search.url = https://search.maven.org/solrsearch/select?q=1:%%22%s%%22&rows=20&wt=json

Timeout in seconds:

jarhc.search.timeout = 65

Important: The Maven Search API often requires 15, 30, or even 45 seconds to respond. If the timeout is too short, JarHC may not find the artifact.

HTTP request header "User-Agent":

jarhc.search.headers.User-Agent = Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:129.0) Gecko/20100101 Firefox/129.0

The above default User-Agent value is from a Firefox browser on Ubuntu Linux in September 2024.

Additional HTTP request headers:

jarhc.search.headers.<NAME> = <VALUE>