Jun 10 2025

Cross-platform analysis of C and C++ projects in PVS-Studio

Jun 10 2025

Introduction

PVS-Studio supports cross-platform analysis of C and C++ projects regardless of the used build system. Such projects can be checked using a special utility that has different names depending on the target platform: pvs-studio-analyzer on Linux and macOS, and CompilerCommandsAnalyzer.exe on Windows. All examples of the analyzer run are based on the pvs-studio-analyzer executable file.

For more details about checking Visual Studio projects, refer to the following documentation:

On Windows, you can also use the compiler monitoring server.

Note. The pvs-studio-analyzer and CompilerCommandsAnalyzer.exe utilities are similar cross-platform application with minor differences. This document describes platform-dependent features of these utilities. All pvs-studio-analyzer run examples provided in this documentation are cross-platform unless explicitly stated otherwise in the description.

How to activate a license

To enable the analyzer, activate the license using one of the ways described in the documentation.

If you do not have the license, you can request it on our website.

How to prepare the project for the analysis

To analyze the project, the pvs-studio-analyzer utility must receive the compilation run parameters for each translation unit. These parameters can be obtained from JSON Compilation Database (compile_commands.json) or a build trace file.

Note. The project must be successfully built to be analyzed.

Using the compilation database (Windows, Linux, and macOS)

Many build systems (CMake, Ninja, etc.) enable generating the compile_commands.json file. For build systems that do not allow obtaining compile_commands.json directly, there are various utilities—like Bear, Text Toolkit, intercept-build, etc.—that allow you to generate it.

The process of JSON Compilation Database generation and analysis is described here.

Creating a compilation trace file (Linux only)

If you cannot generate compile_commands.json for your project, you can use the compilation trace mode. It works only on Linux and uses the strace utility to intercept compiler calls.

To monitor compilation on Windows, use CLMonitor.

Note. To trace the compilation, install strace version 4.7 or higher and enable the PTRACE system call. Before starting the compilation trace, the project should be cleaned. This ensures that the analyzer gathers the most complete information about the project structure. In many distributions, PTRACE is enabled by default, but there are exceptions. For example, to enable PTRACE, change the value of the kernel.yama.ptrace_scope parameter to 1 in the /etc/sysctl.d/10-ptrace.conf file.

By default, the trace result is saved to the strace_out file located in the current directory. You can specify an arbitrary path to the result file using the -o flag.

Before starting the trace, make sure that there are no artifacts of the previous build in the build directory. Otherwise, the build system may omit compiler calls for unmodified files if it uses the incremental build mode.

To start the compilation trace, run the build_command command to build the project:

pvs-studio-analyzer trace [-o <FILE>] -- build_command

The example:

pvs-studio-analyzer trace -- cmake build .

How to analyze a project

After generating the JSON Compilation Database or the compilation trace file, you can finally start analyzing the project.

Run the following command to start the analysis:

pvs-studio-analyzer analyze [-o /path/to/PVS-Studio.log] \ [-e /path/to/exclude-path]... \ [-j <N>]

Below is a description of all command-line flags.

General flag description

