How to run PVS-Studio on Linux

Introduction

PVS-Studio for Linux is a static code analysis console application for C/C++. To work with this program you should have the GCC or Clang compiler installed, the PVS-Studio.lic license file and the config file PVS-Studio.cfg. 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.

The analyzer has two main modes in the Linux environment:

  • checking source code files (*.cpp, *.c and so on.);
  • checking the preprocessed files (* .i).

Installing and updating PVS-Studio

Examples of commands to install the analyzer from the packages and repositories are given on this page.

Supported versions of GCC and Clang

Starting with the compiler version having the preprocessing support (flag - E), you can use the PVS-Studio static code analyzer to check your files.

By default the preprocessor is taken from the CC/CXX environment variables. If they aren't set, then the program uses gcc and g++, or clang and clang++, available through the PATH environment variable.

Quick run

The best way to use the analyzer is to integrate it into your build system, namely near the compiler call. However, if you want to run the analyzer for a quick test on a small project, use the pvs-studio-analyzer utility.

Important. The project should be successfully compiled and built before analysis.

CMake-project

To check the CMake-project we use the JSON Compilation Database format. To get the file compile_commands.json necessary for the analyzer, you should add one flag to the CMake call:

$ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=On <src-tree-root>

Cmake supports the generation of a JSON Compilation Database for Unix Makefiles.

The analysis starts with the following commands:

$ pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic
  -o /path/to/project.log -e /path/to/exclude-path -j<N>
$ plog-converter -a GA:1,2 -t tasklist
  -o /path/to/project.tasks /path/to/project.log

It is important to understand that all files to be analyzed should be compiled. If your project actively uses code generation, then this project should be built before analysis, otherwise there may be errors during preprocessing.

CMake/Ninja-project

To check the Ninja-project we use the JSON Compilation Database format. To get the necessary file compile_commands.json for the analyzer, you must execute the following commands:

$ cmake -GNinja <src-tree-root>
$ ninja -t compdb

The analysis is run with the help of following commands:

$ pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic
  -o /path/to/project.log -e /path/to/exclude-path -j<N>
$ plog-converter -a GA:1,2 -t tasklist
  -o /path/to/project.tasks /path/to/project.log

Any project

This utility requires the strace utility.

This can be built with the help of the command:

$ pvs-studio-analyzer trace -- make

You can use any other build command with all the necessary parameters instead of make, for example:

$ pvs-studio-analyzer trace -- make debug -j2

After you build your project, you should execute the commands:

$ pvs-studio-analyzer analyze -l /path/to/PVS-Studio.lic
  -o /path/to/project.log -e /path/to/exclude-path -j<N>
$ plog-converter -a GA:1,2 -t tasklist
  -o /path/to/project.tasks /path/to/project.log

Analyzer warnings will be saved into the specified project.tasks file. You may see various ways to view and filter the report file in the section "Filtering and viewing the analyzer report" within this document.

If your project isn't CMake or you have problems with the strace utility, you may try generating the file compile_commands.json with the help of the Bear utility. This file will help the analyzer to check a project successfully only in cases where the environment variables don't influence the file compilation.

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 trace -- ...
$ 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.

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 downloaded 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 or clang.
  • 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 (required) 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.
  • cl-params (optional) should contain original parameters of the source file compilation. Illegal parameters for the analyzer's duties are given in the documentation section "Preprocessor parameters"
  • source-file (required) contains the absolute path to the source file to be analyzed.
  • skip-cl-exe (optional) shows the analyzer that the preprocessing stage can be skipped, and the analysis can be started.
  • i-file (optional) contains the absolute path to the preprocessed file.

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. Modifiable parameters can be passed to the analyzer directly, like this for example:

$ pvs-studio --cfg PVS-Studio.cfg --source-file
/home/user/Documents/src/source.cpp --cl-params -c -Wall
-std=c++11 /home/user/Documents/src/source.cpp

Preprocessor parameters

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. For example, the "-o" parameter should not be passed to --cl-params, because the analyzer redirects the preprocessor output to the text file (preprocessed), instead of the binary object file. 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.

Integration of PVS-Studio into a build system

Setting up PVS-Studio for the source file analysis

To check the source file in cases where there is no preprocessed file, it is necessary to create a config file as follows:

exclude-path = /usr/include/
platform = linux64
preprocessor = gcc
analysis-mode=4
language = C++
lic-file = /home/user/Documents/PVS-Studio/PVS-Studio.lic
output-file = /home/user/Documents/src/project.log
cl-params = -c -Wall -std=c++11 /home/user/Documents/src/source.cpp
source-file = /home/user/Documents/src/source.cpp

