Visual Studio Code C++ December 2021 Update: clang-tidy

Julia

The latest insiders release of the C++ extension is here, bringing clang-tidy support to VS Code! Clang-tidy is a clang-based C++ linter tool that detects common errors in your code, like style violations and bugs that can be deduced via static analysis. Clang-tidy integration was one of our top asks on GitHub, so we’re excited to announce that it’s ready for you to try!

Getting started

Do I need to install clang-tidy?

Nope! Clang-tidy now comes bundled with the C++ extension. But if you already have clang-tidy installed (and it’s on your environment’s path), the C++ extension will use that one instead. You can point the C++ extension to any clang-tidy binary by editing the C++ extension’s Clang Tidy: Path setting.

How do I run clang-tidy in VS Code?

To manually run clang-tidy, open the Command Palette (Ctrl + Shift + P) and type “Run Code Analysis.” You can run clang-tidy on the active file, on all open files, or on the entire workspace.

Screenshot showing how to manually run clang-tidy from the Command Palette

If there are certain workspace files or folders that you don’t want to run clang-tidy on, add them to the Clang Tidy: Exclude setting (C_Cpp.codeAnalysis.exclude in settings.json).

You can also set clang-tidy to run automatically whenever you open or save a file. To turn on automatic code analysis, open your project settings by selecting “Preferences: Open Settings (UI)” from the Command Palette (Ctrl + Shift + P).

Screenshot showing how to open VS Code settings from the Command Palette

Then search for “code analysis” to find all the clang-tidy settings and set Clang Tidy: Enabled to true.

Screenshot of the Clang Tidy: Enabled setting in VS Code, which must be set to true in order for code analysis to run automatically in the background

Note: You can set clang-tidy settings globally (in the User tab) or at the workspace level.

You can check if clang-tidy is running by looking for the fire icon in the blue status bar at the bottom of the window.

Screenshot of the fire icon in the status bar. Users can hover over this icon to see the status of clang-tidy.

To pause or cancel clang-tidy, click on the fire icon and then choose an option from the drop down.

Screenshot showing the Cancel and Pause options for clang-tidy from a dropdown in VS Code

How do I configure clang-tidy checks and check options?

If you have a .clang-tidy configuration file in your project directory, the C++ extension will honor the checks and options defined in that file. If you have multiple .clang-tidy configuration files in your workspace, clang-tidy will use the configuration file closest to the source file by searching up the path in its parent directories. Alternatively, you can specify a clang-tidy configuration with the Clang Tidy: Config setting. Clang Tidy: Config accepts checks and check options as a YAML/JSON-formatted string.

Screenshot of the Clang Tidy: Config setting in VS Code, where users can pass a string in YAML/JSON format to specify clang-tidy checks and options

If a source file doesn’t have a .clang-tidy configuration file in any of its parent directories, and the Clang Tidy: Config property is left empty, then the fallback configuration (defined in C_Cpp.codeAnalysis.clangTidy.fallbackConfig) will be used for that file.

You can enable and disable more checks by using the Clang Tidy > Checks: Enabled and Clang Tidy > Checks: Disabled settings. The checks defined in these settings are run in addition to the checks in the .clang-tidy file.

Screenshot of the Clang Tidy > Checks: Enabled setting in VS Code, where users pick which clang-tidy settings to run on their project

Selecting Add Item shows a list of all clang-tidy checks.

Screenshot showing the list of available clang-tidy checks after selecting Add Item in the Clang Tidy > Checks: Enabled settings

You can add as many checks as you’d like to both the Clang Tidy > Checks: Enabled and Clang Tidy > Checks: Disabled settings.

Screenshot of the Clang Tidy > Checks: Disabled and Clang Tidy > Checks: Disabled settings in VS Code, where users can choose which clang-tidy checks to run or not run for their workspace

How do I pass command line args to clang-tidy?

If you typically pass command line options to clang-tidy, you can specify those in the Clang Tidy: Args property. The Clang Tidy: Args setting takes precedence over the equivalent Clang Tidy settings in the editor (such as Clang Tidy > Checks: Enabled and Clang Tidy > Checks: Disabled).

Viewing check results in the editor

The results of clang-tidy checks (warnings and errors) are displayed in the Problems panel and as squiggles beneath relevant sections of code.

Screenshot of the results of clang-tidy checks showing up in the Problems pane in VS Code

