How to run PVS-Studio on Linux and macOS
- Installing and updating PVS-Studio
- Information about a license file
- Running the analysis
- Incremental analysis mode
- File List analysis mode
- Integration of PVS-Studio into build systems and IDEs
- Integration of PVS-Studio with continuous integration systems
- Filtering and viewing the analyzer report
- Notifying the developer teams (blame-notifier utility)
- Mass suppression of analyzer messages
- Common problems and their solutions
PVS-Studio static analyzer for C/C++ code is a console application, named pvs-studio, and several supporting utilities. For the program work it is necessary to have configured environment for a build of your project.
A new run of the analyzer is performed for every code file. The analysis results of several source code files can be added to one analyzer report or displayed in stdout.
There are three main work modes of the analyzer:
- Integration of pvs-studio call in a build system;
- Analyzer integration using modules for CMake/QMake;
- Analysis of a project without integration using the pvs-studio-analyzer utility.
Installing and updating PVS-Studio
Examples of commands to install the analyzer from the packages and repositories are given on these pages:
Information about a license file
You can request a license for acquaintance with PVS-Studio via a feedback form.
To save information about a license in file it is necessary to use the following command:
pvs-studio-analyzer credentials NAME KEY [-o LIC-FILE]
PVS-Studio.lic file will be created by default in the ~/.config/PVS-Studio/ directory. In this case it is not necessary to specify it in the analyzer run parameters, it will be caught automatically.
License key for the analyzer is a text file of UTF8 encoding.
You can check a license deadline using this command:
pvs-studio --license-info /path/to/PVS-Studio.lic
Running the analysis
Before running the analysis, you need to perform one of the following actions to get a project build model.
Important. The project must be successfully compiled and built before the analysis.
JSON Compilation Database
This page provides instructions for running the analysis based on compile_commands.json files. It is suitable for widely used build systems such as: CMake, Ninja, GNU Make, Qt Build System, Xcode.
Compilation tracing (for Linux only)
To use this method, you need to install the strace utility. The utility helps the analyzer to get the necessary information about the compilation of the project during its build.
You can build the project and track its compilation process with the help of the following command:
pvs-studio-analyzer trace -- make
Instead of the make command, you can use any command to start the project's build with all the necessary parameters, for example:
pvs-studio-analyzer trace -- make debug
As a result of tracing, the strace_out file will be generated by default.
Running the project analysis
After building the project and getting its model, you need to run the following commands:
pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic \ -o /path/to/PVS-Studio.log \ -e /path/to/exclude-path \ -j<N> plog-converter -a GA:1,2 \ -t json \ -o /path/to/Analysis_Report.json \ /path/to/PVS-Studio.log
The analyze command requires strace_out or compile_commands.json files in the current working directory. You can explicitly specify the location of these files with the help of the --file (-f) flag.
The analyzer warnings will be saved into the specified Analysis_Report.json file. You may find various ways to view and filter the report in the following documentation section "Filtering and viewing the analyzer report".
If you use cross compilers
In this case, the compilers may have special names and the analyzer will not be able to find them. To analyze such a project, you must explicitly list the names of the compilers without the paths:
pvs-studio-analyzer analyze ... --compiler COMPILER_NAME --compiler gcc --compiler g++ --compiler COMPILER_NAME plog-converter ...
Also, when you use cross compilers, the directory with the header files of the compiler will be changed. It's necessary to exclude such directories from the analysis with the help of -e flag, so that the analyzer doesn't issue warnings for these files.
pvs-studio-analyzer ... -e /path/to/exclude-path ...
There shouldn't be any issues with the cross compilers during the integration of the analyzer into the build system.
You can pass the response file to the pvs-studio-analyzer utility. Response file is a file which contains other command-line arguments.
The response file argument on the command line is indicated by the '@' character, which is followed by the path to the response file (e.g. '@/path/to/file.txt'). The arguments in the response file are separated by spaces/tabs/newlines. If you want to pass an argument that contains a whitespace, you can escape the whitespace with a backslash (\) character or put the whole argument in single ('') or double ("") quotes. You can't escape quotes inside quotes. There's no difference between single-quoted and double-quoted arguments. Note that the arguments are passed as-is, no other processing takes place like shell variable expansion, glob expansion, etc. Recursive response files are supported.
Incremental analysis mode
For the pvs-studio-analyzer utility, incremental analysis mode is available (analysis of only changed files), for this, you need to run the utility with the parameter --incremental:
pvs-studio-analyzer analyze ... --incremental ...
This mode works independently from the incremental project build. I.g. if your project is completely compiled, the first run of the incremental analysis will still analyze all files. During the next run only changed files will be analyzed.
For monitoring the changed files, the analyzer saves service information in a directory named .PVS-Studio in the launch directory. That's why for using this mode it is always necessary to run the analyzer in one and the same directory.
File List analysis mode
The pvs-studio-analyzer utility allows to analyze a project's specific files. This mode is necessary when checking commits and pull requests. To start the analysis, run the utility with the following settings: the --source-files or -S parameter, and a path to a file that contains a list of source files to be checked.
pvs-studio-analyzer analyze ... -S source_file_list ...
To learn more about file list analysis mode, read the following documentation article: "Pull request and commit analysis".
Integration of PVS-Studio into build systems and IDEs
Examples of integration in CMake, QMake, Makefile, and WAF
Test projects are available in the official PVS-Studio repository on GitHub:
- pvs-studio-cmake-examples, CMake module itself on GitHub repository
This is how the integration with CLion, QtCreator and Eclipse CDT looks like
Figure 1 shows an example of analyzer warnings viewed in CLion (more details here):
Figure 1 - PVS-Studio warnings viewed in CLion
Figure 2 demonstrates an example of analyzer warnings viewed in QtCreator:
Figure 2 - PVS-Studio warnings viewed in QtCreator
Instructions for checking CMake projects in the Qt Creator environment are located on the page "How to use PVS-Studio in Qt Creator"
Figure 3 shows an example of analyzer warnings viewed in Eclipse CDT:
Figure 3 - PVS-Studio warnings viewed in Eclipse CDT
The analyzer checks not the source files, but preprocessed files. This method allows the analyzer perform a more in-depth and qualitative analysis of the source code.
In this regard, we have several restrictions for the compilation parameters being passed. These are parameters that hinder the compiler run in the preprocessor mode, or damage the preprocessor output. A number of debugging and optimization flags, for example,-O2, -O3, -g3, -ggdb3 and others, create changes which affect the preprocessor output. Information about invalid parameters will be displayed by the analyzer when they are detected.
This fact does not presuppose any changes in the settings of project to be checked, but part of the parameters should be excluded for the analyzer to run in properly.
Configuration file *.cfg
During integration of the analyzer into the build system, you should pass it a settings file (*.cfg). You may choose any name for the configuration file, but it should be written with a "--cfg" flag.
The settings file with the name PVS-Studio.cfg, which is located in the same directory as the executable file of the analyzer, can be loaded automatically without passing through the command-line parameters.
Possible values for the settings in the configuration file:
- exclude-path (optional) specifies the directory whose files it is not necessary to check. Usually these are directories of system files or link libraries. There can be several exclude-path parameters.
- platform (required) specifies the platform. Possible variants: linux32 or linux64.
- preprocessor (required) specifies the preprocessor. Possible variants: gcc, clang, keil.
- language (required) parameter specifies the version of the C/C++ languages that the analyzer expects to see in the code of the file to be analyzed (--source-file). Possible variants: C, C++. Incorrect setting of this parameter can lead to V001 errors, because every supported language variant has certain specific keywords.
- lic-file (optional) contains the absolute path to the license file.
- analysis-mode (optional) defines the type of warnings. It is recommended that you use the value "4" (General Analysis, suitable for most users).
- output-file (optional) parameter specifies the full path to the file, where the report of the analyzer's work will be stored. If this parameter is missing in the configuration file, all messages concerning the errors found will be displayed in the console.
- sourcetree-root (optional) by default, during the generation of diagnostic messages, PVS-Studio issues absolute, full paths to the files, where PVS-Studio detected errors. Using this setting you can specify the root part of the path that the analyzer will automatically replace with a special marker. For example, the absolute path to the file /home/project/main.cpp will be replaced with a relative path |?|/main.cpp, if /home/project was specified as the root.
- source-file (required) contains the absolute path to the source file to be analyzed.
- i-file (required) contains the absolute path to the preprocessed file.
- no-noise (optional) will disable the generation of Low Certainty messages (Level 3). When working with large-scale projects, the analyzer might generate a huge number of warnings. Use this setting when it is not possible to fix all the warnings at once, so you can concentrate on fixing the most important warnings first.
An important note:
You don't need to create a new config file to check each file. Simply save the existing settings, for example, lic-file, etc.
Integration of PVS-Studio with continuous integration systems
Any of the following methods of integration of the analysis into a build system can be automated in the system Continuous Integration. This can be done in Jenkins, TeamCity and others by setting automatic analysis launch and notification of the found errors.
It is also possible to integrate with the platform of the continuous analysis of SonarQube using the plug-in PVS-Studio. The plugin is available with the analyzer in .tgz archive available to download. Setting instructions are available on this page: "Integration of PVS-Studio analysis results into SonarQube".
Filtering and viewing the analyzer report
Plog Converter utility
To convert the analyzer bug report to different formats (*.xml, *.tasks and so on) you can use the Plog Converter, which can be found open source.
Enter the following in the command line of the terminal:
plog-converter [options] <path to the file with PVS-Studio log>
All options can be specified in random order.
- -t - utility output format.
- -o - the path to the file that will be used for output. If it is missing, the output will be redirected to the standard output device.
- -s - path to the configuration file. The file is similar to the analyzer configuration file PVS-Studio.cfg. Information on the root of the project and the excluded directories (exclude-path) is taken from this file.
- -r - a path to the project directory.
- -a - set of filtered diagnostic rules. The full list: GA, 64, OP, CS, MISRA. The can be used together with specified levels, for example: "-a GA:1,2;64:1;CS".
- -d - a list of excluded diagnostics, separated by a comma: "-d V595,V730".
- -m - to enable a display of CWE ID and MISRA ID for the found warnings: " -m cwe -m misra".
- -e - use stderr instead of stdout.
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".
At this point, the available formats are:
- xml-a convenient format for further processing of the results of the analysis, which is supported supported by the plugin for SonarQube;
- csv - file stores tabular data (numbers and text) in plain text;
- errorfile is the output format of the gcc and clang;
- errorfile-verbose is an extension for the 'errorfile' output format; this extension supports displaying extra positions (if any exist) in the report for each time a diagnostic is triggered;
- tasklist - an error format that can be opened in QtCreator;
- tasklist-verbose is an extension for the 'tasklist' output format; this extension supports displaying extra positions (if any exist) in the report;
- html - html report with a short description of the analysis results. It suits best for the e-mailing of the notifications;
- fullhtml - report with sorting of the analysis results according to the different parameters and navigation along the source code;
- sarif - report generation in the SARIF format. This is an open format for exchanging data between static-analysis tools. More details here;
- sarif-vscode is an extension for the 'sarif' format; the extension contains fixes that allow for the multi-file navigation to work correctly in the Sarif Viewer Visual Studio Code extension.
The result of execution of the utility, is a file containing messages of a specified format, filtered by the rules that are set in the configuration file.
Viewing the analyzer report in QtCreator
The following is an example of a command which would be suitable for most users, for opening the report in QtCreator:
plog-converter -a GA:1,2 -t tasklist -o /path/to/project.tasks /path/to/project.log
Figure 4 demonstrates an example of a .tasks file, viewed in QtCreator:
Figure 4 - A .tasks file viewed in QtCreator
Html report view in a web browser or an email client
The analyzer report converter allows generating an Html report of two types:
1. FullHtml - full report to view the results of the analysis. You can search and sort messages by type, file, level, code and warning text. A feature of this report is the ability to navigate to the location of the error, to the source code file. The source code files themselves, which triggered the analyzer warnings, are copied in html and become a part of report. Examples of the report are shown in figures 5-6.
Figure 5 - Example of the Html main page report
Figure 6 - Warning view in code
Example of a command for receiving such a report:
plog-converter -a GA:1,2 -t fullhtml /path/to/project.log -o /path/to/report_dir
This report is convenient to send in an archive, or to provide access by the local network using any web server, for example, Lighttpd, etc.
2. Html is a lightweight report, consisting of a single .html file. It contains brief information about the found warnings and is suitable for notification by email. A report example is shown on the Figure 7.
Figure 7 - Simple Html page example
Example of a command for receiving such a report:
plog-converter -a GA:1,2 -t html /path/to/project.log -o /path/to/project.html
Viewing the analyzer report in Vim/gVim
An example of commands to open the report in gVim editor:
$ plog-converter -a GA:1,2 -t errorfile -o /path/to/project.err /path/to/project.log $ gvim /path/to/project.err :set makeprg=cat\ % :silent make :cw
The figure 8 demonstrates an example of viewing an .err file in gVim:
Figure 8 - viewing the .err file in gVim
Viewing the analyzer report in GNU Emacs
An example of commands to open the report in Emacs editor:
plog-converter -a GA:1,2 -t errorfile -o /path/to/project.err /path/to/project.log emacs M-x compile cat /path/to/project.err 2>&1
Figure 9 demonstrates an example of viewing an .err file in Emacs:
Figure 9 - viewing the .err file in Emacs
Viewing the analyzer report in LibreOffice Calc
An example of commands to convert the report in CSV format:
plog-converter -a GA:1,2 -t csv -o /path/to/project.csv /path/to/project.log
After opening the file project.csv in LibreOffice Calc, you must add the autofilter: Menu Bar --> Data --> AutoFilter. Figure 10 demonstrates an example of viewing an .csv file in LibreOffice Calc:
Figure 10 - viewing an .csv file in LibreOffice Calc
More settings can be saved into a configuration file with the following options:
- enabled-analyzers - an option similar to the -a option in the console string parameters.
- sourcetree-root - a string that specifies the path to the root of the source code of the analyzed file. If set incorrectly, the result of the utility's work will be difficult to handle.
- errors-off - globally disabled warning numbers that are enumerated with spaces.
- exclude-path - a file, the path to which contains a value from this option, will not be initialized.
- disabled-keywords- keywords. Messages, pointing to strings which contain these keywords, will be excluded from processing.
The option name is separated from the values by a '=' symbol. Each option is specified on a separate string. Comments are written on separate strings; insert # before the comment.
Adding custom output formats
To add your own output format, follow these steps:
Create your own output class, making it an heir from the IOutput class, and redefine the virtual method void write(const AnalyzerMessage& msg). Describe the message output in the correct format for this method. The fields of the AnalyzerMessage structure are defined in the analyzermessage.h file. The following actions are the same as for the existing output classes (XMLOutput, for example).
In OutputFactory::OutputFactory in m_outputs add your format by analogy with the one that is already specified there. As a variant - add it through the method OutputFactory::registerOutput.
The format will be available as the utility option -t after these actions.
Notifying the developer teams (blame-notifier utility)
The blame-notifier utility is meant for automating the process of notifying developers who have committed the code in the repository for which the PVS-Studio analyzer has issued warnings. The analyzer report is passed to the blame-notifier with specification of additional parameters; the utility finds files that triggered warnings and generates an HTML-report for each "guilty" developer. It is also possible to send a full report: it will contain all warnings related to each "guilty" developer.
The following documentation section describes the ways how to install and use the utility: "Notifying the developer teams (blame-notifier utility)".
Mass suppression of analyzer messages
Mass warnings suppression allows you to easily embed the analyzer in any project and immediately start to benefit from this, i.e. to find new bugs. This mechanism allows you to plan correcting of missed warnings in future, without distracting developers from performing their current tasks.
There are several ways of using this mechanism, depending on the integration of the analyzer.
Analysis using pvs-studio-analyzer utility
To suppress all analyzer warnings (first time and in subsequent occasions) you need to execute the command:
pvs-studio-analyzer suppress /path/to/report.log
If you want to suppress a warning for a specific file, use the --file(-f) flag:
pvs-studio-analyzer suppress -f test.c /path/to/report.log
In addition to the file itself, you can explicitly specify the line number to suppress:
pvs-studio-analyzer suppress -f test.c:22 /path/to/report.log
This entry suppresses all warnings that are located on line 22 of the 'test.c' file.
This flag can be specified repeatedly, thus suppressing warnings in several files at once.
In addition to explicit file specification, there is a mechanism for suppressing specific diagnostics:
pvs-studio-analyzer suppress -v512 /path/to/report.log
The --warning(-v) flag can also be specified repeatedly:
pvs-studio-analyzer suppress -v1040 -v512 /path/to/report.log
The above-mentioned --file and --warning flags can be combined to suppress warnings more precisely:
pvs-studio-analyzer suppress -f test.c:22 -v512 /path/to/report.log
So the above command will suppress all v512 diagnostic warnings on line 22 of the 'test.c' file.
Analysis of the project can be run as before. At the same time suppressed warnings will be filtered:
pvs-studio-analyzer analyze ... -s /path/to/suppress.json \ -o /path/to/report.log plog-converter ...
Direct integration of the analyzer in the build system
Direct integration might look as follows:
.cpp.o: $(CXX) $(CFLAGS) $(DFLAGS) $(INCLUDES) $< -o $@ $(CXX) $(CFLAGS) $< $(DFLAGS) $(INCLUDES) -E -o $@.PVS-Studio.i pvs-studio --cfg $(PVS_CFG) --source-file $< --i-file $@.PVS-Studio.i --output-file $@.PVS-Studio.log
In this mode, the analyzer cannot verify source files and filter them simultaneously. So, filtration and warnings suppression would require additional commands.
To suppress all the warnings, you must also run the command:
pvs-studio-analyzer suppress /path/to/report.log
To filter a new log, you must use the following commands:
pvs-studio-analyzer filter-suppressed /path/to/report.log plog-converter ...
File with suppressed warnings also has the default name suppress_base.json, for which you can optionally specify an arbitrary name.
Common problems and their solutions
1. The strace utility issues the following message:
strace: invalid option -- 'y'
You must update the strace program version. Analysis of a project without integrating it into a build system is a complex task, this option allows the analyzer to get important information about the compilation of a project.
2. The strace utility issues the following message:
strace: umovestr: short read (512 < 2049) @0x7ffe...: Bad address
Such errors occur in the system processes, and do not affect the project analysis.
3. The strace utility issues the following message:
No compilation units found
The analyzer could not find files for analysis. Perhaps you are using cross compilers to build the project. See the section "If you use cross compilers" in this documentation.
4. The analyzer report has strings like this:
The analyzer saves the report in the intermediate format. To view this report, you must convert it to a readable format using a plog-converter utility, which is installed together with the analyzer.
5. The analyzer issues the following error:
Incorrect parameter syntax: The ... parameter does not support multiple instances.
One of the parameters of the analyzer is set incorrectly several times.
This can happen if part of the analyzer parameters are specified in the configuration file, and part of them were passed through the command line parameters. At the same time, some parameter was accidentally specified several times.
If you use pvs-studio-analyzer, then almost all the parameters are detected automatically, this is why it can work without a configuration file. Duplication of such parameters can also cause this error.
6. The analyzer issues the warning:
V001 A code fragment from 'path/to/file' cannot be analyzed.
If the analyzer is unable to parse some code fragment, it skips it and issues the V001 warning. Such a situation doesn't influence the analysis of other files, but if this code is in the header file, then the number of such warnings can be very high. Send us a preprocessed file (.i) for the code fragment, causing this issue, so that we can add support for it.
If you have any questions or problems with running the analyzer, feel free to contact us.