A configuration file is used to display and filter analyzer messages. The configuration file also allows you to set additional parameters for the analysis. You can use configuration files only for projects written in C, C++ or C#.
Plugins for the following IDEs support configuration files:
Utilities that support configuration files:
To use a configuration file in Visual Studio, add the file at the project or solution level. Choose the necessary project or solution in the Solution Explorer window inside Visual Studio IDE. Select the 'Add New Item...' context menu item. In the window that appears, select the 'PVS-Studio Filters File' file type.
If there is no file template, you can add a simple text file with the ".pvsconfig" extension to the project or solution.
You can add multiple configuration files for each project/solution.
Configuration files added at the project level apply to all files in a given project. Configuration files added at the solution level apply to all files of all projects in a given solution.
There is no special template for adding a configuration file for CLion.
You can add a configuration file for CLion only at the project level. To use the file in CLion, add a new file with the .pvsconfig extension to the .PVS-Studio folder using the New > File context menu.
There is no special template for adding a configuration file for Rider.
You can add a configuration file for Rider only at the project level. To use the diagnostics configuration file in Rider, add a new file with the .pvsconfig extension to the project via Solution Explorer.
When you run analysis through PVS-Studio_Cmd.exe or pvs-studio-dotnet, the configuration files from the project or solution being analyzed are automatically used. You can also specify the path to the additional .pvsconfig file using the ‑‑rulesConfig (-C) parameter:
PVS-Studio_Cmd.exe -t ProjName.sln -C \path\to\.pvsconfig
pvs-studio-dotnet -t ProjName.sln -C /path/to/.pvsconfigIn this case, the settings both from the files in the project/solution and the file passed as an argument are taken into account in the analysis.
You can specify the path to the configuration file as a command-line argument (the -c parameter):
CLMonitor.exe analyzeFromDump -d /path/to/compileDump.gz -c /path/to/.pvsconfigIf you use the CompilerCommandsAnalyzer.exe utility, you can specify the path to the .pvsconfig file via the -R parameter:
CompilerCommandsAnalyzer.exe analyze ... -R /path/to/.pvsconfigIn Standalone.exe, you can specify the path to the file when you start monitoring.
The global diagnostics configuration file is used during all project checks. There can be several global .pvsconfig configuration files and the PVS-Studio tools will use them all.
To add a global configuration file, create a file with the pvsconfig extension in the folder:
To set the settings in the configuration files use special directives that start with the '//' characters. Each directive is written on a new line.
Example:
//-V::122
//-V::123You can add comments — write the '#' character at the beginning of the line.
Example:
# I am a commentTo completely disable a certain diagnostic, use the following syntax pattern:
//-V::number'number' is the number of the diagnostic you want to turn off (for example, 3022).
Example:
//-V::3022In this case, the V3022 diagnostic warnings will be ignored.
To disable a number of diagnostics, you can list their numbers separating them by commas:
//-V::number1,number2,...,numberNExample:
//-V::3022,3080This use of this directive will completely disable V3022 and V3080 diagnostics.
To disable diagnostics of a certain group, use the following directives:
//-V::GA
//-V::X64
//-V::OP
//-V::CS
//-V::MISRA
//-V::OWASPDefinition for each of the group:
You can disable several groups of diagnostics — list them separating by commas.
For example:
//-V::GA,MISRATo turn off all diagnostics of C++ or C# analyzer use the following directives:
//-V::C++
//-V::C#If you need to turn off warnings of a certain level, use the following syntax pattern:
//-V::number1,number2,...,numberN:levelThe number 1 corresponds to warnings of 'High' level, the number 2 — to 'Medium' level warnings, the number 3 — to 'Low' level warnings.
You can filter out warnings of several levels at once. To do this, list the levels and separate them by commas.
Example:
//-V::3022,5623:1,3This directive will filter out the warnings of V3022 and V5623 diagnostics of 'High' and 'Low' levels.
The analyzer supports the ability to exclude warnings by the diagnostic number and substring contained in a message.
The syntax pattern is as follows:
//-V::number::{substring}The syntax pattern to suppress warnings by the substring:
//-V::3022::{always true}In this case, the V3022 warnings with the 'always true' substring in the message will be suppressed.
You can filter warnings by the certainty level and the substring simultaneously. The syntax pattern is the following:
//-V::number1,number2,...,numberN:level:{substring}The number 1 corresponds to warnings of 'High' level, the number 2 is the 'Medium' level warnings, and the number 3 is the 'Low' level warnings.
You can filter out warnings of several levels at once. To do this, list the levels and separate them by commas.
Example:
//-V::3022,5623:1,3:{always true}This directive will filter out the warnings of V3022 and V5623 diagnostics of 'High' and 'Low' levels with the 'always true' substring in the message.
To exclude warnings from specific groups at different levels, use the following command:
//-V::category1,category2,...,categoryN:levelYou can combine the group and level filters by separating them with a comma.
Here is the example:
//-V::GA,MISRA:1,3'High' and 'Low' level warnings that fall into the 'GA' and 'MISRA' groups will be excluded.
Note. This setting is only available for C, C++ and C# projects.
To enable a certain diagnostic, use the following syntax pattern:
//+V::number'number' is the number of the diagnostic you want to turn on (for example, 3022).
Example:
//+V::3022In this case, the V3022 diagnostic will be enabled.
To enable a number of diagnostics, you can list their numbers separating them by commas:
//+V::number1,number2,...,numberNExample:
//+V::3022,3080This use of this directive will enable V3022 and V3080 diagnostics.
Note. This setting is only available for C, C++ and C# projects.
To enable diagnostics of a certain group, use the following directives:
//+V::GA
//+V::X64
//+V::OP
//+V::CS
//+V::MISRA
//+V::OWASPYou can enable several groups of diagnostics — list them separating by commas.
For example:
//+V::GA,MISRAYou can mark warnings issued for certain string that includes the specified fragment as False Alarm. Use the following directive:
//-V:substring:numberNote 1. The substring you are looking for ('substring') must not contain spaces.
Note 2. Messages filtered in this way will still appear in the report. They will be marked as False Alarm (FA).
Example:
public string GetNull()
{
return null;
}
public void Foo()
{
string nullStr = GetNull();
Console.WriteLine(nullStr.Length);
}For this code, the analyzer will issue a warning: "V3080 Possible null dereference. Consider inspecting 'nullStr'.".
Use the following directive in .pvsconfig to add the FA mark for warnings issued on such code:
//-V:Console:3080This directive adds a False Alarm mark to all V3080 warnings issued on the code lines containing 'Console'.
You can also add the False Alarm mark to multiple diagnostic warnings at once. To do this, list their numbers separated by commas:
//-V:substring:number1,number2,...,numberExample:
//-V:str:3080,3022,3175The V3080, V3082, V3175 diagnostic messages will be marked as False Alarm if there is the 'str' substring in the code line indicated by the analyzer.
With PVS-Studio version 7.28 it is now possible to appending an additional hash code to the False Alarm mark. If the line with this hash code is changes, the warnings issued for this line will not be marked as False Alarms. This is because the hash code of the changed line differs from the hash code of the mark.
This setting helps recognize situations where a string with a False Alarm mark is modified.
To enable this feature, add the following flag to the configuration file:
//V_ENABLE_FALSE_ALARMS_WITH_HASHIn the code, the False Alarm mark with hash code looks like this:
//-V817 //-VH "3652460326"Since PVS-Studio 7.30 it is possible to suppress only those messages that have an additional hash code added to the False Alarm mark:
//V_HASH_ONLY ENABLE
//V_HASH_ONLY ENABLE_VERBOSEIf this setting is applied, the lines that have the False Alarm mark without a hash code will not be suppressed.
The ENABLE setting will result in one V018 message for the entire project being reported. If the ENABLE_VERBOSE setting is applied, such a warning will be issued for each line of code that contains the False Alarm mark without a hash code.
The setting can be disabled as follows:
//V_HASH_ONLY DISABLEThis situation may arise if the application of this setting is required only for a certain part of code.
To exclude a file or a group of files from analysis, use the directive:
//V_EXCLUDE_PATH fileMaskSeveral examples of masks:
//V_EXCLUDE_PATH C:\TheBestProject\thirdParty
//V_EXCLUDE_PATH *\UE4\Engine\*
//V_EXCLUDE_PATH *.autogen.csThe process of how the masks are specified is described in the documentation.
Starting from 7.32, the PVS-Studio_Cmd.exe utility and the plugin for Visual Studio support excluding projects from the analysis in the following way:
//V_EXCLUDE_PROJECT projMask'projMask' is the project mask.
Here is an example of using some masks:
//V_EXCLUDE_PROJECT C:\TheBestProject\thirdParty\3rdparty.vcxproj
//V_EXCLUDE_PROJECT *\TOCSharp.csproj
//V_EXCLUDE_PROJECT *\elsewhere\*.*projThe mask generation syntax is the same as the syntax used to exclude files from analysis. Only .vcxproj and .csproj projects can be excluded from analysis.
You can also exclude a project from analysis by setting the same path for the //V_EXCLUDE_PATH flag.
Before running the analysis, 'PVS-Studio_Cmd' generates the configuration of diagnostic rules from:
There may be a situation when the global configuration should not be applied during analysis of some projects or solutions. If you need to ignore global configuration files, add the following flag to the corresponding '.pvsconfig' file:
//IGNORE_GLOBAL_PVSCONFIGIf you run the analysis with the plugin interface (Visual Studio, Rider and CLion) or in the C and C++ Compiler Monitoring UI (Standalone.exe) you can specify a timeout after which the file analysis is terminated. If the analysis timeout is exceeded, the V006 warning is added to the analysis results. The warning contains information about the file that exceeded the timeout.
You can specify the file analysis timeout in .pvsconfig. For example, you can set a 10-minute (600-second) timeout with the following line:
//V_ANALYSIS_TIMEOUT 600If the timeout value specified in the .pvsconfig file is 0, the files are analyzed with no time limit.
You can limit file analysis time in certain projects/solutions/systems by specifying a timeout in .pvsconfig files of different levels:
The analyzer classifies warnings according to three certainty levels: High, Medium, and Low. Depending on the constructs used in the code, the analyzer evaluates the certainty of warnings and assigns them to the appropriate level in the report.
In some projects, it is important to find specific types of errors without considering the certainty level. However, there is also an opposite case when messages are of little use, but you don't want to turn them off completely. In such cases, you can manually set the High/Medium/Low level for diagnostics. To do so, use the following directives:
To change the certainty level, use the following directive:
//V_LEVEL_1::numberwhere 'number' is the diagnostic number.
For example, to assign the third certainty level to the V3176 diagnostic, use the following directive:
//V_LEVEL_3::3176To change the substring in the analyzer message, use the following syntax:
//+Vnnn:RENAME:{originalString:replacementString}, ...Let's consider an example of how the directive works. Suppose the code contains the number 3.1415 that triggers the V624 diagnostic. As a result, you get the message explaining that you need to replace 3.1415 with 'M_PI' from the '<math.h>' library. However, the project uses a special mathematical library that requires you to use only its mathematical constants. To make it work properly, add the directive to the configuration file.
The directive will look like this:
//+V624:RENAME:{M_PI:OUR_PI},{<math.h>:"math/MMath.h"}Then you will be informed to use the 'OUR_PI' constant from the 'math/MMath.h' header file.
You can also add a line to the message.
Here is the directive that helps you to do this:
//+Vnnn:ADD:{message}Let's look at an example. Here is the V2003 diagnostic message: "Explicit conversion from 'float/double' type to signed integer type.".
To add more information to this message, use the following directive:
//+V2003:ADD:{ Consider using boost::numeric_cast instead.}Now the analyzer will output a modified message: "Explicit conversion from 'float/double' type to signed integer type. Consider using boost::numeric_cast instead.".
If you run the analysis with the plugin for Visual Studio or in the C and C++ Compiler Monitoring UI (Standalone.exe) you can disable the synchronization of suppress files by setting Specific Analyzer Settings\DisableSynchronizationOfSuppressFiles.
You can disable synchronization using '.pvsconfig' file of the solution level. To do this, add the following flag to the corresponding configuration file:
//DISABLE_SUPPRESS_FILE_SYNCTo enable synchronization via .pvsconfig, regardless of the value of the DisableSynchronizationOfSuppressFiles setting, you must use the flag:
//ENFORCE_SUPPRESS_FILE_SYNCThis flag is only enabled at the .pvsconfig level of the solution.
Starting from version 7.24, PVS-Studio_Cmd.exe utility and the plugin for Visual Studio support the ability to specify the PVS-Studio core version for analyzing C++ projects in case several versions of PVS-Studio are installed on the computer.
For PVS-Studio_Cmd.exe to run the analysis on the required version of the PVS-Studio core, the //PVS_VERSION::Major.Minor flag should be added to the solution-level .pvsconfig file, where
Major - major version number, and Minor - minor number.
Example:
//PVS_VERSION::7.24PVS-Studio_Cmd.exe calculates the path to the core using information from the system registry which is written by the installer when installing PVS-Studio.
The latest installation of PVS-Studio is considered default. This means that if the latest PVS-Studio 7.22 was installed, all the plugins and PVS-Studio_Cmd.exe will be of the same version. Consequently, you will not be able to use the mechanism of selecting the PVS-Studio core versions. Therefore if you want to use old versions of PVS-Studio (7.23 and older), you need to install them first and only then install the latest PVS-Studio 7.24 or newer version.
For all versions older than 7.24 you need to specify in the registry the correlation of the version and the path to the installation directory of this version, so that PVS-Studio_Cmd.exe could find the path to PVS-Studio's core. The information is written into 'Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ProgramVerificationSystems\PVS-Studio\Versions'.
Starting with PVS-Studio 7.25, the PVS-Studio_Cmd.exe utility and the plugin for Visual Studio support the feature of explicitly setting the priority of configuration files on the same level. To do this, use the //CONFIG_PRIORITY::number flag, where number is the priority number.
For example:
//CONFIG_PRIORITY::1The smaller the number, the higher the priority of the configuration file. Files that do not have this flag have minimal priority. Files having the same priority are treated in alphabetical order. For example, among the files Filter1.pvsconfig, Filter2.pvsconfig, and Filter3.pvsconfig, the Filter3.pvsconfig file will be given priority.
The //CONFIG_PRIORITY flag affects only configuration files of the same level. In ascending order of priority, the configuration files are treated as follows:
If you want PVS-Studio to execute commands from the CustomBuild task before running the analysis, add the following directive to the .pvsconfig file:
//EXECUTE_CUSTOM_BUILD_COMMANDSThis directive only applies to the .pvsconfig files passed via the command line and located at the global or solution level.
Let's look into the case where the directive might be useful.
Some Visual C++ projects can generate source code at build time using commands from the CustomBuild task. Running the analysis without generating the files can lead to errors. If you only need to generate the files, a complete build is useless (since it may take a long time).
In this case, it would be useful to specify the corresponding directive for PVS-Studio so that the analyzer could first execute the file generation commands and then perform the analysis.
Sometimes the analyzer may issue a parsing error warning for a project that compiles perfectly. These errors may not be critical to the quality of the analysis. In this case, you can suppress them.
The parsing error has the following code:
Suppressing the V051 warning (the C# analyzer)
The C# analyzer issues V051 if there is at least one compilation error. To see all errors, run the command-line version of the analyzer with the "‑‑logCompilerErrors" option. The syntax for suppressing the errors looks like this:
//V_EXCLUDE_PARSING_ERROR:V051:{"ProjectName": "MyProject", "ErrorCode": "CS0012", "Message": "Some message"}
In this case, a compilation error that has the CS0012 code and the "Some message" message is suppressed for the (.csproj) MyProject project.
You do not need to combine information for suppression:
You can use masks when specifying the message, for example:
//V_EXCLUDE_PARSING_ERROR:V051:{Message: "Some*"}
Note: currently, parsing error suppression is available only for V051 (the C# analyzer).
The global Settings.xml file contains a number of options that affect the analysis result. For example, you can turn off diagnostic groups.
Use the '//V_IGNORE_GLOBAL_SETTINGS ON' flag to ignore the settings from Settings.xml during the analysis. In this case, all diagnostic groups are enabled, and no path filters are applied.
To customize analysis settings, use configuration files (.pvsconfig).
This option is available only in the configuration file of the solution level, and it affects only PVS-Studio_Cmd.exe, and plugins for Visual Studio.
You can use the '//V_SOLUTION_DIR_AS_SOURCE_TREE_ROOT' flag to enable the solution directory as the SourceTreeRoot value.
To learn more about the SourceTreeRoot setting, please consult the separate documentation.
The parameter has higher priority than UseSolutionDirAsSourceTreeRoot from the Settings.xml file.
This option is only available for the .pvsconfig level of the solution and affects only PVS-Studio_Cmd.exe and plugins for Visual Studio.
Starting with PVS-Studio 7.27, all suppressed messages are saved in sorted form. To learn more, please consult the documentation.
If you need to save old behavior and disable sorting mode, you can specify the //V_DISABLE_SUPPRESS_FILE_SORTING parameter.
You can specify specific rules for a certain PVS-Studio version.
The syntax:
//V_SECTION_BEGIN
//V_WHEN_VERSION: <CONDITION_SEQUENCE>
....
//V_SECTION_ENDEach section contains three mandatory components:
The condition syntax:
<CONDITION_SEQUENCE> ::= <CONDITION> | <CONDITION_SEQUENCE> "|" <CONDTION>
<CONDITION> ::= <SINGLE_VERSION_COMPARISON> | <RANGE_VERSIONS_COMPARISON>
<SINGLE_VERSION_COMPARISON> ::= <OP> <VERSION>
<RANGE_VERSIONS_COMPARISON> ::= "IN" <VERSION> "," <VERSION>
<OP> ::= "EQ" | "NE" | "LT" | "LE" | "GT" | "GE"
<VERSION> ::= <NUMBER> [ "." <NUMBER> ]Conditions in V_WHEN_VERSION can be combined using the '|' character (analogous to the logical OR operator). Each subexpression is evaluated individually. If at least one of them is true, the section with all the directives inside it is applied. Otherwise, it is discarded.
If you need to specify a range rather than the exact version, you can use the IN operator. Values are comma-separated. For example, all versions from 7.20 to 7.25 (inclusive) can be specified this way:
....
//V_WHEN_VERSION: in 7.20,7.25
....The supported operators in conditions, their aliases and description:
|
# |
Operator |
Alias |
Description |
|---|---|---|---|
|
1 |
EQ |
== |
Equal to |
|
2 |
NE |
!= |
Not equal to |
|
3 |
LT |
< |
Less than |
|
4 |
LE |
<= |
Less than or equal to |
|
5 |
GT |
> |
Greater than |
|
6 |
GE |
>= |
Greater than or equal to |
|
7 |
IN |
absent |
Range of values |
The text operators are case-insensitive. This condition entry will also be correct:
....
//V_WHEN_VERSION: == 7.17 | In 7.20,7.25 | GT 8
....Restrictions:
Notes:
The section example:
//V_SECTION_BEGIN
//V_WHEN_VERSION: eq 7.30 | in 7.32,7.35 | gt 8
//+V::860
//V_ASSERT_CONTRACT
//-V::1100
//V_SECTION_END