Direct use of Java analyzer from command line

• How to install the Java analyzer core
• Arguments of the Java analyzer core
• How to run the analysis
  • How to change the Java version to run the analyzer
• Java analyzer configuration file
• Global Java analyzer settings file
• The return codes for the Java analyzer core
• How to update PVS-Studio Java

The scenario where Java analyzer is run directly by invoking its core is an advanced use case and is not recommended as the primary method. For convenient integration and use of PVS-Studio Java analyzer, we recommend using:

• the Gradle build system plugin;
• the Maven build system plugin;
• the plugin for IntelliJ IDEA and OpenIDE;
• the Visual Studio Code extension.

How to install the Java analyzer core

On Windows, use the PVS-Studio installer to install the Java analyzer core. You can download the installer on the Download PVS-Studio page.

Also, regardless of what OS you are using, you can download the ZIP archive for Java on the Download page. The archive contains the Java analyzer core (a folder named 7.42.105102 in the pvs-studio-java directory). Unpack the Java analyzer core to the path you need or to the standard installation directory for the Java analyzer core:

• Windows: %APPDATA%/PVS-Studio-Java;
• Linux and macOS: ~/.config/PVS-Studio-Java.

Arguments of the Java analyzer core

To get information on all available arguments of the analyzer, run the --help command:

java -jar pvs-studio.jar --help

Analyzer arguments:

• --additional-warnings specifies a list of diagnostic rules that will be added to the analysis. It has a higher priority than --enabled-warnings, --disabled-warnings, and --analysis-mode settings. Default value: not set. Use whitespace to separate multiple rules. The example: --additional-warnings V6001 V6002 V6003.
• --analysis-mode specifies a list of enabled diagnostic rule groups. It has a lower priority than --enabled-warnings, --disabled-warnings, and --additional-warnings settings. Default value: GA. Use whitespace to separate multiple groups. The example: --analysis-mode GA OWASP. Available groups:
  • GA (general analysis diagnostic rules);
  • OWASP (rules based on OWASP Top Ten and OWASP ASVS).
• --analyze-only-list specifies a path to the text file that contains a list of paths to files and/or directories for the analysis—each entry must be on a separate line. Relative (will be expanded relative to the working directory) and absolute paths are supported. Files and/or directories read from the file specified in this argument are merged into a common list with values from the --analyze-only argument. This setting has a lower priority than --exclude. Default value: not set.
• --analyze-only specifies a list of files and/or directories for the analysis. Relative (will be expanded relative to the working directory) and absolute paths are supported. Files and/or directories passed in this argument are merged into a common list with files and/or directories from the--analyze-only-list argument. If no value is specified for this setting, all files will be analyzed. The setting has a lower priority than -- exclude. Default value: not set. Use whitespace to separate multiple files or directories. The example: --analyze-only "path/to/file1" "path/to/file2" "path/to/dir".
• --cfg (-c) specifies a configuration file for running the analyzer core. This file stores the values of Java analyzer core command line arguments in JSON format. Read more information about this file in the documentation. Default value: not set.
• --convert runs the analyzer in the conversion mode. Available modes:
  • toFullhtml converts a warning report to the .fullhtml format;
  • toSuppress converts a warning report to a suppress file.
