How to use the PVS-Studio extension for Qt Creator
- How to install the PVS-Studio extension
- How to work with analysis results
- How to configure the plugin
You can view the PVS-Studio reports in Qt Creator with a specialized extension. In this document, you can find instructions on how to install and configure the extension as well as main use case scenarios.
Note. As for now, you cannot run the PVS-Studio analysis from Qt Creator directly. You can analyze the code and get a PVS-Studio report using one of the following ways:
- command-line utilities PVS-Studio_Cmd.exe (C++, C# Windows), CompilerCommandsAnalyzer.exe (C++ Windows) / pvs-studio-analyzer (C++ Linux/macOS);
- JSON Compilation Database for C++ projects;
- the PVS-Studio plugins for IDEs: Visual Studio, JetBrains Rider and CLion, IntelliJ IDEA;
- the compiler monitoring system.
How to install the PVS-Studio extension
First, you need to get the right extension version. You can find it in the PVS-Studio installation directory.
- For Windows, the default path is 'C:\Program Files (x86)\PVS-Studio'.
- For Linux: '$PREFIX/lib/pvs-studio/plugins', where '$PREFIX' is the installation prefix (often it's '/usr').
Supported versions of Qt Creator
Due to restrictions of the Qt Creator, you can run there only those plugin versions that were created specifically for this IDE. As of now, the following versions are supported:
- Qt Creator 8.0.x
The 'x' character replaces any digit. That is, supported version 8.0.x means that the plugin works on versions 8.0.0, 8.0.1, and 8.0.2.
The target version of Qt Creator is specified at the end of the plugin file's name. For example: 'pvs-studio-qtcreator-plugin_8.0.x.dll'.
Installation with Qt Creator Wizard
To install the PVS-Studio extension, open Qt Creator and select 'Help' -> 'About Plugins':
Click on 'Install Plugin...':
In the installation wizard, specify the location of the plugin file as well as the installation location. Depending on the platform, the plugin file will have the '.dll' or '.so' extension. After the extension is installed, restart Qt Creator.
To install the plugin manually, copy the plugin file to the directory with plugins for Qt Creator. Depending on the platform, the file will have the '.dll' or '.so' extension. By default, Qt Creator searches for plugins in the following directories:
Manual installation (option two)
You can use this option when it's impossible to install the plugin in standard directories. When starting Qt Creator, you can specify additional directories to search for plugins. Specify these directories using the '-pluginpath' flag.
For example, you can run the IDE with the following command:
- Windows: qtcreator.exe -pluginpath "%path_to_plugin_directory%"
- Linux: qtcreator -pluginpath "$path_to_plugin_directory"
When you run Qt Creator, you may see a message: the PVS-Studio plugin cannot be loaded because the suitable dependencies cannot be found (as shown below). To fix it, check the plugin version and the Qt Creator version used. You can find the Qt Creator version by going 'Help' -> 'About Qt Creator'. The plugin version is specified in the name of its file.
The PVS-Studio plugin for Qt Creator integrates into the menu bar of the IDE and the output pane.
Integration into the menu bar
After the plugin is installed, the PVS-Studio item appears in the 'Analyze' dropdown menu. This item contains the following options:
Open/Save allows you to upload and save reports.
Recent Reports stores a list of last opened reports for quick navigation. By clicking on this menu item, you can start loading the selected file.
Help contains links to the documentation and the most important pages of the analyzer website.
Options... opens the Qt Creator settings in the PVS-Studio section.
Integration into the output pane
An additional item named 'PVS-Studio' appears in the Qt Creator output pane.
The PVS-Studio window has the following items:
1 — report control bar. The first button allows clearing the current table with warnings. The two other buttons (with arrows) allow you to navigate the table. Please note that these buttons don't navigate table rows, but positions. That is, navigating the table will open the files specified in the warnings.
2 — quick filters bar. Contains buttons for displaying additional menu and advanced filters as well as certainty level checkboxes and buttons with warning categories. When you click on the hamburger button, you'll see the following items:
- Open/Save allows you to upload/save the report.
- Show False Alarms shows/hides warnings marked as false alarms. The number in parenthesis shows the number of false alarms in the current report. When you activate it, an additional column appears in the warning table.
- Options... shows the Qt Creator's settings window with the active PVS-Studio section.
- Edit Source Tree Root... allows you to quickly change the Source Tree Root settings. When activated, this item calls a dialog window where you can choose the existing directory. Please note that this option is visible only if the report contains warnings with relative paths to files. You can read more about this setting in the additional functionality section.
3 — the output area. This area solely consists of table with warnings. Further we'll describe this item in more detail.
4 — the pane control elements. The first button allows you to expand the output area by height, the second one allows you to hide the pane.
5 — a button to display the PVS-Studio pane.
Integration into settings
Integration into settings consists of adding a new section named "PVS-Studio" into a list of existing sections.
The PVS-Studio settings section is divided into 4 subsections (one tab for each section). For more information about the purpose of each section and the settings included in them, see the "How to configure the plugin" section.
How to work with analysis results
Note: the PVS-Studio extension for Qt Creator supports reports only in the JSON format. Depending on the type of the project analyzed and the way of running the analysis, PVS-Studio can generate report in several formats. To display the report in the extension, you need to convert it into the JSON format.
To convert the report, use command-line utilities (PlogConverter.exe for Windows and plog-converter for Linux / macOS). These utilities allow not only to convert PVS-Studio reports into different formats, but also process it. For example, filter warnings. Read more about these utilities here.
Example of a command to convert the PVS-Studio report to the JSON format using PlogConverter.exe (Windows):
PlogConverter.exe path\to\report.plog -t json ^ -n PVS-Studio
Example of a command to convert the PVS-Studio report to the JSON format using plog-converter (Linux and macOS):
plog-converter path/to/report/file.json -t json \ -o PVS-Studio.json
How to upload the PVS-Studio JSON report in Qt Creator
To view the PVS-Studio report in Qt Creator, open the PVS-Studio pane, click on the hamburger button, and select 'Open/Save' -> 'Open Analysis Report...':
You can also open the report using the menu bar: 'Analyze -> PVS-Studio -> Open/Save -> Open Analysis Report...':
After you select and upload the report, you'll get the output area and the warnings displayed in a table:
How to navigate the report
The PVS-Studio result output window is designed to simplify navigation through the project code and code fragments containing potential errors. Double-click on the warning in the table to open the position (a file and a code line) to which the warning was issued.
Left-click on the table header to sort the contents by the selected column.
Right-click on the table header to open the context menu. Using this menu, you can show/hide additional columns as well as display full paths to files in the position column.
The warning table supports multiple selection. To activate it, left-click on and hold it while scrolling through the rows. You can also use keyboard shortcuts:
- 'Shift+Click 'or 'Shift+arrows' — multiple selection/cancel
- 'Ctrl+Click' – single selection/cancel
Note: almost all elements in the plugin have tooltips. To see them, hold the cursor over the item for a few seconds.
Columns in the report and their purpose
Level — the unnamed first column. It displays correspondence between the certainty level and color (importance/certainty in the descending order): red — High level, orange — Medium level, yellow — Low level.
Star — shows if the warnings is marked as favorite. Click on a cell in this column to mark the warning as favorite or remove the mark. This is helpful when you noticed an interesting warning and would like to return to it later.
ID — shows the warning's order number in a report. This is helpful when you need to sort the report in order in which warnings are received from the analyzer.
Code — shows which warnings relate to which diagnostics. Click on this cell to see the documentation on the diagnostic rule.
CWE — shows the correspondence between diagnostics and the CWE classification. Click on this cell to open the documentation with the description of this security weakness.
SAST — shows the diagnostics' compliance with various safety and security standards (SEI CERT, MISRA, AUTOSAR, etc.).
Message — the text of a warning issued by the analyzer.
Project — name of a project, the analysis of which resulted in a warning.
Position — shows the position (file name and a line number, separated by a colon), to which a warning was issued. If you need to view the full path to the file, right-click on the table header and select 'Show full path to file'. If the analyzer warning contains several positions, (...) appears at the end of it. In this case, when you click on the position column, you'll see a list with all additional positions.
FA — shows if the warning is marked as false alarm.
Note: some columns may be hidden by default. To display/hide them, right-click on the table header. In the context menu, select 'Show Columns' and then select the desired column.
When you right-click on any warning, you'll see the context menu with a list of available additional actions:
The 'Mark As' menu contains commands to quickly mark or remove the mark from the selected warnings. As for now, you can mark warnings as favorites or as false alarms. Please note that the contents of this menu change depending on the status of selected warnings.
The 'Copy to clipboard' menu allows copying information about selected warnings. Contains several sub-items:
- All — copies full information about the warning (a diagnostic number, security classifiers, a full analyzer message, a file name, and a string). Note that CWE and/or SAST ids will be included in the message only if the corresponding columns are displayed;
- Message — copies only the warning text;
- Path to file — copies the full path to file.
'Hide all %N errors' — allows to hide all warnings related to this diagnostic from the report. When you click on this item, a pop-up window appears to confirm the operation. If you confirm the operation, the analyzer messages will be filtered out instantly.
'Don't check files from' — a submenu containing parts of the path to the position's file. Use this item when you need to hide all warnings issued on files from the selected directory. When you select a value, a pop-up window appears to confirm the operation. This window also contains a tip on how to disable this filter:
The 'Analyzed source files' menu contains a list of files, analysis of which resulted in this warning. This menu is helpful when warnings were issued on header files.
How to filter a report
The PVS-Studio filtering mechanisms allow you to quickly find and display diagnostic messages separately or in groups.
All filtering mechanisms (quick and advanced filters) listed below can be combined with each other and with sorting simultaneously. For example, you can filter messages by level and diagnostic groups, exclude all messages except for those containing specified text, and then sort them by position.
The quick filters bar contains several buttons that allow you to enable/disable displaying warnings from certain diagnostic groups. When the list of active categories changes, all filters are also re-calculated.
Note: the button for the 'Fails' group is displayed only if the report contains errors related to the analyzer (Their 'Code' starts with V0..).
You can read a detailed description of the certainty levels and diagnostic groups in the documentation section "Getting acquainted with the PVS-Studio static code analyzer on Windows".
You can see advanced filters if you click on 'Quick Filters'. The status of the additional filters bar (shown/hidden) does not affect the active filters. That is, you can hide this bar and filters won't be reset.
When you activate it, you'll see an additional bar that contains an input field to filter all table columns. The bar also has a button for quick clearing all filters (Clear All).
To activate the filter, press 'Enter' after you enter the text in the input field. Please note that some filters support multiple filtering (for example, Code). When you hover the cursor over the input field, a tooltip with this remainder will appear.
How to configure the plugin
To see the settings for the PVS-Studio plugin for Qt Creator IDE, you can choose the PVS-Studio section in the general list of settings; you can also use the 'Options...' menu items of the plugin.
The plugin settings are stored in the 'qtcsettings.json' file which is located in:
- Windows: '%APPDATA%\PVS-Studio\qtcsettings.json';
- Linux: '~/.config/PVS-Studio/qtcsettings.json'.
All plugin settings are divided into 4 tabs:
- General — general plugin settings;
- Detectable Errors — configuration of active warnings;
- Don't Check Files — filtering warnings by path masks and file names;
- Keyboard Message Filtering — filtering warnings by keywords.
The 'General' tab
Display false alarms – enables/disables displaying false positive warnings in the report. If you activate this setting, a new column appears in the report table.
Save file after False Alarm mark – if active, then after a False Alarm comment is inserted, a changed file is saved.
Source Tree Root – contains a path which should be used to open positions that use relative paths. For example, the '\test\mylist.cpp' relative path is written in the warning, while Source Tree Root contains the 'C:\dev\mylib' path. If the plugin tries to go to the position from the warning, the 'C:\dev\mylib\test\mylist.cpp' file will be opened.
For a detailed description of using relative paths in the PVS-Studio report files, see here.
Help Language – specifies the preferred language of the documentation. This setting is used to open the documentation on the analyzer website.
The 'Detectable Errors' tab
This tab contains a list and a description of all analyzer warnings. In this tab, you can also enable/disable diagnostic groups or separate diagnostic rules.
In the upper part of the window, you can do a full-text search for the description of the diagnostics and their numbers. If you click on the diagnostic's code, a corresponding documentation will open. If you hover the cursor over the text, you'll see a tooltip with a full text of the diagnostic rule. When you click on 'OK' or 'Apply', a warning table is updated to match the current filters.
All diagnostics are divided into groups. You can set the following states for them:
- Disabled – a category is disabled and all its warnings will not be shown in the warning list. Also, its button will be hidden from the quick filters bar (except for the General category).
- Custom – the category is active and the items have different states.
- Show All – activates the category and all its child items.
- Hide All – deactivates the category and its child items. The category button remains on the quick filters bar.
The full list of diagnostics is available on the "PVS-Studio Messages" page.
The 'Don't Check Files' tab
This tab contains lists for filtering warnings by file names or path masks. If the name or path meets at least one mask, it will be hidden from the report.
The following wildcard characters are supported:
* – any number of any characters
? – any one character
To add an entry, click on 'Add' and enter the text in the field that appears. To remove an entry, select it and click on 'Remove'. Entries with empty fields will be deleted automatically. You can edit the existing entries by double-clicking on it or by selecting it and clicking on 'Edit'.
When you click on 'OK' or 'Apply', a warning table is updated to match the current filters.
The 'Keyword Message Filtering' tab
The tab contains a keyword editor, warnings with which will be hidden in reports. Keywords from this list are checked only by the data in the 'Message' column.
The function can be helpful if you need to hide warnings from a specific function and class — you only need to specify them here.