Setting up PVS-Studio to analyze a preprocessed file

If you have already got the preprocessed file, you can start checking it right after editing the configuration file as follows:

exclude-path = /usr/include/
skip-cl-exe = yes
platform = linux64
preprocessor = gcc
analysis-mode=4
language = C++
lic-file = /home/user/Documents/PVS-Studio/PVS-Studio.lic
output-file = /home/user/Documents/src/project.log
source-file = /home/user/Documents/src/source.cpp
i-file = /home/user/Documents/src/source.i

Integration into Makefile/Makefile.am

The call of the executable file of the analyzer should be performed in the same location as the compiler call. The compiler launch line should be fully duplicated during the call of the analyzer with the flag --cl-params, except the output parameters, for example -o:

.cpp.o:
  $(CXX) $(CFLAGS) $(DFLAGS) $(INCLUDES) $< -o $@
  pvs-studio --cfg $(CFG_PATH) --source-file $< --language C++
     --cl-params $(CFLAGS) $(DFLAGS) $(INCLUDES) $<

Important notes:

  • The path to the source file that is present in the original compilation line must be duplicated with the flag --source-file;
  • The analyzer settings should not be duplicated in the command line parameters and the configuration file;
  • Checking of several files with one analyzer call is not supported.

Integration into CMake/CLion/QtCreator

You can use the PVS-Studio.cmake module for projects that use cmake. Suggested content of CMakeLists.txt, using this module.

include(PVS-Studio.cmake)
pvs_studio_add_target(TARGET analyze ALL
                      FORMAT tasklist
                      PREPROCESSOR gcc
                      LOG "/path/to/report.tasks"
                      ANALYZE main_target subtarget:path/to/subtarget
                      LICENSE "/path/to/PVS-Studio.lic"
                      CXX_FLAGS ${PREPROCESSOR_ADDITIONAL_FLAGS}
                      C_FLAGS ${PREPROCESSOR_ADDITIONAL_FLAGS}
                      CONFIG "/path/to/PVS-Studio.cfg")

All settings are optional. The ALL parameter indicates that the analysis starts when you build the project (Build All).

This method supports incremental build: the resulting log will contain errors from the latest versions of the files.

You can add an additional command that will convert the log to the required format with the help of the plog-converter utility:

include(PVS-Studio.cmake)
pvs_studio_add_target(TARGET analyze
                      OUTPUT FORMAT errorfile
                      ANALYZE target
                      LOG target.plog
                      LICENSE "/path/to/PVS-Studio.lic")

Figure 1 shows an example of analyzer warnings viewed in CLion:

Figure 1 - PVS-Studio warnings viewed in CLion

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

Figure 2 - PVS-Studio warnings viewed in QtCreator

Integration into QMake

You can use the PVS-Studio.pri file for qmake-projects. It works in a similar way to the CMake-module described above.

pvs_studio.target = pvs
pvs_studio.output = true
pvs_studio.license = /path/to/PVS-Studio.lic
pvs_studio.cxxflags = -std=c++14
pvs_studio.sources = $${SOURCES}
include(PVS-Studio.pri)

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.

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.

Usage

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.

Available options:

  • -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. 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 space: "-dV595, V730".
  • -e - use stderr instead of stdout.

At this point, the available formats are:

  • xml;
  • csv - file stores tabular data (numbers and text) in plain text;
  • errorfile is the output format of the gcc and clang;
  • tasklist - an error format that can be opened in QtCreator.

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 3 demonstrates an example of a .tasks file, viewed in QtCreator:

Figure 3 - A .tasks file viewed in QtCreator

Figure 3 - A .tasks file viewed in QtCreator

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 4 demonstrates an example of viewing an .err file in gVim:

Figure 4-viewing the .err file in gVim

Figure 4-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 5 demonstrates an example of viewing an .err file in Emacs:

Figure 5 - viewing the .err file in Emacs

Figure 5 - 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 6 demonstrates an example of viewing an .csv file in LibreOffice Calc:

Figure 6-viewing an .csv file in LibreOffice Calc

Figure 6-viewing an .csv file in LibreOffice Calc

Configuration file

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.

Compilation from the source code and set up

To compile the utility, you'll need g++ 5.4 or higher, and CMake. No other additional libraries are required.

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ...
make -j8
sudo make install

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:

r-vUVbw<6y|D3 h22y|D3xJGy|D3pzp(=a'(ah9f(ah9fJ}*wJ}*}x(->'2h_u(ah

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.

Conclusion

If you have any questions or problems with running the analyzer, feel free to contact us.


Do you make errors in the code?

Check your code
with PVS-Studio

Static code analysis
for C, C++ and C#

goto PVS-Studio;