• --disable-cache disables caching of the program metamodel. When caching is disabled, the project model is not cached and is rebuilt each run. Incremental analysis is also disabled, even if the --incremental flag is specified. Default value: false.
• --disabled-warnings specifies a list of diagnostic rules that are disabled during the analysis. If this setting is not specified, all diagnostic rules are considered enabled. This setting has a higher priority than --enabled-warnings and --analysis-mode, but has a lower priority than --additional-warnings. Default value: not set.
• --dst-convert specifies a path to the file or directory where the conversion result will be written—a file for toSuppress, a directory for toFullhtml.
• --enabled-warnings specifies a list of enabled diagnostic rules. During analysis, only the diagnostic rules from this list will be used. This setting has a lower priority than --disabled-warnings and --additional-warnings, but a higher priority than --analysis-mode. Default value: not set. Use whitespace to separate multiple groups. The example: --enabled-warnings V6001 V6002 V6003.
• --exclude specifies a list of files and/or directories to be excluded from analysis. Relative (will be expanded relative to the working directory) and absolute paths are supported. This setting has a higher priority than --analyze-only and --analyze-only-list. The setting has no default value. Use whitespace to separate multiple files or directories. The example: --exclude "path/to/file1" "path/to/file2" "path/to/dir".
• --ext-file specifies a path to the file with classpath. The setting has no default value. The classpath separator is : on *nix systems and ; on Windows systems. The example: --ext-file "path/to/project_classpath_file".
• --ext (-e) defines classpath. The setting has no default value. Use whitespace to separate multiple classpath entities. The example: --ext "path/to/file.jar" "path/to/dirJars".
• --fail-on-warnings sets a non-zero return program code if the analyzer issues at least one warning for the project code. This behavior can be useful when integrating into CI/CD. Default value: false.
• --force-rebuild forces a full rebuild of the cached program metamodel. When this flag is used, incremental project analysis mode is disabled (--incremental). Default value: false;
• --help (-h) outputs help information about Java analyzer core arguments to the console.
• --incremental (-i) enables incremental analysis. In this mode, the analyzer checks only modified files. Default value: false.
• --java-path specifies a path to the java executable file that is used to run the analyzer core. This setting can be configured system-wide in the global.json file. If java-path is not used, PVS-Studio attempts to use the path from the PATH environment variable.
• --logging specifies the logging level when starting the analysis. When enabled, log files are created for the current run in the .PVS-Studio/logs subdirectory relative to the directory where Java analyzer is currently running. If an invalid value is passed, logging will be disabled. Default value: OFF. Available values are:
  • OFF
  • ERROR
  • WARN
  • INFO
  • DEBUG
  • TRACE
  • ALL.
• --output-file (-o) specifies a path to the analyzer report file. The report format does not depend on the file extension specified in the parameter. Default value: ./PVS-Studio + the format extension defined by --output-type. To generate a report in .fullhtml format, specify the directory where the fullhtml subdirectory containing the analyzer report file (index.html) will be created. Default value: ./fullhtml. Note. It is recommend to use the PlogConverter (Windows) and plog-converter (Linux and macOS) instead of --output-file. They enable converting the analyzer report to more formats (for example, SARIF). The utilities provide additional features: filtering warnings from the report, converting paths in the report from absolute to relative (and vice versa), comparing reports, etc.
• --output-type (-O) specifies the analyzer report format. Default value: json. Available values are:
  • text
  • log
  • json
  • xml
  • tasklist
  • html
  • fullhtml
  • errorfile.
• --security-related-issues tags warnings related to potential security issues with an additional mark up in the SAST field. Default value: false.
• --sourcetree-root specifies the root part of the path that the analyzer uses to generate relative paths in the report for warnings. Default value: not set. The example: --sourcetree-root /path/to/project/directory.
• --src-convert specifies the path to the analyzer report that contains warnings (*.json);
• --src (-s) specifies the set of files or directories of the analyzed project. The setting has no default value. Use whitespace to separate multiple files or directories. The example: --src "path/to/file1" "path/to/file2" "path/to/dir".
• --suppress-base specifies a path to the suppress file that contains suppressed analyzer warnings. These warnings are excluded from future analysis reports. Default value: ./.PVS-Studio/suppress_base.json.
• --threads (-j) specifies the number of analysis threads. This setting can also be configured system-wide in the global.json file. Default value: the number of available logical processors.
• --timeout specifies the timeout for analyzing one file (in minutes). This setting can be configured system-wide in the global.json file. Default value: 10.
• --activate-license saves the license information specified via the --user-name and --license-key arguments to a file. Default value: false.
• --license-key specifies the license key.
• --license-path specifies a path to the license file. Valid file extensions are .xml, .lic. The default value is %APPDATA%/PVS-Studio/Settings.xml (Windows) or ~/.config/PVS-Studio/PVS-Studio.lic (macOS and Linux).
• --user-name specifies the analyzer username associated with the license key.
• --compatibility enables the V6078 diagnostic rule, which detects potential API compatibility issues between selected Java SE versions. Default value: false.
• --exclude-packages specifies the packages to be excluded from compatibility analysis. The V6078 diagnostic rule uses this setting if the --compatibility setting is enabled. The example: --exclude-packages "package1" "package2" "package3".
• --source-java specifies the Java SE version on which the analyzed application is developed. The V6078 diagnostic rule uses this setting if the --compatibility setting is enabled. Minimum value: 8. Maximum value: 14.
• --target-java specifies the Java SE version against which the API used in the application (--source-java) is checked for compatibility. The V6078 diagnostic rule uses this setting if the --compatibility setting is enabled. Minimum value: 8. Maximum value: 14.

How to run the analysis

Before running the analysis, enter the PVS-Studio license. To learn how to do this, please consult the documentation.

The quick start example of the Java analyzer core:

