Direct use of Java analyzer from command line

• Installing the Java analyzer core
• Arguments of the Java analyzer core
• Running 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
• Updating PVS-Studio Java

PVS-Studio Java analyzer has two main components: the core performing the analysis and the plugins for integrating the analyzer into build systems (Maven and Gradle) and IDEs (PVS-Studio for IntelliJ IDEA and Android Studio).

With the plugins, you can:

• run and configure the analyzer in a user-friendly interface;
• view and filter the analysis results easily (IDE);
• collect and transfer the project structure data (the set of source files and the classpath) to the analyzer core;
• deploy the version of the analyzer core compatible with the plugin version.

Installing 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.39.99802 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:

• ‑‑src (-s) is the set of *.java files or directories for analysis. The value is absent by default. If you need to list multiple files/directories, use whitespace as a separator. Example: ‑‑src "path/to/file1" "path/to/file2" "path/to/dir".
• ‑‑ext (-e) is the definition of the classpath (*.jar/*.class files and directories). The value is absent by default. If you need to list multiple classpath entities, use whitespace as a separator. Example: ‑‑ext "path/to/file.jar" "path/to/dirJars".
• ‑‑ext-file is the path to the classpath file. The value is absent by default. The classpath separator is : on *nix systems and ; on Windows. Example: ‑‑ext-file "path/to/project_classpath_file".
• ‑‑cfg (-c) is the configuration file for running the analyzer core. This file stores the values of the Java analyzer core command line arguments in JSON format. You can find more information on this file in the next section of the documentation. The value is absent by default.
• ‑‑help (-h) is the information on the Java analyzer core arguments outputs to the console.
• ‑‑user-name is the user name.
• ‑‑license-key is the license key.
• ‑‑license-path is the path to the license file. Available file extensions are .xml and .lic. The default value is %APPDATA%/PVS-Studio/Settings.xml (on Windows) or ~/.config/PVS-Studio/PVS-Studio.lic (on macOS and Linux);
• ‑‑activate-license is the flag for saving licensing information specified in the ‑‑user-name and ‑‑license-key arguments to a file. The default value is false.
• ‑‑convert is used to run the analyzer in the conversion mode. The following modes are available:
  • toFullhtml converts a report with warnings to the .fullhtml format;
  • toSuppress converts a report with warnings to the suppress file.
• ‑‑src-convert is the path to the analyzer report which contains warnings (*. Json).
• ‑‑dst-convert is the path to the file/directory where the result of the conversion is written (the path to the file for toSuppress, and the path to the directory for toFullhtml).
• ‑‑output-type (-O) is the format of the analyzer report (.text, .log, .json, .xml, .tasklist, .html, .fullhtml, .errorfile). The default value is .json. Example: ‑‑output-type txt.
• ‑‑output-file (-o) is the path to the analyzer report file. The format of the report contents does not depend on the file extension specified in this argument. The default value is: ./PVS-Studio + the format extension from the ‑‑output-type argument. To get a report in the .fullhtml format, specify the directory where the fullhtml folder containing the report file (index.html) is created. The default value is ./fullhtml. Note. Instead of the ‑‑output-file argument, it's better to use the PlogConverter (Windows) and plog-converter (Linux and macOS) console utilities. They enable you to convert 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), getting data on the differences between reports, etc.;
• ‑‑threads (-j) is the number of analysis threads. Analysis threads require more system resources but enable you to speed up the analysis of a project. You can also specify this setting for the entire system in the global.json file. The default value is the number of available processors.
• ‑‑sourcetree-root is the root part of the path that the analyzer uses to generate relative paths in diagnostic rules. By default, PVS-Studio displays absolute paths to the files where the analyzer found errors. With this setting, you can specify the root part of the path, which the analyzer will automatically replace with a special marker. The file path is replaced if it begins with the specified root path. Next, the report with relative paths can be used to view the analysis results in an environment with a different location of source files. For example, in different operating systems. The default value is absent. Example: ‑‑sourcetree-root /path/to/project/directory.
• ‑‑analysis-mode is the list of enabled groups of warnings. Available groups: GA (general analysis diagnostic rules), OWASP (OWASP ASVS compliant diagnostic rules). The ‑‑enabled-warnings, ‑‑disabled-warnings, and ‑‑additional-warnings settings have a higher priority than this setting. If a group of diagnostic rules is disabled (or enabled), you can use the settings listed above to enable (or disable) individual diagnostic rules. When listing multiple groups, use whitespace as a separator. The default value is GA; Example: ‑‑analysis-mode GA OWASP.
• ‑‑enabled-warnings is the list of enabled diagnostic rules. During the analysis, the analyzer uses only the diagnostic rules in the list. If the value is absent, then all diagnostic rules are enabled unless a value is specified for ‑‑disabled-warnings. The ‑‑enabled-warnings setting has a lower priority than the ‑‑disabled-warnings and ‑‑additional-warnings settings, but a higher priority than ‑‑analysis-mode. The default value is absent. When listing multiple diagnostic rules, use whitespace as a separator. Example: ‑‑enabled-warnings V6001 V6002 V6003.
• ‑‑disabled-warnings is the list of disabled diagnostic rules. The listed diagnostic rules are disabled during the analysis. If there are no diagnostic rules in the list, all diagnostic rules are enabled unless ‑‑enabledWarnings is set. The ‑‑disabled-warnings setting has a higher priority than the enabledWarnings and ‑‑analysisMode settings, but a lower priority than –additionalWarnings. The default value is absent.
• ‑‑additional-warnings is the list of diagnostic rules to be included in analysis, which are enabled by default. If a diagnostic rule is added to this list, its co-presence in the ‑‑enabledWarnings and ‑‑disabledWarnings lists is ignored. In addition, it is possible to enable the diagnostic rule even if the group of diagnostic rules to which it belongs is disabled (i.e. ‑‑analysisMode does not contain this group). The ‑‑additional-warnings setting has a higher priority than the ‑‑enabled-warnings, ‑‑disabled-warnings and ‑‑analysis-mode settings. The default value is absent. When listing multiple diagnostic rules, use whitespace as a separator. Example: ‑‑additional-warnings V6001 V6002 V6003.
• ‑‑exclude is the list of files and/or directories to be excluded from the analysis (absolute or relative paths that are expanded relative to the current working directory). When the value for this setting is absent, all files are analyzed unless a value for the ‑‑analyze-only or ‑‑analyze-only-list setting is specified. The ‑‑exclude setting has a higher priority than the —analyze-only and —analyze-only-list settings. The default value is absent. When listing multiple files or directories, use whitespace as a separator. Example: ‑‑exclude "path/to/file1" "path/to/file2" "path/to/dir".
• ‑‑analyze-only is the list of files and/or directories to be analyzed (absolute or relative paths that are expanded relative to the current working directory). You can also write these paths to a file line-by-line and pass the path to that file to the ‑‑analyze-only-list argument. When the value for this setting is absent, all files are analyzed unless a value for the ‑‑exclude or ‑‑analyze-only-list setting is specified. The ‑‑analyze-only setting has a lower priority than the ‑‑exclude setting. 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. The default value is absent. When listing multiple files or directories, use whitespace as a separator. Example: ‑‑analyze-only "path/to/file1" "path/to/file2" "path/to/dir".
• ‑‑analyze-only-list is the path to the text file which contains the list of paths to files/directories to be analyzed (each entry must be on a separate line). Relative (will be expanded relative to the current working directory) and absolute paths are supported. When the value for this setting is absent, all files are analyzed unless a value for the ‑‑exclude or ‑‑analyze-only setting is specified. ‑‑analyze-only-list has a lower priority than the ‑‑exclude setting. Files and/or directories read from the file specified in this argument are merged into a common list with files and/or directories from the ‑‑analyze-only argument. The default value is absent.
• ‑‑suppress-base is the path to the suppress file which contains suppressed warnings of the analyzer. Warnings from the suppress file will not be included in the report in any subsequent project checks. You can add warnings to the suppress file in several ways: in the PVS-Studio plugin for IntelliJ IDEA and Android Studio, by using the pvsSuppress command, in the plugins for Gradle and Maven, by using the ‑‑convert argument which has the toSuppress value. The default value is ./.PVS-Studio/suppress_base.json.
• ‑‑fail-on-warnings is the flag used to return a non-zero code if the analyzer issued a warning for a project code. The flag allows you to monitor warnings in the analyzer's report. Such behavior of warnings can be useful when you integrate the analyzer into CI/CD. The default value is false.
• ‑‑incremental (-i) is the flag used to enable the incremental analysis mode. In this mode, the analyzer checks only modified files, which speeds up the analysis process. The default value is false.
• ‑‑force-rebuild is the flag used to force the rebuild of the entire cached metamodel of a program. The metamodel contains information about the program structure and data types. Rebuilding the project metamodel can be necessary when the analyzer version is updated or if the project metamodel is corrupted. When this flag is used, the incremental analysis mode is disabled (the ‑‑incremental flag). The default value is false.
• ‑‑disable-cache is the flag used to disable caching of the program metamodel. When the cache is disabled, the project model is not cached and is rebuilt each time. This flag can be useful when identifying the causes of the analyzer errors. Disabling project metamodel caching also disables the incremental analysis (the –incremental flag). The default value is false.
• ‑‑java-path specifies the path to the java executable file that will be used to run the analyzer core. You can configure this setting for the entire system in the global.json file. If java-path is not used, PVS-Studio attempts to use the path from the PATH environment variable.
• ‑‑timeout is the timeout for analyzing a file (in minutes). It enables you to increase or decrease the maximum amount of time taken to analyze one file. You can enable this setting for the whole system in the global.json file. The default value is 10.
• ‑‑compatibility is the flag that enables the V6078 diagnostic rule that detects potential API compatibility issues between the selected Java SE versions. The V6078 diagnostic rule enables you to ensure that the JDK API you are using will not be modified or will not disappear in future versions of the JDK. The default value is false.
• ‑‑source-java is the Java SE version that your application is developed on. This setting is used by the V6078 diagnostic rule if the ‑‑compatibility setting is enabled. The minimum value is 8. The maximum value is 14.
• ‑‑target-java is the Java SE version to be checked for compatibility with the API used in your application (‑‑source-java). The V6078 diagnostic uses this setting if the ‑‑compatibility setting is enabled. The minimum value is 8. The maximum value is 14.
• ‑‑exclude-packages are packages to be excluded from the compatibility analysis (the V6078 diagnostic). The V6078 diagnostic uses this setting if the ‑‑compatibility setting is enabled. Example: ‑‑exclude-packages "package1" "package2" "package3".
• ‑‑security-related-issues highlights warnings related to potential security issues with additional markings in the SAST field in the analyzer output.
• ‑‑logging defines the logging level during analysis. When logging is enabled (any valid value other than "OFF" is set), log files for the current run are created in the .PVS-Studio/logs subdirectory relative to the project folder. These log files can help identify causes of analyzer malfunctions. Users may provide these files to help more quickly resolve issues related to incorrect analyzer behavior, such as unhandled exceptions during the analysis. The value should be one of the following strings: "OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE", "ALL". If an invalid value is set, logging is disabled ("OFF"). The default value is "OFF"—logging is disabled.

Running 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

Please 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.

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.

Updating 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.39.99802)". 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.39.99802 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