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:

Note: If a file is specified but no format, JarHC tries to guess the format based on the filename extension:

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

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

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
• m - Modules
• cv - Class Versions
• 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.

JAR file names

--remove-version
--use-artifact-name

Those two options can be used to "normalize" the JAR file names. This is useful if you later want to compare/diff two reports which were created with different versions of some libraries.

With "--remove-version", JarHC will try to remove the version number from the JAR file name. Example: "asm-tree-7.0.jar" becomes "asm-tree.jar". Note that the algorithm used to find and remove a version number is fuzzy. If third-party developers use non-standard version number schemes, JarHC may fail to remove the complete version number.

With "--use-artifact-name", JarHC will re-generate the JAR file name from the artifact coordinates (if available). Example: "l4j-127.jar" may become "log4j-1.2.7.jar".

You can also combine the two options, in which case JarHC will generate a JAR file name based on the artifact ID but without version number. Example: "l4j-127.jar" may become "log4j.jar".

Those options only have an impact on the JAR file names as they are shown in the report. The actual JAR files on disk are of course not renamed.

Order of JAR files

--sort-rows

This option can be used to sort the rows in the report. By default, JAR files are listed in the order they are found on the classpath. This option can be used to sort the JAR files alphabetically.

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>