java -jar pvs-studio.jar -s A.java B.java C.java -e Lib1.jar Lib2.jar -j4 
-o report.txt -O text --user-name someName –-license-key someSerial

java -jar pvs-studio.jar -s src/main/java --ext-file classpath.txt -j4 
-o report.txt -O text --license-path PVS-Studio.lic

Note.

• The analyzer needs a collection of source files (or directories with source files) to perform the analysis and the classpath to build the program metamodel correctly.
• When analyzing a project, the plugin runs the Java analyzer core, which uses the Java version from the PATH environment variable by default. You can set a different version by configuring the javaPath plugin. The Arguments of the Java analyzer core section above describes this in detail.

How to change the Java version to run the analyzer

By default, the analyzer starts the core with java from the PATH environment variable. If you need to run the analysis with some other java, you can set it manually. To do this, run the Java analyzer core by using the full path to the java file from the JDK. The version of this JDK will be used when checking the source code of the project:

/path/to/jdk_folder/bin/java -jar pvs-studio.jar ^
-s A.java B.java C.java -e Lib1.jar Lib2.jar -j4 ^
-o report.txt -O text --user-name someName –-license-key someSerial

Java analyzer configuration file

To simplify the command for running the analysis, you can put the command line arguments into a special JSON file. Later this file can be passed to the analyzer core through the --cfg flag.

The syntax of the file is as follows:

{
  "single-value-parameter": "value",
  "multiple-values-parameter": ["value1", "value2", "value3"]
}

Each parameter in the configuration file is the full name of a command line flag with the value to be passed in that flag.

The example of a configuration file:

{
  "src": ["A.java", "B.java", "C.java"],
  "threads": 4,
  "output-file": "report.txt",
  "output-type": "text",
  "user-name": "someName",
  "license-key": "someSerial"
  ....
}

In this case, you can run the analyzer with the following line:

java -jar pvs-studio.jar –-cfg cfg.json

Note. Parameters passed via the command line have a higher priority than parameters specified in the configuration file.

Global Java analyzer settings file

The Java analyzer core takes some settings from the global.json file. This file is located at the default installation path of the Java analyzer core:

• Windows: %APPDATA%/PVS-Studio-Java/global.json;
• Linux and macOS: ~/.config/PVS-Studio-Java/global.json.

The list of the settings:

• java: the default value is java.
• jvm-arguments: the default value is ["-Xss64m"].
• threads: the default value is the number of available processors. This value can be overridden via the --threads command line argument of the Java analyzer core.
• timeout: the default value is 10. This value can be overridden via the --timeout command line argument of the Java analyzer core.
• verbose: the default value is true.

By default, these values are used for all Java analyzer cores in the system as well as for PVS-Studio Java plugins. If necessary, you can change the values of these parameters. For example, to ensure that all PVS-Studio plugins for Java utilize the same number of threads for analysis.

You can read more about which of these parameters can be changed in the following documentation sections:

• Maven
• Gradle
• PVS-Studio for IntelliJ IDEA and Android Studio.

The return codes for the Java analyzer core

• 0: the analysis is completed. Errors can be both detected and undetected.
• 50: an error occurred during analysis.
• 51: invalid arguments are passed when starting the analysis.
• 52: the invalid or expired license is used.
• 53: the analysis is completed. The analyzer detected potential errors in the project code. This return code will only be returned when the --fail-on-warnings Java analyzer core flag is enabled.
• 54: an attempt was made to access features available under the Enterprise license.

How to update PVS-Studio Java

When you run the analyzer, it checks whether a new version of PVS-Studio analyzer is available. If a new version of the analyzer has been released, the file with the analysis results contains the following message: "A newer version of PVS-Studio is available (7.42.105102)". This message contains the latest version of the Java analyzer core.

You can download the latest version of PVS-Studio from the file at the link.

To update the Java analyzer core, download the ZIP archive for Java on the Download page. The archive contains the Java analyzer core (a folder named 7.42.105102 in the pvs-studio-java directory). Unpack the Java analyzer core to the path you need or to the standard installation directory:

• Windows: %APPDATA%/PVS-Studio-Java
• Linux and macOS: ~/.config/PVS-Studio-Java

This process can be automated with various scripts to ensure that the latest version of the Java analyzer core is used.

Was this page helpful?

Message submitted.

Your message has been sent. We will email you at

If you do not see the email in your inbox, please check if it is filtered to one of the following folders:

• Promotion
• Updates
• Spam

If you can’t find an answer to your question, fill in the form below and our developers will contact you

By clicking this button you agree to our Privacy Policy statement