‑‑cfg [FILE] (or -c [FILE]) specifies the configuration file (*.cfg) that contains parameters of the analyzer startup, such as exclude-path, lic-file, and others. The next section describes configuration file settings. You can include general parameters for checking various projects in this configuration file.
‑‑lic-file [FILE] (or -l [FILE]) specifies a path to the license file. There is a corresponding setting for this parameter in the configuration file.
‑‑threads [N] (or -j [N]) specifies the number of threads to which the analysis will be parallelized.
‑‑output-file [FILE] (or -o [FILE]) specifies a path to the file where the analysis report will be saved. By default, if this flag is not set, the report will be saved to the PVS-Studio.log file in the current directory. You can specify this parameter in *.cfg.
‑‑exclude-path [DIR] (-e [DIR]) specifies a path to files that should be excluded from the analysis. You can specify an absolute or relative path. You can also use templates (glob) to exclude a set of files. To exclude several directories from the analysis, add each directory via the flag or write them in the configuration file.
‑‑analysis-paths [MODE=PATH|GLOB] defines the analysis behavior on the specified paths. The available modes:
- skip-analysis specifies the directory where files do not need to be checked. These are usually directories of system files or included libraries. The mode is behaved as the ‑‑exclude-path flag.
- skip-settings ignores settings located in source files and .pvsconfig at the specified path.
- isolate-settings sets the directory for which the settings should be isolated. When this mode is enabled, the configuration files of diagnostic rules (.pvsconfig) from parent directories will not be applied to translation units in the specified directory and its subdirectories. Both absolute and relative paths are supported. Relative paths are expanded via the current directory. The glob patterns cannot be used in this mode.
- skip ignores the settings located in the source files and .pvsconfig files and filters warnings for source code by the specified path or mask.
‑‑analysis-mode [MODE] (-a [MODE]) specifies the group of warnings that will be enabled during the analysis.
- 64: Diagnostic rules for 64-bit errors.
- GA: General analysis diagnostic rules.
- OP: Diagnostic rules for micro-optimizations.
- CS: Diagnostic rules for specific user requests.
- MISRA: MISRA compliance diagnostic rules for code analysis.
- AUTOSAR: AUTOSAR compliance diagnostic rules for code analysis.
- OWASP: OWASP compliance diagnostic rules for code analysis.

You can read more about MISRA, AUTOSAR, and OWASP here.

To specify several groups of warnings, separate them with ; or +.

For example:

GA;OP;64

GA+OP+64

You can omit single quotes if you use + as a separator. When using ;, wrap the expression in single quotes or escape each semicolon because the ; character is usually used as a command separator in shells.

By default, the analyzer uses the GA group.

You can also specify this parameter in the configuration file (*.cfg).

‑‑sourcetree-root [DIR] (or -r [DIR]) specifies the root part of the path ([DIR]) to be replaced with a special marker in the report. By default, when generating warnings, PVS-Studio outputs absolute file paths with warnings. Next, the report with relative paths can be used to view the analysis results in an environment with a different location of the source files.
‑‑project-root specifies the path to the project root directory. Both absolute and relative paths are supported. Relative paths are expanded via the current directory. If the flag is not specified, the current directory will be considered the project root.
‑‑apply-pvs-configs enables the mode for searching and applying configuration files (.pvsconfig) for each translation unit. The configuration files are searched for in the translation unit directory and in all parent directories up to the project root directory. To use this mode, specify the project root directory using the ‑‑project-root flag.
‑‑disableLicenseExpirationCheck returns the exit code to 0 if the license expires soon. Use this flag when integrating the analyzer into CI systems like Travis CI, CircleCI, and GitLab CI/CD or when automating the commit and pull request verification. Also, use this flag if your license is about to expire (less than 30 days left).

Note. If you renew the license and forget to remove this flag, pvs-studio-analyzer replaces the possible exit code 0 with 6.

‑‑file [FILE] (-f [FILE]) specifies a path to the compilation trace file or JSON Compilation Database. By default, if this flag is not specified, PVS-Studio searches for the strace_out or compile_commands.json file in the current directory. Note that PVS-Studio first searches for compile_commands.json and then strace_out. If you use JSON Compilation DB, make sure to specify the .json file extension, otherwise this file will be treated as a trace file. Specify the flag if the compilation trace file or JSON Compilation Database is saved to a non-default path.
‑‑quiet hides the analysis progress.
‑‑preprocessor [NAME] specifies the preprocessor type that the analyzer will expect when parsing preprocessed files (*.PVS-Studio.i). Possible values:
- visualcpp
- clang
- gcc
- bcc
- bcc_clang64
- iar
- keil5
- keil5_gnu
- c6000.

During the preprocessing, macros are expanded, and the file contents, included via #include, are substituted into the resulting preprocessed file. To help compilers and various utilities correctly navigate such a file, the preprocessor inserts special #line directives that indicate the origin file of the inserted content.

The PVS-Studio requires the preprocessor type to correctly process the #line directives specific for different compilers.

By default, if this flag is not specified, the analyzer attempts to automatically detect the preprocessor type. However, the analyzer may incorrectly determine it. In this case, the preprocessor can be explicitly specified. The parameter can be specified in the configuration file (*.cfg).

