Home
>
Documentation
>
Direct use of Java analyzer from comman…


Direct use of Java analyzer from command line

The PVS-Studio Java analyzer has two main components: the core performing the analysis and the plugins for integrating the analyzer into build systems (Maven, 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.33.85174 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) — 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) — the definition of the classpath (*.jar/*.class files, 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 — 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) — 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) — the information on the Java analyzer core arguments outputs to the console.
  • ‑‑user-name — the user name.
  • ‑‑license-key — the license key.
  • ‑‑license-path — the path to the license file. Note: if ‑‑user-name and ‑‑license-key are empty, the analyzer tries to retrieve licensing information from the file: %APPDATA%/PVS-Studio/Settings.xml (on Windows) or ~/.config/PVS-Studio/PVS-Studio.lic (on macOS and Linux);
  • --activate-license — the flag for saving licensing information specified in the ‑‑user-name and ‑‑license-key arguments to the file by the default path: %APPDATA%/PVS-Studio/Settings.xml (on Windows) or ~/.config/PVS-Studio/PVS-Studio.lic (on macOS and Linux). 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 — the path to the analyzer report which contains warnings (*. json).
  • ‑‑dst-convert — 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) — 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) — 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. Please 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) — 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 — 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 — the list of enabled groups of warnings. Available groups: GA (general analysis diagnostics), OWASP (OWASP ASVS compliant diagnostics). The ‑‑enabled-warnings, ‑‑disabled-warnings, and ‑‑additional-warnings settings have a higher priority than this setting. If a diagnostics group is disabled (or enabled), you can use the settings listed above to enable (or disable) individual diagnostics. When listing multiple groups, use whitespace as a separator. The default value is GA; Example: ‑‑analysis-mode GA OWASP.
  • ‑‑enabled-warnings — the list of enabled diagnostic rules. During the analysis, the analyzer uses only the diagnostics listed in this list. If the value is absent, then all diagnostics 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 — the list of disabled diagnostics. The diagnostics listed in the list are disabled during the analysis. If there are no diagnostics in the list, then 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 — the list of diagnostic rules to be included in analysis, which are enabled by default. If a diagnostic 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 diagnostic group 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 — 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 — 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 — 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 — 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 — 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) — 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 — 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 — 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.
  • ‑‑timeout — 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 — the flag that enables the V6078 diagnostic rule that detects potential API compatibility issues between the selected Java SE versions. The V6078 diagnostic 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 — 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 — 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 — 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".

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 same Java language version as the JDK is used. The java file from the JDK is used to start the Java analyzer core. If you want to change the Java language version to be used in the analysis, use the java file from the JDK for that version to run the Java analyzer core (pvs-studio.jar).

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 that 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 the 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:

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 the 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.33.85174)". This message contains the latest version of the Java analyzer core.

Also, 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.33.85174 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.