Clicking on the problem in the Problems panel takes you to the issue in your source file. To clear the code analysis squiggles, click on the Quick Actions lightbulb, and then select Clear code analysis squiggles.

Screenshot of the "Clear Code Analysis Squiggles" Quick Action, which is visible when selecting the lightbulb next to underlined code

Clang-tidy settings

Here’s a list of new VS Code settings to help you configure clang-tidy for your workspace.

Setting name Type Default value Description
C_Cpp.codeAnalysis.clangTidy.enabled

 

Boolean False When true, clang-tidy will be enabled and run automatically if C_Cpp.codeAnalysis.runAutomatically is set to true

 

C_Cpp.codeAnalysis.runAutomatically Boolean True When true, runs clang-tidy on file open and file save.

 

C_Cpp.codeAnalysis.clangTidy.path String Null (empty) The full path to the clang-tidy executable.
C_Cpp.codeAnalysis.clangTidy.checks.enabled Array of strings Null (empty) List of enabled clang-tidy checks. The values are appended to the Checks in a .clang-tidy file or C_Cpp › Code Analysis › Clang Tidy: Config.
C_Cpp.codeAnalysis.clangTidy.checks.disabled Array of strings Null (empty) List of disabled clang-tidy checks. The values are appended to the Checks in a .clang-tidy file or C_Cpp › Code Analysis › Clang Tidy: Config, if any.
C_Cpp.codeAnalysis.clangTidy.config String Null (empty) Specifies a clang-tidy configuration in YAML/JSON format: {Checks: ‘-*,clang-analyzer-*’, CheckOptions: [{key: x, value: y}]}. When empty, any found .clang-tidy files will be used.
C_Cpp.codeAnalysis.clangTidy.fallbackConfig String Null (empty) Specifies a clang-tidy configuration in YAML/JSON format to be used as a fallback when C_Cpp › Code Analysis › Clang Tidy: Config is not set and no .clang-tidy file is found.
C_Cpp.codeAnalysis.clangTidy.args Array of strings Null (empty) Command line arguments to pass to clang-tidy. These take precedence over the equivalent C_Cpp.codeAnalysis.clangTidy.* settings.
C_Cpp.codeAnalysis.exclude String Null (empty) Configure glob patterns for excluding folders and files for code analysis.
C_Cpp.codeAnalysis.clangTidy.headerFilter String Null (empty) A POSIX extended regular expression (ERE) matching the names of the headers to output diagnostics from. It overrides the HeaderFilterRegex option in a .clang-tidy file, if any.
C_Cpp.codeAnalysis.maxConcurrentThreads

(User level only)

Int Null (empty) The maximum number of concurrent threads to use for code analysis. The default of null (empty) uses half the value inherited from C_Cpp: Max Concurrent Threads.
C_Cpp.codeAnalysis.maxMemory

(User level only)

Int Null (empty) Fewer code analysis processes will run concurrently after this memory usage (in MB) is exceeded. The default of null (empty) uses the value inherited from C_Cpp: Max Memory.

Coming soon

Hang tight! Applying suggested fixes in the editor is coming soon.

What do you think?

Download the C++ extension for Visual Studio Code today and join our Insiders program to access this initial release of clang-tidy integration. To join our Insiders program, go to File > Preferences > Settings and under Extensions > C/C++, change the “C_Cpp: Update Channel” to “Insiders.” Then under Features > Extensions, enable “Extensions: Auto Update.”

If you run into any issues, or have any suggestions, please report them in the Issues section of our GitHub repository.

We can be reached via the comments below or in email at visualcpp@microsoft.com. You can also find our team on Twitter at @VisualC.

4 comments

Leave a comment

  • TBD TBD

    These instructions don’t work. My Update Channel is set to Insiders, and my extensions are set to Auto-update. “Check for Extension Updates” says “All extensions are up to date”. But the installed version is 1.7.1, “Install another version” doesn’t list anything newer, and I don’t see any clang-tidy integration.

    • Julia ReidMicrosoft employee

      Which version of VS Code are you using? You can check by opening VS Code and selecting Help > Release notes. The latest major release is 1.63, if you aren’t using that version, can you update and try again?

  • Hristo Hristov

    This is not just related to VSCode but to VS too: Is there a trivial way to disable code analysis on headers included from vcpkg and generally to exclude third party libraries and headers even such that are included in the source itself?