‑‑platform [NAME] specifies the target platform for which the project is being compiled.

This flag expects the following parameters:

Windows: win32, x64, Itanium, and arm;
Linux: linux32, linux64, Itanium, and arm;
macOS: macOS;
Embedded: pic8 and tms (Texas instruments).

The analyzer requires information about the platform to correctly detect the data model.

By default, if this flag is not specified, PVS-Studio attempts to automatically detect the platform based on the compiler startup parameters.

This parameter can also be specified in the configuration file.

‑‑ignore-ccache enables analysis of all source files regardless of the ccache state. If the project uses a wrapper over the compiler call (ccache) to speed up the build, the analysis does not detect the compilation files. This flag omits the ccache call and processes the compiler command wrapped in it.
‑‑incremental (or -i) enables incremental analysis of the project.
‑‑source-files [FILE] (or -S [FILE]) specifies a list of source files for the file list checking mode. It contains the path to each source file, separated by a new line. Absolute and relative paths are allowed. Relative paths should be specified relative to the directory from which you plan to run the analysis. This approach is convenient to use when you analyze commits and pull/merge requests.
‑‑regenerate-depend-info [OPTION] updates information about compilation dependencies for each source file. Information about dependencies is stored in the depend_info.json file. This flag supports the following modes:
- run-analysis updates the dependency information and runs the analysis;
- skip-analysis updates information about dependencies without running the analysis.

The analyzer needs the dependencies file for correct file list checking or incremental analysis. For more details, refer to the documentation.

‑‑suppress-file [FILE] (or -s [FILE]) specifies the path to the file with suppressed warnings. These warnings are ignored when generating the analyzer report. The default suppress file name is suppress_file.suppress.json. You can read more about it in the documentation.
‑‑analyze-specified-system-paths enables the analysis of files located in custom system directories specified through compilation flags such as isystem, isysroot, system_include_dir, and others.
‑‑compiler [COMPILER_NAME[=COMPILER_TYPE]] (or -C [COMPILER_NAME[=COMPILER_TYPE]]) specifies the compiler name and type. Use the flag when PVS-Studio cannot detect compiler calls when analyzing from the trace file or starts the compiler with incorrect preprocessing flags because it sets the wrong compiler type.
COMPILER_NAME filters compiler commands when you parse a trace file (strace_out).
COMPILER_TYPE specifies the compiler type. This allows the analyzer to correctly run the file preprocessing command. The possible values:
- gcc
- clang
- keil5
- keil5gnu
- keil6
- tiarmcgt
- cl
- clangcl
- gccarm
- iararm_v7_orolder
- iararm
- qcc
- xc8.

If the compiler type is not specified, the analyzer attempts to detect it based on the name or version information. If detection fails, the analyzer will treat it as GCC (on Linux and macOS) or cl (on Windows).

For example, the following command instructs the analyzer to treat the unknown compiler named CustomCompiler as GCC in the strace_out file:

pvs-studio-analyzer analyzer -f /path/to/strace_out \ -C CustomCompiler=gcc

‑‑env [VAR=VALUE] (or -E [VAR=VALUE]) specifies an environment variable to be preprocessed with.
‑‑rules-config [FILE] (or -R [FILE]) specifies the configuration file of diagnostic rules *.pvsconfig. See the documentation for details on configuring diagnostic rules.
‑‑intermodular enables the intermodular analysis mode that performs a deeper code analysis but increases the analysis time.
‑‑security-related-issues highlights warnings related to potential security issues with additional markups in the SAST field in the analyzer output.
‑‑misra-c-version sets the version of the MISRA C standard. Supported versions of the MISRA C standard: 2012 and 2023.

How to use the configuration file

The configuration file enables you to set general parameters for running the analyzer.

You can create a separate configuration file for the project and put specific parameters to this file.

The parameters are written as key=value. You can use the # symbol to comment lines.

The possible values in the configuration file:

