How to use the C++ Core Guidelines Checker outside of Visual Studio

This post written by Sergiy Oryekhov and Andrew Pardoe

The latest C++ Core Guidelines Checker is deployed as a part of the Native Code Analysis tools in Visual Studio 2017 15.3. These tools are designed for use in Visual Studio, which provides a rule set editor for filtering warnings. But what if you want to adopt the C++ Core Guidelines checks in your automated builds?

Using the C++ Core Guidelines Checker with MSBuild

The Native Code Analysis checker (PREfast) is integrated into the MSBuild environment by custom targets files. You can use project properties to enable it, as well as add the C++ Core Guidelines Checker to the PREfast execution step:

  <PropertyGroup>
    <EnableCppCoreCheck>true</EnableCppCoreCheck>
    <CodeAnalysisRuleSet>CppCoreCheckRules.ruleset</CodeAnalysisRuleSet>
    <RunCodeAnalysis>true</RunCodeAnalysis>
  </PropertyGroup>

Make sure you add these properties before the import of the Microsoft.Cpp.targets file. Note, you can pick specific rule sets or create your custom rule set (see Managing rules in the C++ Core Guidelines Checker), or you can use the default rule set that includes other PREfast checks.

If you can’t modify the project file, you can pass properties via command line:

msbuild /p:EnableCppCoreCheck=true /p:RunCodeAnalysis=true /p:CodeAnalysisRuleSet=CppCoreCheckRules.ruleset ...

Using the C++ Core Guidelines Checker from the command line

In case you want to use a build system that doesn’t rely on MSBuild you can still run the checker, but you’ll need to get familiar with some internals of the Code Analysis engine configuration (which is not guaranteed to be supported in the disabled future).

In summary, you need to set a few environment variables and use proper command line options for the compiler. It is better to work under the “Native Tools Command Prompt” environment so that you don’t have to search for specific paths of compiler, include directories, etc.

• Environment variables:
  • set esp.extensions=cppcorecheck.dll
    This tells the engine to load the C++ Core Guidelines module.
  • set esp.annotationbuildlevel=ignore
    This variable disables additional logic that processes SAL annotations. Annotations don’t affect code analysis in the C++ Core Guidelines Checker, yet their processing takes time (sometimes a lot of time). This setting is optional, but highly recommended.
  • set caexcludepath=%include%
    It is highly recommended to disable warnings that fire on standard headers. This setting does exactly that. You can add more paths, e.g. the path to the common headers in your project.
• Command line options:
  • /analyze
    Enables code analysis (consider also using /analyze:only and /analyze:quiet).
  • /analyze:plugin EspXEngine.dll
    This option loads the Code Analysis Extensions engine into the PREfast code analysis engine. This engine, in turn, loads the C++ Core Guidelines Checker.

How to enable the C++ Core Guidelines Checker on specific project files

Sometimes it may be useful to do very focused code analysis and still leverage the Visual Studio IDE. Below is a sample scenario that can be used for large projects to save build time and to ease results filtering.

1. In the command shell set the “esp.extensions” and “esp.annotationbuildlevel” environment variables.
2. Start Visual Studio from the command shell to inherit these variables.
3. Load your project and open its properties.
4. Enable code analysis, pick the appropriate rule set, but do not enable code analysis extensions.
5. Now go to the file you want to analyze with the C++ Core Guidelines Checker and open its properties.
6. In the “C/C++Command Line Options” add /analyze:plugin EspXEngine.dll
7. Disable the use of precompiled header (“C/C++Precompiled Headers”). This is necessary since the extensions engine may attempt to read its internal information from the precompiled header and if the latter was compiled with default project options, it will not be compatible.
8. Rebuild the project. It should run code analysis on all files. Because the C++ Core Guidelines Checker is not enabled by default, it should have small effect on the build performance and produce results only from the common code analysis tools. (You can hide these by using the appropriate rule set). There will only be a small performance impact on the file that is clearly configured to use the C++ Core Guidelines Checker.

The same approach can be easily ported to the level of MSBuild files. The environment variables can be set by using the BuildMacro item. Here’s an example of how to add a BuildMacro to your MSBuild configuration.

<ItemGroup>
    <BuildMacro Include="Esp_AnnotationBuildLevel">
      <EnvironmentVariable>true</EnvironmentVariable>
      <Value>Ignore</Value>
    </BuildMacro>
    <BuildMacro Include="Esp_Extensions">
      <EnvironmentVariable>true</EnvironmentVariable>
      <Value>CppCoreCheck.dll</Value>
    </BuildMacro>
</ItemGroup>

In closing

If you’re using the C++ Core Guidelines Checker outside of Visual Studio in your automated builds or CI system, please let us know about your experience.

If you have any feedback or suggestions for us about using the C++ Core Guidelines Checker outside of VS or about any part of the Visual C++, please let us know. We can be reached via the comments below, via email (visualcpp@microsoft.com) and you can provide feedback via Help > Report A Problem in the product, or via Developer Community. You can also find us on Twitter (@VisualC) and Facebook (msftvisualcpp).