Getting started with Klocwork Desktop plug-in for Visual Studio
Getting started with Klocwork Desktop plug-in for Visual Studio
The Klocwork Desktop plug-in for Visual Studio (called the Visual Studio extension) helps you detect and fix issues before check-in. The Visual Studio extension supports C/C++, C# and mixed projects and solutions, but certain features are not supported for C#.
The plug-in is equipped with several popular C/C++ refactorings, such as renaming and inlining functions, that can be performed within your IDE.
You can also customize project settings, issue filters and analysis settings to your own preferences. For more information about these features, see the topics below.
Visual Studio did not load one or more extensions that were using deprecated APIsSelect Allow synchronous autoload and restart Visual Studio. The plug-in will now work as expected and this warning will disappear. You may receive additional warning messages, however these should be ignored. For more information, see our Limitations for the Visual Studio plug-in.
Connect to a project on the Klocwork Server
You get the most from desktop analysis when you connect a local project to a project on the Klocwork Server. The local project is analyzed quickly while incorporating Klocwork knowledge bases generated on the server where additional source files were analyzed (for example, shared libraries). Connecting to a server project also allows you to share issue status information with the integration build analysis and among team members. You can also run a standalone desktop analysis, but the analysis only derives knowledge from the local project's source files, and is not recommended.
You perform this step only once for each project.
- Right-click a solution in the Solution Explorer and select Klocwork Solution Properties.
- In the Klocwork Project list, select the server project you want to connect to and click OK.
For a mixed solution, you connect to two server projects--one on the C/C++ Projects tab and one on the C# Projects tab.
C/C++ code: By default, the Klocwork Visual Studio extension runs whenever you save a file. If you prefer, you can use on-the-fly analysis instead so that Klocwork detects issues when you open files and as you type.
C# code: For pure C# or mixed C/C++ and C# solutions, right-click the solution and select Analyze Solution. Or, right-click a project and select Analyze Selection. A full solution or project analysis detects both C/C++ and C# issues.
When Klocwork detects issues in a file, you see issue markers on the left and right margins of the editor. The left markers (chevrons) scroll with the text. When Klocwork detects more than one issue on the same line, the left gutter markers display only the highest-priority issue.
|Left margin icon||Right margin icon||Severity|
|Critical, Error (server issue)|
|Warning, Review (server issue)|
|Ignored (server issue)|
A few notes about the types of issues the Visual Studio extension displays
By default, the Visual Studio extension identifies and displays desktop, system, and server issues. You can change settings to configure which issues show.
Desktop issues are issues detected by the Visual Studio extension. In connected desktop projects, the Visual Studio extension identifies two types of desktop issues: system issues and local only issues. For example, in the image above:
- The NPD.FUNC.MUST issue highlighted in green is a system issue. This is indicated by the word System after the line number in parentheses: (Line 130, System). A system issue is an issue that Klocwork identified two ways: Klocwork found the issue locally by using desktop analysis, and Klocwork found the issue in an integration build on the Klocwork Server.
- The HA.OPTIMIZE issues highlighted in blue are also issues detected by desktop analysis. These two issues do not have the word "System" following the line number in parentheses. This means the issues that have only been found locally, and have not been found in an integration build on the Klocwork Server.
Show local issues only
In the Klocwork Issues window, click the Show local issues only icon to filter the issues list so that it only shows issues that have been found locally on the desktop and not by an integration build on the Klocwork Server.
Server issues are issues that Klocwork has detected in an integration build on the Klocwork Server, but that Klocwork has not detected by using local desktop analysis. This can sometimes occur because of the highly optimized nature of desktop analysis. In the image above, the CWARN.MEM.NONPOD issues highlighted in red are server issues, as indicated by the icon in the left margin of the issue list.
If you modify the source code to fix a server issue, it won't disappear from the issues list until the next integration build runs. Similarly, if you modify the source code to fix a system issue, it won't be detected by desktop analysis and will become a server issue that won't disappear from the issues list until the next integration build runs.
If you're working in standalone desktop mode (that is, not connected mode), all of the issues you see are classed as desktop issues. You will never see any server issues, because you aren't connected to an integration project on the Klocwork Server.
Disable loading server issues
- Open your version of Visual Studio and go to Klocwork > Options.
- Click the Analysis tab.
- In the Server issues section, clear the Load server issues check box.
Review and investigate
- In the Klocwork Issues window, double-click an issue in the list to view it in source code.
- Use Traceback information to investigate the issue. Key statements that contribute to issues are marked with red rectangles and include a description of the problem. Note: Traceback information is embedded within the source viewer and will appear next to the appropriate issue. You can hide it by pressing ESC.
- Get help by right-clicking an issue and selecting View Checker Documentation from the Manage <checker name> Checker menu.
Changing an issue's status to show how it should be handled
For a real defect, fix the issue in your code. While working in Visual Studio, the Klocwork plug-in handles issues as follows:
- For C/C++ files, the detected issue disappears as soon as you finish typing the correction.
- For C# files, run the analysis on the project or solution again. If the defect disappears from the list, it's fixed.
The exception to this behavior is if you are fixing a server issue. Server issues remain in the issues list until the next integration build runs.
For your remaining issues, you can set different issue statuses (called citing) that cover several scenarios. Using statuses such as Not a Problem, Ignore, or Defer is a handy way to suppress issues in your results that you don't care about (often in third-party libraries).
You can change the status for one issue at a time for selected issues, or for an entire file. You need the Change Issue Status permission to change issue status. For connected projects, status updates are synchronized to the server. Your local project is also updated with changes made by other developers.
- Right-click an issue in the issue window or the red or yellow chevron icon in the left gutter, click Cite issue and select the appropriate issue state from the list of choices.
- Type a comment in the dialog box that appears to provide additional information. Tip: Use Ctrl + S to save changes and close the dialog. Press ESC to close the dialog without saving.
- Click and the issue disappears from the list.
If you prefer to simply ignore an issue without specifying a more specific status, right-click the issue and select Ignore Issue. If you want to restore an ignored issue, right-click the issue(s) you want to restore and select Recover Issue.
Showing ignored issues
Default filtering options hide all issues in statuses other than Analyze and Fix, so once you change an issue's status to something other than Analyze or Fix, you won't see it again. You can adjust your filter settings to show ignored issues: click the icon and select an ignored status.
Discarding issues (CI builds only)
If you configure Continuous Integration (CI) builds and open an issue in Visual Studio using the 'open in IDE' button from one of the supported CI plug-ins, this imports the issue into your open project. If you have fixed this issue or simply want to remove it from your issue list, you can right-click the issue and select Discard this issue. Note that this functionality does not apply to issues found from a full analysis; you cannot discard these issues.
Submitting a false positive report
For C/C++ users, false positive reports can be generated to collect information needed to reproduce false positives in specific source files.
To submit a false positive report from Visual Studio:
- Right-click an issue in the issue window and select Create false positive report.
- A dialog will appear, asking you to save the archive as a .kwz file. Place the file somewhere you can locate it easily.
- Open a ticket with Support and attach the .kwz file.
Before you check in
Visual Studio dialogs
Within Visual Studio, you can configure settings for your Klocwork plug-in by using the following dialogs:
- For information on authenticating with the Klocwork Server, see Authentication dialog in Visual Studio.
- For information on specifying the location of the Klocwork Server and enabling or disabling analysis, see General Options dialog.
- For information on configuring your analysis and altering appearance settings, see Analysis and Appearance tabs.
- For information on configuring your SCM, see Klocwork Solution Properties dialog in Visual Studio.
Authentication dialog in Visual Studio
The Authentication dialog in Visual Studio allows users to authenticate with the Klocwork Server. When access control has been configured, all users need to authenticate with the Klocwork Server.
To access the Authentication dialog, click Login or the status icon in the task bar.
The Authentication dialog prompts you to enter your user name and password.
- If Open authentication has been set up, enter the user name of your choice.
- If Basic authentication has been set up, enter the user name and password given to you by the Klocwork administrator.
- If LDAP or NIS authentication has been set up, enter your LDAP or NIS user name and password.
Klocwork then stores a token in the user's home directory, so you need to log in only once. Note that users' passwords are not stored.
Once authenticated, you can run any Klocwork tool that points to the same Klocwork Server host and port. To run a Klocwork tool pointing to a different Klocwork Server host and port, you must log in again. Likewise, to run Klocwork as a different user, you must log in again.
General Options dialog
To open the General Options dialog in Visual Studio, go to Klocwork > Options. The Options dialog appears with the General tab open by default.
Use this dialog to specify the location of the Klocwork Servers and to enable or disable on-the-fly analysis markers and underlining.
The Klocwork Server manages integration projects and their associated settings. You can obtain the server location from your Klocwork administrator. The server and port fields must have valid values to run the analysis when it is connected to a Klocwork project.
Server specifies the host name of the Klocwork Server. You can enter either an IP address or a host name. The default is localhost.
Port specifies the port on which the Klocwork Server listens. The value must be a number between 0 and 65535. The default port is 8080.
Enable Use secure connection if a secure connection to the Klocwork Server has been set up.
Analysis and Appearance tabs
To configure analysis and appearance settings in Visual Studio, go to Klocwork > Options > Klocwork > General.
The Analysis tab allows you to enable or disable on-the-fly analysis, as well as limit how often on-the-fly analysis and/or on-demand analysis run. You can configure them both to run one to three threads at a time.
You can also configure when analysis is run on-the-fly. By default, analysis is run any time you save a file. If you prefer to have it run whenever you open a file or pause while typing, clear the On File Savecheck box under the On-The-Fly analysis menu. You can also configure whether analysis continues after a file is closed by enabling or disabling the option Continue analysis after the file has closed.
Under Analysis Mode, you can enable classic mode. When this option is enabled, it forces Klocwork to use the previous generation (pre-Klocwork 2018) analysis engine. The previous analysis engine only provides partial support for C++11 and C++14.
The Appearance tab allows you to enable or disable on-the-fly analysis markers and underlining for detected issues in your editor. You can also configure whether the change comment dialog shows by default and whether or not to show Klocwork engine errors and warnings in the error list.
The Data tab in Visual Studio allows you to control whether Klocwork data is stored next to the solution, or within a specified central location of your choice. This data includes solution properties, defects, and other meta data used by the Klocwork plug-in.
To access the Data tab, go to Klocwork > Options > Klocwork > General and select the Data tab.
If you want to store Klocwork data outside of your solution directory, select Store Klocwork data in a specified location. Click Browse and specify the location you would like the data to be stored in. The change takes effect the next time you open the solution. Once you re-open your solution, your existing data is migrated to the new specified location. You can also opt to delete the data instead of migrating it by manually deleting it before making the change to your data location. If you opt to restore storage to the solution directory, the data is migrated when you close the solution.
You can configure how verbose you want your log to be by selecting the verbosity level on the logging tab.
- 2. Errors & Warnings (this is the default option)
- 4. Debug Messages
- 5. Instrumented
Klocwork Solution Properties dialog in Visual Studio
To open the Klocwork Solution Properties dialog in Visual Studio, right-click a solution and select Klocwork Solution Properties.
There are separate tabs for C/C++ and C#, as well as a tab for configuring Source Code Management (SCM) systems.
Klocwork projects loading status
This status bar can display several possible messages, as follows:
- Ready: Your project is properly synchronized with the Klocwork Server and authentication is verified (if required).
- Login: There is an authentication error. Click Login to open the authentication dialog and enter your credentials.
- Failed to retrieve projects: There is an error with your Klocwork Server settings. Click Settings to open the General options dialog and troubleshoot the error.
- Klocwork Project specifies the C/C++ Klocwork Server project with which this Visual Studio solution is associated. Both Klocwork project language tabs (one for C/C++ and one for C#) are visible if your solution contains both C/C++ and C# projects.
- C++ Issue Configuration allows you to enable or disable checkers.
You can use the Update Build Specification action to explicitly generate a build specification for your solution or project. When selected, the Update Build Specification action performs clean and build operations on your project or solution. The build specification is generated on a per-project basis, using the Visual Studio project configuration.
To explicitly generate a build specification whenever you right-click your solution, project, folder or file, click Use the build specification generated by the "Update Build Specification" action.
To use a custom build specification for a project
- Click Specify a Custom Build Specification.
- Select your build configuration type from the Configuration list.
- Select your platform from the Platform list.
- Click ... then browse to your build specification file.
- Klocwork Project specifies the C# Klocwork Server project with which this Visual Studio solution is associated. Both Klocwork project language tabs (one for C/C++ and one for C#) are visible if your solution contains both C/C++ and C# projects.
- C# Issue Configuration allows you to enable or disable checkers.
This tab contains a list of SCM's that are supported within Visual Studio. You can configure and test your settings for each SCM manually from this tab if required.