{"id":19115,"date":"2018-04-09T10:00:16","date_gmt":"2018-04-09T17:00:16","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/vcblog\/?p=19115"},"modified":"2019-02-18T17:47:59","modified_gmt":"2019-02-18T17:47:59","slug":"c-code-analysis-configure-rules-from-the-command-line","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/c-code-analysis-configure-rules-from-the-command-line\/","title":{"rendered":"C++ code analysis: configure rules from the command line"},"content":{"rendered":"

This post written by Sunny Chatterjee and Andrew Pardoe<\/em><\/p>\n

Visual Studio version 15.7 Preview 3 introduces a new MSVC compiler switch, \/analyze:ruleset<\/code>, that configures code analysis runs. The primary motivation for this switch is to enable developers who are using C++ Code Analysis without using MSBuild to filter rules. But developers who are using code analysis with MSBuild also benefit from this switch: code analysis runs are faster, increasing your compilation throughput.<\/p>\n

What are code analysis rulesets?<\/h3>\n

Code analysis rulesets allow you to choose what code analysis results you see when you analyze your code. Code analysis rulesets are found in Project > Properties > Code Analysis > General. A new C++ project by default has the ruleset \u201cMicrosoft Native Recommended Rules\u201d selected.<\/p>\n

\"\"<\/a><\/p>\n

You can select from rulesets you wish to apply to your project with the highlighted dropdown.<\/p>\n

Visual Studio comes with a handful of built-in rulesets you can choose from. They\u2019re located in %VSINSTALLDIR%\\Team Tools\\Static Analysis Tools\\Rule Sets<\/code>. We\u2019re increasing this set of rules\u2014stay tuned to the VC Blog<\/a> for more information on this.<\/p>\n

You can also create your own custom ruleset and apply that for your project. To create a custom ruleset, go to File > New > File > General > Code Analysis Rule Set.<\/p>\n

\"\"<\/a><\/p>\n

Prior to Visual Studio 2017 version 15.7 Preview 3, all rules are run every time you run C++ code analysis. When you run code analysis for a given project, checkers like C++ Core Check generate a list of defects. After code analysis finishes, there\u2019s an MSBuild task which merges the list of defects together and filters them according to the ruleset selected for the project. You\u2019re only shown the warnings that apply to your currently selected code analysis ruleset.<\/p>\n

While the old mechanism works great if you are building inside VS environment, there are a couple of areas where it falls short. First, if you are using the VS compiler toolset in your custom build environment, you don\u2019t get any configuration options through rulesets. You must write your own tool for filtering defects as per your needs. Second, inside the current VS environment itself, the ruleset filtering mechanism is essentially a post processing tool \u2013 the checkers do all the work to generate the defect, which then gets filtered out in the end. We added \/analyze:ruleset<\/code> in the MSVC compiler toolset to overcome these shortcomings in the code analysis experience.<\/p>\n

How does \/analyze:ruleset work?<\/h3>\n

The new \/analyze:ruleset<\/code> option can be used with any build configuration: inside or outside of VS, using MSBuild, Ninja, or a custom build system. This new option allows the compiler to directly filter out defects based on the set of rules specified in the ruleset. Now that the compiler has knowledge of what rules are active, it can pass on that knowledge to the individual checkers, so they can make smart decisions. For example, if the ruleset only specifies rules for type safety, more expensive checks like lifetimes can turn themselves off, so you only pay for what you need in terms of analysis cost. Not having to run unselected rules means that your code analysis experience is faster and more fluid.<\/p>\n

Using \/analyze:ruleset<\/h3>\n

Taking advantage of this new switch is simple: just define your own ruleset files and pass that option to the compiler when running code analysis. This is best illustrated with a step-by-step example. In this example, we\u2019ll detect all the defects related to uninitialized variables in our program.<\/p>\n

    \n
  1. First, we need to identify the set of rules which will detect uninitialized variables and memory. For this example, we pick two rules that\u2019ll help us, C6001 and C26494.<\/li>\n
  2. Now need to create a ruleset file which contains the set of rules you selected. We can do this in Visual Studio as shown above or we can manually create a ruleset by authoring a simple XML.<\/li>\n
  3. Now we have a ruleset file that looks like below that we\u2019ve saved as UninitVariable.ruleset<\/code>.\n

    [xml]\n<?xml version="1.0" encoding="utf-8"?>\n<RuleSet Name="New Rule Set" Description=" " ToolsVersion="15.0">\n <Rules AnalyzerId="Microsoft.Analyzers.NativeCodeAnalysis" RuleNamespace="Microsoft.Rules.Native">\n <Rule Id="C6001" Action="Warning" \/>\n <Rule Id="C26494" Action="Warning" \/>\n <\/Rules>\n<\/RuleSet>\n[\/xml]<\/p>\n<\/li>\n

  4. For this example, our test file looks like below. We name it test.cpp<\/code>.\n
    \nint f( bool b )\n{\n   int i;\n   if ( b )\n   {\n      i = 0;\n   }\n   return i; \/\/ i is unintialized if b is false\n}\n<\/pre>\n<\/li>\n
  5. We run code analysis without any configuration option and observe the following warnings:\n
    \nE:\\test>cl.exe \/c test.cpp \/analyze:plugin EspXEngine.dll\n\nMicrosoft (R) C\/C++ Optimizing Compiler Version 19.14.26329 for x86\nCopyright (C) Microsoft Corporation.  All rights reserved.\n\ntest.cpp\ne:\\test\\test.cpp(8) : warning C6001: Using uninitialized memory 'i'.: Lines: 3, 4, 8\ne:\\test\\test.cpp(3) : warning C26494: Variable 'i' is uninitialized. Always initialize an object (type.5).\ne:\\test\\test.cpp(1) : warning C26497: The function 'f' could be marked constexpr if compile-time evaluation is desired (f.4).\ne:\\test\\test.cpp(1) : warning C26440: Function 'f' can be declared 'noexcept' (f.6).\n<\/pre>\n<\/li>\n
  6. Next, we pass the additional compiler option to specify our custom ruleset for identifying uninitialized variables: \/analyze:ruleset UninitVariable.ruleset<\/code>.\n
    \nE:\\test>cl.exe \/c test.cpp \/analyze:plugin EspXEngine.dll \/analyze:ruleset UninitVariable.ruleset\n\nMicrosoft (R) C\/C++ Optimizing Compiler Version 19.14.26329 for x86\nCopyright (C) Microsoft Corporation.  All rights reserved.\n\ntest.cpp\ne:\\test\\test.cpp(8) : warning C6001: Using uninitialized memory 'i'.: Lines: 3, 4, 8\ne:\\test\\test.cpp(3) : warning C26494: Variable 'i' is uninitialized. Always initialize an object (type.5).\n<\/pre>\n<\/li>\n<\/ol>\n
    With the \/analyze:ruleset<\/code> option, code analysis only runs the rules for uninitialized variables and the additional warnings which were not related to these rules don\u2019t show up anymore.<\/p>\n
    In closing<\/h3>\n
    We hope that you\u2019ll find \/analyze:ruleset<\/code> option useful for configuring code analysis runs in your private build environments. We\u2019ve started taking advantage of it already! For example, our code analysis targets file in Visual Studio now passes the \/analyze:ruleset<\/code> option to the compiler when running code analysis. This way we can optimize our checks based on the selected ruleset. We\u2019ll be introducing new default rulesets in the future as well as providing support in Visual Studio to run C++ code analysis in build environments like CMake for Ninja and Visual Studio.<\/p>\n
    As always, we welcome your feedback. We can be reached via the comments below or via email (visualcpp@microsoft.com<\/a>).<\/p>\n
    If you encounter other problems with MSVC in Visual Studio 2017 please let us know through Help > Report A Problem in the product<\/a>, or via Developer Community<\/a>. Let us know your suggestions through UserVoice<\/a>. You can also find us on Twitter (@VisualC<\/a>) and Facebook (msftvisualcpp<\/a>).<\/p>\n","protected":false},"excerpt":{"rendered":"
    This post written by Sunny Chatterjee and Andrew Pardoe Visual Studio version 15.7 Preview 3 introduces a new MSVC compiler switch, \/analyze:ruleset, that configures code analysis runs. The primary motivation for this switch is to enable developers who are using C++ Code Analysis without using MSBuild to filter rules. But developers who are using code […]<\/p>\n","protected":false},"author":312,"featured_media":35994,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-19115","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-cplusplus"],"acf":[],"blog_post_summary":"
    This post written by Sunny Chatterjee and Andrew Pardoe Visual Studio version 15.7 Preview 3 introduces a new MSVC compiler switch, \/analyze:ruleset, that configures code analysis runs. The primary motivation for this switch is to enable developers who are using C++ Code Analysis without using MSBuild to filter rules. But developers who are using code […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/19115","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/312"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=19115"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/19115\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/35994"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=19115"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=19115"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=19115"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}