exclude-path specifies an absolute or relative path to files or directories that should be excluded from the analysis. The relative path is expanded relative to the directory containing the configuration file. You can also use the command shell templates (glob) to specify the path.
analysis-paths defines the analysis behavior for the specified paths. The available modes:
- skip-analysis specifies directories whose files should be excluded from the analysis. These are usually directories of system files or linked libraries.
- skip-settings ignores the settings located in the source files and .pvsconfig files by the specified path.
- isolate-settings sets the directory for which the settings should be isolated. When this mode is enabled, .pvsconfig from parent directories will not be applied to translation units in the specified directory and its subdirectories. Both absolute and relative paths are supported. Relative paths are expanded via the current directory. The glob patterns are forbidden for this mode.
- skip ignores the settings located in the source and .pvsconfig files and filters warnings for source code by the specified path or mask.
timeout specifies the time (in seconds) after which the analysis of a translation unit will terminate. By default, the time limit for one file is 600 seconds (10 minutes). Use 0 to disable the time limit, but note that this may cause the analysis to hang.
platform specifies the platform. The possible options:
- win32
- x64
- Itanium
- linux32
- linux64
- macOS
- pic8
- tms.
preprocessor specifies the preprocessor. The possible options:
- visualcpp
- clang
- gcc
- bcc
- bcc_clang64
- iar
- keil5
- keil5_gnu
- c6000.
lic-file specifies the absolute or relative path to the license file. The path is set relative to the directory containing the configuration file.
analysis-mode specifies the warning type to be issued, which is a bit mask. Using the bitwise OR, you can specify several groups of diagnostic rules that will be used in the analysis. The possible values:
- 0: Full analysis.
- 1: 64-bit diagnostic rules.
- 4: General analysis diagnostic rules (recommended and used by default).
- 8: Diagnostic rules for micro-optimizations.
- 16: Diagnostic rules for customer specific requests.
- 32: MISRA compliance diagnostic rules for code analysis.
- 64: AUTOSAR compliance diagnostic rules for code analysis.
- 128: OWASP compliance diagnostic rules for code analysis.
output-file specifies the absolute or relative path to the file where the analysis report will be saved. By default, the report will be written to the PVS-Studio.log file. Relative paths will be expanded relative to the directory from which you want to run the analysis. When the analysis is parallelized, all PVS-Studio core processes write warnings in a single file. So, this file remains locked until the last process writes information to it.
funsigned-char specifies the signedness of the char type. If it is true—the analyzer treats char as an unsigned type, otherwise it treats it as signed.
rules-config specifies the path to the diagnostic rule configuration file (*.pvsconfig). The path is expanded relative to the directory containing configuration file.
no-noise enables you to exclude all warnings of the certainty level 3. If it is set to true, warnings of this level will not appear in the analyzer report. By default, it is false.
errors-off specifies the list of disabled diagnostic rules. The list items should be separated by a space or comma: V1024 V591 or V1024, V591. Diagnostic rules in this list will be excluded from the analysis.
analyzer-errors specifies the list of enable diagnostic rules. The list items should be separated by a space or comma: V1024 V591 or V1024, V591. Only the diagnostic rules in this list will be used during the analysis.

Note. The list of disabled diagnostic rules specified in errors-off has a higher priority than the list of enabled ones.

For example, specify the basic parameters for running PVS-Studio and the project analysis in the configuration file. To do so, pass the *.cfg file to the analyzer.

The MyProject.cfg file:

lic-file=~/.config/PVS-Studio/PVS-Studio.lic exclude-path=*/tests/* exclude-path=*/lib/* exclude-path=*/third-party/* platform=linux64 preprocessor=clang analysis-mode=4

Then, start the analysis (assuming that there is strace_out or compile_commands.json in the current directory):

pvs-studio-analyzer analyze --cfg ./MyProject.cfg \ -o ~/MyProject/MyProject.PVS-Studio.log \ ....

Using the configuration file facilitates the analyzer integration with CI/CD systems.

Baselining analysis results and filtering reports according to suppression rules

PVS-Studio analyzer has the message suppression mechanism that can be used in the following scenarios:

When you first integrate the analyzer into a project and PVS-Studio issues a lot of warnings for the code. You can suppress these warnings and return to them when you have time. In this case, PVS-Studio will issue warnings only for new code during regular checks.
When you want to suppress the analyzer's false positives without modifying source code files.

The pvs-studio-analyzer enables you to suppress analyzer messages and filter a report by excluding suppressed messages.

How to baseline messages

To baseline messages, the analyzer creates a special file (by default, it is named suppress_file.suppress.json). This file contains analyzer warnings that should be ignored.

The general syntax for running the baselining mode is as follows:

pvs-studio-analyzer suppress [-a <TYPES>] [-f <FILE...>] \ [-v <NUMBER...>] [-o <FILE>] [log]

[log] is a path to the report created by the analyzer. By default, the analyzer searches for the PVS-Studio.log file in the current directory.
‑‑analyzer [TYPES] (or -a [TYPES]) enables you to specify which groups and levels of warnings will be moved to the suppression file. This parameter takes a string of the Diagnostic group: Diagnostic level [, Diagnostic level]* form. Diagnostic group defines a specific group. Possible groups: GA, 64,OP, CS, MISRA, AUTOSAR, or OWASP. Diagnostic level specifies the level of certainty (possible levels: 1, 2, or 3). You can combine various groups and levels via the ; or + character. For example, the GA:1;OP:1 string indicates the analyzer to suppress only diagnostic rules with the first level of certainty from the general analysis and micro-optimization groups. By default, the analyzer filters warnings by all groups and levels.
‑‑file [FILE...] (or -f [FILE...]) enables suppression of all warnings for a specific file:

pvs-studio-analyzer suppress -f test.cpp \ -f test2.cpp \ /path/to/PVS-Studio.log

or for a specific line in a specific file:

pvs-studio-analyzer suppress -f test.cpp:15 \ /path/to/PVS=Studio.log

‑‑warning [NUMBER...] (or -v [NUMBER...]) specifies the number of diagnostic rules, warnings of which should be suppressed:

pvs-studio-analyzer suppress -v512 /path/to/PVS-Studio.log

‑‑output [FILE] (or -o[FILE]) specifies a path and a name for the suppress file. By default, PVS-Studio writes all information about suppressed warnings to the suppress_file.suppress.json file in the current directory.

Note. You can combine the ‑‑file, ‑‑warning, and ‑‑analyzer flags. For example, the following command will suppress all V1040 warnings on the line 12:

pvs-studio-analyzer suppress -f test.cpp:12 \ -v 1040 \ /path/to/PVS-Studio.log

The following command suppresses all GA diagnostic rules of the level 3 for the specified file:

pvs-studio-analyzer suppress -f test.cpp \ -a 'GA:3' \ /path/to/PVS-Studio.log

How to filter a report by suppress files

You can filter out warnings that have already been added to the suppress file from the analyzer report. To do this, run the following command:

pvs-studio-analyzer filter-suppressed [-o <FILE>] [-s <FILE>] [log]

‑‑output [FILE] (or -o [FILE]) is a file name to write the filtered report. By default, if the flag is not set, pvs-studio-analyzer will overwrite the existing report file.
‑‑suppress-file [FILE] (or -s [FILE]) is a message suppression file. By default, pvs-studio-analyzer searches for the suppress_file.suppress.json file in the startup directory.
[log] specifies the path to the report earlier created by the analyzer.

The pvs-studio-analyzer utility always searches for the suppress file in the analysis mode to create a filtered report. If the file has a non-standard path, you can specify it via the -s flag:

pvs-studio-analyzer analyze -s /path/to/suppress_file.suppress.json ....

Exit codes

The utility can return the following values:

0: Analysis completed successfully.
1: Various internal errors. For example, file preprocessing failed or an error occurred during trace file parsing. Usually, a crash with this code is followed by an error description in stdout.
2: The license expires in less than a month.
3: An internal error occurred during the analysis of some files.
5:The license has expired.
6: The utility was started with the ‑‑disableLicenseExpirationCheck flag and received a new license valid for more than 30 days.
7: No compilation units were accepted for the analysis. For example, all files have been excluded from the analysis by user settings or by marking all source code directories as system header paths.
8: No compiler invocations were detected. For example, an unknown compiler is used, or the generated project structure file (strace_out or a compile commands database) is corrupted.

In the trace mode, by default, the analyzer returns the same code it received from the executed program. If you want the analyzer to ignore the real exit code and always return 0, you can use the -i or -- ignoreTraceReturnCode flag.