Managing XML Analyzer Report (.plog file)

• Preliminary filtering of analysis results
• Converting the analysis results
• PlogConverter tool exit codes
• Notifying the developer team

In this section we describe working in the Windows environment. Working in the Linux environment is described in the section "How to run PVS-Studio on Linux".

The analysis results that PVS-Studio generates as its output after it has finished checking a project (either from the Visual Studio plugin or in command-line batch mode) are typically presented as an XML log file (".plog"). Using direct integration of C++ analyzer to the build system to perform the analysis produces an unparsed 'raw' log file. You can view these files in the PVS-Studio plugin for Visual Studio or in the C and C++ Compiler Monitoring UI (Standalone.exe). These formats, however, are not convenient for viewing directly in a text editor, sending them via email, and so on. PVS-Studio package comes with a number of utilities that allow you to manage such log files in a number of ways.

Preliminary filtering of analysis results

The analysis results can be filtered even before a start of the analysis by using the No Noise setting. When working on a large code base, the analyzer inevitably generates a large number of warning messages. Besides, it is often impossible to fix all the warnings straight out. Therefore, to concentrate on fixing the most important warnings first, the analysis can be made less "noisy" by using this option. It allows completely disabling the generation of Low Certainty (level 3) warnings. After restarting the analysis, the messages from this level will disappear from the analyzer's output.

When circumstances will allow it, and all of the more important messages are fixed, the 'No Noise' mode can be switched off – all of the messages that disappeared before will be available again.

To enable this setting use the Specific Analyzer Settings page.

Converting the analysis results

When opening log file in a text editor, a user has to deal with XML markup or 'raw' unreadable log from the analyzer. To convert the analysis results into a more convenient format, use PlogConverter utility, which comes with PVS-Studio and can be found in the PVS-Studio installation directory ("C:\Program Files (x86)\PVS-Studio" by default). You can also download the source code of the utility.

Use the "'--help" option to display the basic information about the utility:

PlogConverter.exe --help

Let's take a closer look at the utility's parameters:

• --renderTypes (or -t): defines the possible formats into which the log files can be converted. The supported formats are Html, FullHtml, Totals, Txt, Tasks, Csv, Plog, and TeamCity. When not defined explicitly, the log file will be converted into all of these formats.
  • Html: converts the log file into an html file (convenient for automatic delivery to addressees on your mailing list).
  • FullHtml: converts the log file and the source files in html-files (you can view the analyzer report in browser with sorting by warnings and navigation along the code).
  • Txt: converts the log file into a text file.
  • Csv: converts the log file into a comma-separated file (convenient for viewing in Microsoft Excel, for example).
  • Totals: outputs the statistics on the issued warnings across the types (GA, OP, 64, CS, MISRA) and certainty levels. Detailed description of the levels of certainty and sets of diagnostic rules is given in the documentation section "Getting Acquainted with the PVS-Studio Static Code Analyzer".
  • Tasks: converts the log file into format that can be opened in QtCreator.
  • Plog: can be used to merges several plog xml files into one or transforms a raw unparsed log to parsed xml one.
  • TeamCity: converts the log file into a file for viewing in the TeamCity CI.

You can combine different format options by separating them with "," (no spaces), for example:

PlogConverter.exe D:\Projct\results.plog --renderTypes=Html,Csv,Totals

or

PlogConverter.exe D:\Projct\results.plog -t Html,Csv,Totals

• --analyzer (or -a): filters the warnings by a specified mask. The mask format:

MessageType:MessageLevels

"MessageType" can be set to one of the following types: GA, OP, 64, CS, MISRA, Fail

"MessageLevels" can be set to values from 1 to 3

You can combine different masks by separating the options with ";" (no spaces), for example (written in one line):

PlogConverter.exe D:\Projct\results.plog --renderTypes=Html,Csv,Totals
--analyzer=GA:1,2;64:1

or

PlogConverter.exe D:\Projct\results.plog -t Html,Csv,Totals -a GA:1,2;64:1

The command format reflects the following logic: convert ".plog" into Html, Csv, and Totals formats, keeping only the general-analysis warnings (GA) of the 1-st and 2-nd levels and 64-bit warnings (64) of the 1-st level.

• --excludedCodes (or -d): creates a list of warnings (separated with ",") that shouldn't be included into the resulting log file. For example, you don't want the V101, V102, and V200 warnings to be included (written in one line):

PlogConverter.exe D:\Projct\results.plog --renderTypes=Html,Csv,Totals
  --excludedCodes=V101,V102,V200

or

PlogConverter.exe D:\Projct\results.plog -t Html,Csv,Totals -d V101,V102,V200

• --settings (or -s): defines the path to the PVS-Studio configuration file. PlogConverter will read your custom settings for the warnings you want turned off specified in the configuration file. This parameter in fact extends the list of the warnings that you want to be excluded defined by the "--excludedCodes" parameter.
• --srcRoot (or -r): specifies the replacer of the "SourceTreeRoot" marker. If the path to the project's root directory was replaced with the "SourceTreeRoot" marker (|?|), this parameter becomes obligatory (otherwise the utility won't be able to find the project files).
• --outputDir (or -o): defines the directory where the converted log files will be created. If not specified, the files will be created in the same directory where "PlogConverter.exe" is located.
• --outputNameTemplate (or -n): specifies the filename template without extension. All the converted log files will have the same name but different extensions (".txt", ".html", ".csv", ".tasks" or ".plog" depending on the "--renderTypes" parameter).
• --errorCodeMapping (or -m): to enable a display of CWE ID and MISRA ID for the found warnings: " -m cwe,misra".
• --indicate-warnings (or -w): sets the PlogConverter utility's exit code to '2' if after log filtration the filtered output file (files) still contains warnings.

PlogConverter tool exit codes

The PlogConverter utility defines several non-zero exit codes, which do not necessarily indicate some issue with the operation of the tool itself, i.e. even when the tool returns something other when zero it does not always mean that the tool has 'crashed'. Here's the description of all possible exit codes, that PlogConverter can return.

• '0' - conversion finished successfully;
• '1' - errors were encountered during generation of one of the output files;
• '2' - output contains non-suppressed warnings after filtration. This exit code will be generated only when using converter with "--indicate-warnings" (-w) flag;
• '3' - general (nonspecific) error in the converter's operation, a possible handled exception. Usually, this means an error inside the PlogConverter;
• '4' - some of the command line arguments passed to the tool were incorrect or one of the files, passed as an argument, hadn't been found, or doesn't exist;

Notifying the developer team

Once you have the converted log files, you can send them to other people involved in the development (team leaders, development manager, and so on). This process can be automated by including the analysis step into scheduled "night" builds, where the log file will be converted into the required format and sent to the specified addressees.

Here is an example. Once you have a "fresh" analysis report converted into an HTML file, run SendEmail utility. We are interested in the following basic parameters:

• -f : message sender;
• -t : message recipient. You can specify more than one recipient;
• -s : SMTP server;
• -u : message subject;
• -o username="" : username for authorization;
• -o password="" : password for authorization;
• -o message-charset=utf-8 : specifies the UTF-8 character set;
• -o message-file="PVS-Studio_report.html" : HTML file to be sent to the addressees.

You can also inform the developers by using the BlameNotifier utility, which comes with the PVS-Studio package. The following documentation section describes the ways how to use the utility: "Notifying the developer teams (blame-notifier utility)".