# How to run PVS\-Studio on Linux and macOS

## Introduction

PVS\-Studio static analyzer for C and C\+\+ code is delivered as the `pvs-studio` console application along with several supporting utilities\. There are also integrations into VS Code, Qt Creator, and CLion via plugins, providing a user\-friendly interface for analyzing projects\. To run the analyzer, your project should have a properly configured build environment\.

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 supports three basic operating modes:

1. Project analysis using the [pvs\-studio\-analyzer](https://pvs-studio.com/en/docs/manual/6615/) utility without any integrations\.
1. Integrating the analyzer using the [CMake modules](https://pvs-studio.com/en/docs/manual/6591/)\.
1. Integrating the `pvs-studio` core directly into the [build system](https://pvs-studio.com/en/docs/manual/0006/)\.

## Installing and updating PVS\-Studio

See these web pages for command examples for installing the analyzer from packages and repositories:

* [Installing and updating PVS\-Studio on Linux](https://pvs-studio.com/en/docs/manual/0039/)
* [Installing and updating PVS\-Studio on macOS](https://pvs-studio.com/en/docs/manual/0042/)

## License file information

To get started with PVS\-Studio, fill out the [feedback form](https://pvs-studio.com/en/pvs-studio/try-free/) to request a license\. You can find more information on how to enter the license on Linux and macOS [here](https://pvs-studio.com/en/docs/manual/0046/#UnixLikeCLI)\.

## Running the analysis

Before running the analysis, create a build model of your project\.

**Note**\. The project must be successfully compiled\. If you are using WSL for analysis, make sure that your project is located in the Linux file system\. Otherwise, the analysis will be much slower\. [Read more here](https://pvs-studio.com/en/docs/manual/0023/#ID5DE080EF2F)\.

### JSON Compilation Database

One way to analyze projects is to generate the `compile_commands.json` file in advance\.

This approach works well with many popular build systems, including:

* CMake
* Ninja
* GNU Make
* Qt Build System
* Xcode\.

To learn more about running the analysis based on the `compile_commands.json` files, refer to this [documentation](https://pvs-studio.com/en/docs/manual/6557/)\.

**Note\.** This approach facilitates the analysis, as it does not require fully tracing compiler invocations\. \(The approach is described below\)\.

### Compilation tracing \(for Linux only\)

If generating the `compile_commands.json` file is not possible, use the compiler call trace mode, installing the `strace` utility\. The utility allows the analyzer to get the required compilation information during the project build\.

**Note\.** Before using the mode, the project should be cleaned\. This ensures the analyzer captures complete information about all compiled files\.

To build the project and track the compilation process, use the following command:

```cpp
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:

```cpp
pvs-studio-analyzer trace -- make debug
```

By default, tracing generates a file named `strace_out`\. For more details, refer to the [documentation](https://pvs-studio.com/en/docs/manual/6615/#trace)\.

#### Possible difficulties

In some Docker images `ptrace` is disabled by default, which prevents the `pvs-studio-analyzer` utility from working in tracing mode\.

Below are the methods to enable `ptrace` inside a container\. Please note that full compatibility of PVS\-Studio in such configurations is not guaranteed\. If you encounter any issues, feel free to [contact PVS\-Studio support](https://pvs-studio.com/en/about-feedback/)\.

First method makes the container use the PID namespace of the host:

1. Enable `ptrace` on the host system;
1. Run the container with the `--pid=host` option: `docker run -it --pid=host <image_name> bin/bash`\. Replace `<image_name>` with the name of your image\.

Important: when using `--pid=host`, the container shares the PID namespace with the host, which reduces isolation and affects security of the system\.

Second method injects a correctly configured `ptrace_scope` file into the image during build:

1. Make sure `ptrace` is enabled on the host;
1. Copy the file containing the value `0` to the Dockerfile directory: `bash cp /proc/sys/kernel/yama/ptrace_scope ./ptrace_scope`;
1. In your `Dockerfile`, add the copy instruction: `COPY ptrace_scope /proc/sys/kernel/yama/ptrace_scope`;
1. Rebuild the image: `bash docker build -t <new_image_name>`\.

Please follow [this documentation](https://pvs-studio.com/en/docs/manual/0047/) to run PVS\-Studio in Docker\.

### Running the project analysis

Once you have obtained the compilation tracing file \(`strace_out`\) or JSON Compilation Database \(`compile_commands.json`\), run the following command to start the analysis:

```cpp
pvs-studio-analyzer analyze -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`_ _mode requires either the `strace_out` or `compile_commands.json` file in the current working directory\. You can explicitly specify the location of files using the `--file` \(or `-f`\)_ _flag\.

The analyzer warnings are saved to the specified `Analysis_Report.json` file\. For other ways to view and filter reports, refer to the documentation: "[Filtering and viewing the analyzer report](https://pvs-studio.com/en/docs/manual/0036/#ID14E9A2B2CD)"\.

### If you use cross compilers

The compilers may have specific names, so the analyzer may not detect them\. To analyze projects, explicitly list the names of the compilers without paths:

```cpp
pvs-studio-analyzer analyze ... --compiler COMPILER_NAME \
  --compiler gcc --compiler g++ --compiler COMPILER_NAME

plog-converter ...
```

Cross\-compilers are usually distributed along with their own implementations of the standard library, which are located in non\-standard paths\. The analyzer tries to detect them automatically; however, if this does not happen and the report contains warnings for these files, exclude such directories from analysis using the `-e` flag\.

```cpp
pvs-studio-analyzer ... -e /path/to/exclude-path ...
```

If `pvs-studio-analyzer` misidentifies the cross\-compiler type and runs the preprocessor incorrectly, you can explicitly specify the preprocessor via the following flag:

```cpp
pvs-studio-analyzer analyze ... --compiler CustomCompiler=gcc
```

After that, `pvs-studio-analyzer` will run `CustomCompiler` with the `gcc` preprocessing flags\. For more details, refer to the [documentation](https://pvs-studio.com/en/docs/manual/6615/#flags)\.

**Note**\. Integrating the analyzer into the build system should not cause any issues with cross\-compilers\.

### Response files

You can pass a response file to the `pvs-studio-analyzer` utility\. This file contains command\-line arguments\.

The response file argument on the command line is prefixed by the `@` character, which is followed by the path to the response file \(e\.g\. `@/path/to/file.rsp`\)\. The file can include command\-line arguments separated by spaces, tabs, or newlines\. 

To pass an argument that contains a whitespace, you can: 

* escape the whitespace with a backslash \(`\`\) character;
* wrap the argument in single \(`''`\) or double \(`""`\) quotes\.

**Note**:

* Do not escape quotes inside quotes\. 
* There is no difference between single\-quoted and double\-quoted arguments\. 
* The arguments are passed exactly as written, no additional processing is performed \(e\.g\. no shell variable or `glob` expansion\)\.
* Recursive response files are also supported\.

## Incremental analysis mode

The `pvs-studio-analyzer` utility supports the incremental analysis mode that analyzes only modified files\. To enable this mode, run the utility with the `–incremental`_ _parameter:

```cpp
pvs-studio-analyzer analyze ... --incremental ...
```

This mode works independently from the incremental project build\. If your project is fully compiled, the startup of the incremental analysis will analyze all files\. On subsequent runs, only changed files will be analyzed\.

To track changes, the analyzer saves service data within the `.PVS-Studio` directory in the startup directory\. It is important to always run the analyzer in the same directory when using the mode\.

## File list analysis mode

In the `pvs-studio-analyzer` utility, the file list analysis mode analyzes the specific project files, which is useful for checking commits and pull requests\. To enable this mode, run the utility with the `--source-files` or `-S` parameter and specify the path to a file containing the list of source files to analyze\.

```cpp
pvs-studio-analyzer analyze ... -S source_file_list ...
```

To learn more about the file list analysis mode, refer to the [documentation](https://pvs-studio.com/en/docs/manual/0055/)\.

## PVS\-Studio integration into build systems and IDEs

### Examples of integration into CMake, QMake, Makefile, and WAF

Test projects are available in the official PVS\-Studio repository on [GitHub](https://github.com/viva64/):

* [pvs\-studio\-cmake\-examples](https://github.com/viva64/pvs-studio-cmake-examples), the CMake module on the [GitHub repository](https://github.com/viva64/pvs-studio-cmake-module)
* [pvs\-studio\-qmake\-examples](https://github.com/viva64/pvs-studio-qmake-examples)
* [pvs\-studio\-makefile\-examples](https://github.com/viva64/pvs-studio-makefile-examples)
* [pvs\-studio\-waf\-examples](https://github.com/viva64/pvs-studio-waf-examples)

### Integration with CLion and Qt Creator

_Figure 1_ shows analyzer warnings viewed in CLion \(more details [here](https://pvs-studio.com/en/docs/manual/0052/)\):

![PVS-Studio_Linux/image2.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image2.png)

Figure 1 — PVS\-Studio warnings viewed in CLion

_Figure 2_ shows analyzer warnings viewed in Qt Creator: 

![PVS-Studio_Linux/image4.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image4.png)

Figure 2 — PVS\-Studio warnings viewed in Qt Creator

For more details about analyzing CMake projects in the Qt Creator environment, refer to the [documentation](https://pvs-studio.com/en/docs/manual/6455/)\.

The **PVS\-Studio for QtCreator** extension is available\. You can find more information about it [here](https://pvs-studio.com/en/docs/manual/6648/)\.

### Preprocessor parameters

The analyzer checks the [preprocessed](https://pvs-studio.com/en/blog/terms/0076/) files instead of the source files\. This approach enables a deeper and more accurate code analysis\.

Several restrictions that may interfere with the preprocessor or alter its output are applied to the passed compilation parameters\. For example, some debugging and optimization flags—`-O2`, `-O3`, `-g3`, `-ggdb3`, etc\.—can affect the preprocessor output\. As a result, if any invalid parameters are detected, the analyzer will display a warning\.

While it is not necessary to change the settings of the checked project, some parameters should be excluded to ensure that the analyzer runs correctly\.

### Configuration file \*\.cfg

When integrating the analyzer into a build system, pass the configuration file \(`*.cfg`\)\. You may choose any name for the configuration file, but it should be passed with the `--cfg` flag\.

Here are the available parameters for the settings in the configuration file:

* `exclude-path` \(optional\) specifies directories whose files can be excluded from analysis, for example, system file directories or third\-party libraries\. There can be several `exclude-path` parameters\. 
* `analysis-paths` \(optional\) defines the analysis behavior for the specified paths\. The available modes:
  * `skip-analysis` specifies directories whose files can be excluded from the analysis, for example, directories of system files or third\-party libraries;
  * `skip-settings` ignores the settings located in the source files and `.pvsconfig` files located at the specified path;
  * `skip` ignores the settings from the source files and `.pvsconfig` files at the specified path\. Warnings for source files matching the specified path or mask will also be ignored\.
* `platform` \(required\) specifies the target platform\. Possible options are `linux32` or `linux64`\. 
* `preprocessor`_ _\(required\)_ _specifies the target preprocessor\. Possible options are `gcc`, `clang`, or `keil`\.
* `language` \(required\) specifies the C/C\+\+ language that the analyzer expects in the file provided via `--source-file`\. Possible options are `C` and `C++`\. Setting this parameter incorrectly may lead to the [V001](https://pvs-studio.com/en/docs/warnings/v001/) errors because every supported language option has certain specific keywords\. 
* `lic-file` \(optional\) contains the absolute path to the license file\.
* `analysis-mode` _\(_optional\) defines the warning type\. It is recommended to use the `4` value \(General Analysis, commonly recommended for most users\)\.
* `output-file` \(optional\) specifies the full path to the file with the location of the analyzer report\. If this parameter is missing in the configuration file, all warnings will be displayed in the console\.
* `sourcetree-root` \(optional\) specifies the root path that the analyzer will automatically replace with a special marker\. By default, when generating warnings, PVS\-Studio includes full and absolute paths to files where the analyzer has detected errors\. For example, the absolute path to the `/home/project/main.cpp` file replaces the `|?|/main.cpp` relative path if `/home/project` is 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\) disables the generation of low\-certainty messages \(Level 3\)\. In large\-scale projects, the analyzer may issue a high volume of warnings\. Use this setting to prioritize the most important ones first, especially when addressing all warnings at once is not feasible\. 


> \*\*Note\\\.\*\* It is not necessary to create a new configuration file to check each file\\\. You can save permanent settings into it\\\. For example, \`lic\-file\`\\\.



## PVS\-Studio integration into CI systems

The following approaches to integrating analysis into build systems can be automated in [CI environments](https://pvs-studio.com/en/docs/manual/0005/) \(for example, Jenkins, TeamCity, etc\.\) by setting automatic analysis startup and notification for the detected errors\. 

It is also possible to integrate the tool with the [SonarQube](https://www.sonarqube.org/) continuous analysis platform using the plug\-in PVS\-Studio\. The plugin is provided with the analyzer in the `.tgz` archive available to download\. For more details on this plugin, refer to this [documentation](https://pvs-studio.com/en/docs/manual/0037/)\.

You can convert PVS\-Studio analysis results into a specific format for uploading to DevSecOps platforms like DefectDojo, SonarQube, and CodeChecker\. To learn more how to integrate analysis results, see the [documentation](https://pvs-studio.com/en/docs/manual/6686/)\.

## 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 [open\-source](https://github.com/viva64/plog-converter) utility, Plog Converter\. Learn more about how it works in the [documentation](https://pvs-studio.com/en/docs/manual/0038/)\.

### Viewing the analyzer report in Qt Creator

Use the following command to open the report in Qt Creator \(recommended for most users\):

```cpp
plog-converter -a GA:1,2 -t tasklist \
               -o /path/to/project.tasks \
               /path/to/project.log
```

_Figure 3_ illustrates an example of the `.tasks` file viewed in Qt Creator: 

![PVS-Studio_Linux/image6.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image6.png)

Figure 3 — The \.tasks file viewed in Qt Creator 

### Viewing an HTML report in a web browser or an email client

The analyzer report converter can generate two types of HTML reports:

1\. `FullHtml` is a full report for viewing the analysis results\. It enables developers to search and sort warnings by type, file, level, code, and warning message\. Users can navigate this report to find error locations in the source code file\. The source code files that triggered the analyzer warnings are copied to HTML and become a part of the report\. The examples of the report are shown in _Figures 4–5_\.

![PVS-Studio_Linux/image8.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image8.png)

Figure 4 — An example of the Html main page report 

![PVS-Studio_Linux/image9.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image9.png)

Figure 5 — A warning viewed in code

The example command to generate such a report:

```cpp
plog-converter -a GA:1,2 -t fullhtml \
               -o /path/to/report_dir \
               /path/to/project.log
```

 This report can be conveniently shared as an archive or accessed over a local network using any web server, for example, [Lighttpd](https://www.lighttpd.net/), etc\.

2\. `Html` is a simplified report, consisting of a single `.html` file\. It contains brief information about the detected warnings and is suitable for notification by email\. The report example is shown in _Figure 6_\.

![PVS-Studio_Linux/image11.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image11.png)

Figure 6 — A simple HTML page example 

The example of the command for receiving such a report:

```cpp
plog-converter -a GA:1,2 -t html \
               -o /path/to/project.html \
               /path/to/project.log
```

###  Viewing the analyzer report in Vim and gVim

The command examples to open the report in the **gVim** editor: 

```cpp
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
```

_Figure 7_ shows an example of viewing the `.err` file in gVim:

![PVS-Studio_Linux/image12.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image12.png)

Figure 7 — Viewing the \.err file in gVim

### Viewing the analyzer report in GNU Emacs

The command examples to open the report in the **Emacs** editor: 

```cpp
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 8_ shows an example of viewing the `.err` file in Emacs: 

![PVS-Studio_Linux/image13.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image13.png)

Figure 8 — Viewing the \.err file in Emacs

### Viewing the analyzer report in LibreOffice Calc

The command examples to convert the report to the `CSV` format:

```cpp
plog-converter -a GA:1,2 \
               -t csv \
               -o /path/to/project.csv \
               /path/to/project.log
```

After opening the `project.csv` file in LibreOffice Calc, add **Menu Bar \> Data \> AutoFilter**\. _Figure 9_ shows an example of viewing the `.csv` file in LibreOffice Calc: 

![PVS-Studio_Linux/image14.png](https://import.viva64.com/docx/blog/PVS-Studio_Linux/image14.png)

Figure 9 — Viewing the \.csv file in LibreOffice Calc

## Notifying the developer teams \(blame\-notifier utility\)

The blame\-notifier utility automates the process of notifying developers whose code triggered warnings from PVS\-Studio when committed to a repository\. It works as follows:

1. The analyzer report is passed to the `blame-notifier` along with additional parameters\. 
1. The utility identifies files with warnings and generates the HTML reports grouped by the authors of the changes\.
1. HTML reports are sent via the specified SMTP server to all authors listed in a special file\.

It also supports sending a full report containing all warnings, sorted by author\.

For more details on how to install and use the utility, refer to the following documentation: "[Notifying the developer teams \(blame\-notifier utility\)](https://pvs-studio.com/en/docs/manual/0050/)\."

## Mass suppression of analyzer messages

Mass warning suppression streamlines the analyzer integration into any project and starts detecting new bugs right away\. This mechanism enables developers to schedule fixing of missed warnings for later without distracting developers from their current tasks\.

There are several ways to use this mechanism, depending on how the analyzer is integrated\. Learn more about how to use the warning suppression mechanism in `pvs-studio-analyzer` in the [documentation](https://pvs-studio.com/en/docs/manual/6615/#suppress)\.

### Direct analyzer integration into a build system

Direct integration into the build system may look as follows:

```cpp
.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 analyze source files and filter them simultaneously\. Warning filtration and suppression would require additional commands\.

To suppress all the warnings, use the command:

```cpp
pvs-studio-analyzer suppress /path/to/report.log
```

To filter a new log, use the commands:

```cpp
pvs-studio-analyzer filter-suppressed /path/to/report.log
plog-converter ...
```

The file with suppressed warnings has the `suppress_file.suppress.json` default name\. However, you can specify a custom name if needed\.

## Common issues and their solutions

1\. The `strace` utility issues the following message:

```cpp
strace: invalid option -- 'y'
```

Make sure the `strace` program is updated to the minimal required version 4\.7\. It is a complex task to analyze a project without integrating it into a build system\. This utility helps the analyzer get important compilation\-related information\.

2\. The `strace` utility issues the following message:

```cpp
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 `pvs-studio-analyzer` utility issues the following message:

```cpp
No compilation units found
```

The analyzer could not find files for the analysis\. You may be using cross\-compilers to build your project\. To learn more, please see the [documentation](https://pvs-studio.com/en/docs/manual/0036/#ID35219BF409)\. 

Another possible scenario is when trace mode is run on a built project\. This causes the resulting `strace_out` file to be empty\. In this case, clean the project after building it and run the compilation trace again\.

4\. The analyzer report may contain the following strings:

`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, convert it to the readable format using the `plog-converter` utility, which is installed with the analyzer\.

5\. The analyzer issues the following error:

```cpp
Incorrect parameter syntax:
The ... parameter does not support multiple instances.
```

One of the analyzer parameters is set incorrectly several times\.

This can happen if a part of the analyzer parameters is specified in the configuration file, and another part is passed via the command line parameters\. At the same time, a parameter has been accidentally specified several times\. 

If you use `pvs-studio-analyzer`, most parameters are detected automatically, so the utility can run without a configuration file\. Duplication of such parameters can also cause this error\.

6\. The analyzer issues the warning:

```cpp
V001 A code fragment from 'path/to/file' cannot be analyzed.
```

If the analyzer is unable to parse any code fragment, it skips it and issues the [V001](https://pvs-studio.com/en/docs/warnings/v001/) warning\. This does not affect the analysis of other files, but if this code is located in a header file, the number of such warnings may be significant\.

To help us improve the analyzer, please send the corresponding preprocessed `*.PVS-Studio.i` and configured `*.PVS-Studio.cfg` files that includes the problematic code fragment via the [feedback form](https://pvs-studio.com/en/about-feedback/)\.