C++ Core ガイドライン チェッカーの使用Using the C++ Core Guidelines checkers

C++ Core ガイドラインは、ガイドライン、ルール、および C++ 専門家とデザイナーで作成された C++ のコーディングについてのベスト プラクティスの移植可能なセットです。The C++ Core Guidelines are a portable set of guidelines, rules, and best practices about coding in C++ created by C++ experts and designers. Visual Studio では、c++ のコード分析ツールの一部としてこれらのルールのサブセットがサポートされています。Visual Studio currently supports a subset of these rules as part of its code analysis tools for C++. Core ガイドラインのチェッカーが Visual Studio 2017 では、既定でインストールされVisual Studio 2015 用の NuGet パッケージとして利用可能なします。The core guideline checkers are installed by default in Visual Studio 2017, and are available as a NuGet package for Visual Studio 2015.

C++ Core ガイドラインのプロジェクトThe C++ Core Guidelines Project

Bjarne Stroustrup と他のユーザーによって作成された、C++ Core Guidelines は、安全で効果的に最新の C++ を使用するためのガイドです。Created by Bjarne Stroustrup and others, the C++ Core Guidelines are a guide to using modern C++ safely and effectively. ガイドラインは、静的な型の安全性とリソースの安全性を強調します。The Guidelines emphasize static type safety and resource safety. 排除または言語のエラーを起こしやすい部分を最小化する方法を特定され、信頼性の高い方法でパフォーマンスが向上と、コードを簡素化する方法をお勧めします。They identify ways to eliminate or minimize the most error-prone parts of the language, and suggest how to make your code simpler and more performant in a reliable way. 次のガイドラインは、標準の C++ Foundation によって管理されます。These guidelines are maintained by the Standard C++ Foundation. 詳細については、ドキュメントを参照してください。 C++ Core Guidelines、C++ Core Guidelines のドキュメントのプロジェクト ファイルにアクセスしてGitHubします。To learn more, see the documentation, C++ Core Guidelines, and access the C++ Core Guidelines documentation project files on GitHub.

C++ Core Check のガイドラインにコード分析を有効にします。Enable the C++ Core Check guidelines in Code Analysis

選択してプロジェクトでコード分析を有効にすることができます、ビルドに対するコード分析を有効にするでチェック ボックスをオン、コード分析のセクション、プロパティ ページのダイアログ ボックスプロジェクト。You can enable code analysis on your project by selecting the Enable Code Analysis on Build checkbox in the Code Analysis section of the Property Pages dialog for your project.

コード分析の全般設定のプロパティ ページ

C++ Core Check ルールのサブセットは、コード分析を有効にすると、既定で実行している Microsoft ネイティブ推奨規則セットに含まは。A subset of C++ Core Check rules is included in the Microsoft Native Recommended rule set that runs by default when code analysis is enabled. 追加 Core Check の規則を有効にするには、 ドロップダウン リストをクリックし、ルール セットに含めるを選択します。To enable additional Core Check rules, click on the dropdown and choose which rule sets you want to include:

C++ Core Check の規則の追加用のドロップダウン リストを設定します。

使用例Examples

C++ Core Check の規則を検索する問題のいくつかの例を次に示します。Here's an example of some of the issues that the C++ Core Check rules can find:

// CoreCheckExample.cpp
// Add CppCoreCheck package and enable code analysis in build for warnings.

int main()
{
    int arr[10];           // warning C26494
    int* p = arr;          // warning C26485

    [[gsl::suppress(bounds.1)]] // This attribute suppresses Bounds rule #1
    {
        int* q = p + 1;    // warning C26481 (suppressed)
        p = q++;           // warning C26481 (suppressed)
    }

    return 0;
}

この例では、C++ Core Check の規則を検索する警告のいくつかを示します。This example demonstrates a few of the warnings that the C++ Core Check rules can find:

  • C26494 はルール Type.5: 常にオブジェクトを初期化します。C26494 is rule Type.5: Always initialize an object.

  • C26485 はルール Bounds.3: 配列からポインターへの減退しません。C26485 is rule Bounds.3: No array-to-pointer decay.

  • C26481 はルール Bounds.1: ポインター演算を使用しないでください。C26481 is rule Bounds.1: Don't use pointer arithmetic. 代わりに、span を使用してください。Use span instead.

    C++ Core Check のコード分析ルールセットはインストールされている、このコードをコンパイルすると、最初の 2 つの警告は、出力が、3 つ目の抑制を有効になっている場合。If the C++ Core Check code analysis rulesets are installed and enabled when you compile this code, the first two warnings are output, but the third is suppressed. コード例からのビルド出力を次に示します。Here's the build output from the example code:

1>------ Build started: Project: CoreCheckExample, Configuration: Debug Win32 ------
1>  CoreCheckExample.cpp
1>  CoreCheckExample.vcxproj -> C:\Users\username\documents\visual studio 2015\Projects\CoreCheckExample\Debug\CoreCheckExample.exe
1>  CoreCheckExample.vcxproj -> C:\Users\username\documents\visual studio 2015\Projects\CoreCheckExample\Debug\CoreCheckExample.pdb (Full PDB)
c:\users\username\documents\visual studio 2015\projects\corecheckexample\corecheckexample\corecheckexample.cpp(6): warning C26494: Variable 'arr' is uninitialized. Always initialize an object. (type.5: http://go.microsoft.com/fwlink/p/?LinkID=620421)
c:\users\username\documents\visual studio 2015\projects\corecheckexample\corecheckexample\corecheckexample.cpp(7): warning C26485: Expression 'arr': No array to pointer decay. (bounds.3: http://go.microsoft.com/fwlink/p/?LinkID=620415)
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

安全なコードを記述するため、C++ Core Guidelines は。The C++ Core Guidelines are there to help you write better and safer code. ただし、場所、ルール、またはプロファイルを適用しないインスタンスがある場合を簡単に、コード内で直接非表示になります。However, if you have an instance where a rule or a profile shouldn't be applied, it's easy to suppress it directly in the code. 使用することができます、gsl::suppressを検出して、次のコード ブロックの規則の違反をレポートから C++ Core Check を保持する属性。You can use the gsl::suppress attribute to keep C++ Core Check from detecting and reporting any violation of a rule in the following code block. 特定のルールを抑制する個々 のステートメントをマークすることができます。You can mark individual statements to suppress specific rules. 記述することで、全体の bounds プロファイルを抑制することができますも[[gsl::suppress(bounds)]]含めず、特定のルールの数。You can even suppress the entire bounds profile by writing [[gsl::suppress(bounds)]] without including a specific rule number.

規則セットのサポートSupported rule sets

ように、新しいルールを追加する、C++ Core ガイドライン チェッカーの既存のコードを生成する警告の数は増やすことができます。As new rules are added to the C++ Core Guidelines Checker, the number of warnings that are produced for pre-existing code may increase. 有効にするのにルールの種類をフィルター処理するのに定義済みの規則のセットを使用することができます。You can use predefined rule sets to filter which kinds of rules to enable. ほとんどの規則の参照トピックでは、 Visual Studio C コア確認リファレンスします。Reference topics for most rules are under Visual Studio C++ Core Check Reference.

Visual Studio 2017 バージョン 15.3 の時点では、サポートされている規則セット。As of Visual Studio 2017 version 15.3, the supported rule sets are:

警告を 1 つだけ、またはグループの数を制限することができます。You can choose to limit warnings to just one or a few of the groups. ネイティブ最小ネイティブ推奨ルール セットには、その他の PREfast のチェックだけでなく C++ Core Check の規則が含まれます。The Native Minimum and Native Recommended rule sets include C++ Core Check rules in addition to other PREfast checks. 確認には、使用可能なルール セット、プロジェクトのプロパティ ダイアログを開き、次のように選択しますコード Analysis\General、にあるボックスを開き、規則セットコンボ ボックス、および選択複数の規則セットの選択To see the available rule sets, open the Project Properties dialog, select Code Analysis\General, open the dropdown in the Rule Sets combo-box, and pick Choose multiple rule sets. Visual Studio でのルール セットの使用に関する詳細については、次を参照してください。ルール セットのコード分析規則のグループを使用してします。For more information about using Rule Sets in Visual Studio, see Using Rule Sets to Group Code Analysis Rules.

[マクロ]Macros

全体のカテゴリには、コードの警告を抑制するが簡単にするマクロを定義するヘッダー ファイルには、C++ Core ガイドライン チェッカーできます。The C++ Core Guidelines Checker comes with a header file, which defines macros that make it easier to suppress entire categories of warnings in code:

ALL_CPPCORECHECK_WARNINGS
CPPCORECHECK_TYPE_WARNINGS
CPPCORECHECK_RAW_POINTER_WARNINGS
CPPCORECHECK_CONST_WARNINGS
CPPCORECHECK_OWNER_POINTER_WARNINGS
CPPCORECHECK_UNIQUE_POINTER_WARNINGS
CPPCORECHECK_BOUNDS_WARNINGS

これらのマクロは、ルール セットに対応し、スペースで区切られた警告番号のリストに展開します。These macros correspond to the rule sets and expand into a space-separated list of warning numbers. 適切なプラグマ コンストラクトを使用すると、プロジェクトの興味深いは、有効な一連の規則またはコードのセクションを構成できます。By using the appropriate pragma constructs, you can configure the effective set of rules that is interesting for a project or a section of code. 次の例では、コード分析警告定数修飾子の欠如についてのみが表示されます。In the following example, code analysis warns only about missing constant modifiers:

#include <CppCoreCheck\Warnings.h>
#pragma warning(disable: ALL_CPPCORECHECK_WARNINGS)
#pragma warning(default: CPPCORECHECK_CONST_WARNINGS)

属性Attributes

Microsoft Visual C コンパイラでは、属性を非表示、GSL の制限付きサポートには。The Microsoft Visual C++ compiler has a limited support for the GSL suppress attribute. 式および関数内でのブロックのステートメントで警告を抑制するために使用します。It can be used to suppress warnings on expression and block statements inside of a function.

// Supress only warnings from the 'r.11' rule in expression.
[[gsl::suppress(r.11)]] new int;

// Supress all warnings from the 'r' rule group (resource management) in block.
[[gsl::suppress(r)]]
{
    new int;
}

// Suppress only one specific warning number.
// For declarations, you may need to use the surrounding block.
// Macros are not expanded inside of attributes.
// Use plain numbers instead of macros from the warnings.h.
[[gsl::suppress(26400)]]
{
    int *p = new int;
}

分析コマンド ライン オプションを使用して非表示にします。Suppressing analysis by using command-line options

#Pragmas ではなく、プロジェクトまたはファイルを 1 つの警告を抑制するのに、ファイルのプロパティ ページでコマンド ライン オプションを使用できます。Instead of #pragmas, you can use command-line options in the file's property page to suppress warnings for a project or a single file. たとえば、警告を無効にするファイルの 26400。For example, to disable the warning 26400 for a file:

1) ファイルを右クリックしてソリューション エクスプ ローラーRight-click the file in Solution Explorer

2) 選択プロパティ |C または C++ |コマンド ラインChoose Properties|C/C++|Command Line

3) 追加オプションウィンドウで、追加/wd26400します。In the Additional Options window, add /wd26400.

コマンド ライン オプションを使用するには、ファイルのすべてのコード分析を指定することで一時的に無効に/analyze-します。You can use the command-line option to temporarily disable all code analysis for a file by specifying /analyze-. 警告が生成されますD9025 オーバーライド '/analyze' を '/analyze -'、コード分析を後で再度有効にすることを通知します。This produces warning D9025 overriding '/analyze' with '/analyze-', which reminds you to re-enable code analysis later.

特定のプロジェクト ファイルでは、C++ Core ガイドライン チェッカーの有効化Enabling the C++ Core Guidelines Checker on specific project files

重点を置いてコード分析とも、Visual Studio IDE を使用すると便利場合があります。Sometimes it may be useful to do focused code analysis and still use the Visual Studio IDE. ビルド時間を節約し、結果をフィルター処理しやすく、大規模なプロジェクトの次のサンプル シナリオを使用できます。The following sample scenario can be used for large projects to save build time and to make it easier to filter results:

  1. コマンド シェルで次のように設定します。、esp.extensionesp.annotationbuildlevel環境変数。In the command shell set the esp.extension and esp.annotationbuildlevel environment variables.
  2. これらの変数を継承するには、コマンド シェルから Visual Studio を起動します。To inherit these variables, start Visual Studio from the command shell.
  3. プロジェクトを読み込むし、そのプロパティを開きます。Load your project and open its properties.
  4. コード分析を有効にする、適切なルール セットの選択が、コード分析の拡張機能を有効にしません。Enable code analysis, pick the appropriate rule sets, but do not enable code analysis extensions.
  5. C++ Core ガイドライン チェッカーの使用の分析のプロパティを表示するファイルに移動します。Go to the file you want to analyze with the C++ Core Guidelines Checker and open its properties.
  6. 選択C/c++ \Command ライン オプション追加 /analyze:plugin EspXEngine.dllChoose C/C++\Command Line Options and add /analyze:plugin EspXEngine.dll
  7. プリコンパイル済みヘッダーの使用を無効にする (C/c++ \Precompiled ヘッダー)。Disable the use of precompiled header (C/C++\Precompiled Headers). これは、ため、拡張機能のエンジンがプリコンパイル済みヘッダー (PCH); からの内部情報を読み取ろうと可能性があります。PCH は、既定のプロジェクト オプションでコンパイルである場合が、互換性のあるはできません。This is necessary because the extensions engine may attempt to read its internal information from the precompiled header (PCH); if the PCH compiled with default project options, it will not be compatible.
  8. プロジェクトをリビルドします。Rebuild the project. 共通の PREFast のチェックは、すべてのファイルを実行する必要があります。The common PREFast checks should run on all files. C++ Core ガイドライン チェッカーが既定で有効でないためする必要があります、それを使用するように構成ファイルでのみ実行します。Because the C++ Core Guidelines Checker is not enabled by default, it should only run on the file that is configured to use it.

Visual Studio の外部では、C++ Core ガイドライン チェッカーの使用方法How to use the C++ Core Guidelines Checker outside of Visual Studio

自動ビルドで、C++ Core Guidelines のチェックを使用することができます。You can use the C++ Core Guidelines checks in automated builds.

MSBuildMSBuild

ネイティブ コード分析チェック (PREfast) はカスタム ターゲット ファイルで MSBuild 環境に統合されます。The Native Code Analysis checker (PREfast) is integrated into MSBuild environment by custom targets files. プロジェクトのプロパティを使用して、それを有効にし、C++ Core ガイドライン チェッカー (これは、PREfast に基づきます) を追加できます。You can use project properties to enable it, and add the C++ Core Guidelines Checker (which is based on PREfast):

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

Microsoft.Cpp.targets ファイルをインポートする前にこれらのプロパティを追加することを確認します。Make sure you add these properties before the import of the Microsoft.Cpp.targets file. 特定のルール セットを選択またはカスタム規則セットを作成またはその他の PREfast のチェックが含まれる既定の規則セットを使用できます。You can pick specific rule sets or create a custom rule set or use the default rule set that includes other PREfast checks.

同じアプローチを使用して、指定したファイルにのみ、C++ Core チェックを行うことができます前に説明した、MSBuild ファイルを使用します。You can run the C++ Core Checker only on specified files by using the same approach as described earlier, but using MSBuild files. 使用して、環境変数を設定することができます、BuildMacro項目。The environment variables can be set by using the BuildMacro item:

<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>

プロジェクト ファイルを変更しない場合は、コマンドラインでプロパティを渡すことができます。If you don’t want to modify the project file, you can pass properties on the command line:

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

非 MSBuild プロジェクトNon-MSBuild projects

MSBuild に依存しないビルド システムを使用する場合、チェックを実行することができますが、コード分析エンジンの構成の一部の内部について理解する必要があります。If you use a build system that doesn’t rely on MSBuild you can still run the checker, but you need to get familiar with some internals of the Code Analysis engine configuration. これらの内部構造は、今後サポートされる保証はありません。These internals are not guaranteed to be supported in the future.

いくつかの環境変数を設定して、コンパイラは適切なコマンド ライン オプションを使用する必要があります。You have to set a few environment variables and use proper command-line options for the compiler. コンパイラの特定のパスを検索するには、ディレクトリなどが含まれますがあるないように、「Native Tools コマンド プロンプト」環境で機能することをお勧めします。It is better to work under the "Native Tools Command Prompt" environment so that you don’t have to search for specific paths for the compiler, include directories, etc.

  1. 環境変数Environment variables
    • set esp.extensions=cppcorecheck.dll これは、C++ Core Guidelines のモジュールを読み込むエンジンを指示します。set esp.extensions=cppcorecheck.dll This tells the engine to load the C++ Core Guidelines module.
    • set esp.annotationbuildlevel=ignore これには、SAL 注釈を処理するロジックが無効にします。set esp.annotationbuildlevel=ignore This disables the logic that processes SAL annotations. 注釈は、C++ Core ガイドライン チェッカーのコード分析に影響しないが、これらの処理時間 (長い時間場合があります)。Annotations don’t affect code analysis in the C++ Core Guidelines Checker, yet their processing takes time (sometimes a long time). この設定は、省略可、ただし強くお勧めします。This setting is optional, but highly recommended.
    • set caexcludepath=%include% 標準ヘッダーでは発生する警告を無効にすることを強くお勧めします。set caexcludepath=%include% We highly recommend that you disable warnings which fire on standard headers. プロジェクトの一般的なヘッダーへのパスなど、ここでは、複数のパスを追加できます。You can add more paths here, for example the path to the common headers in your project.
  2. コマンド ライン オプションCommand line options
    • /analyze コード分析を有効 (も使用を検討して/analyze: のみと/analyze: quiet)。/analyze Enables code analysis (consider also using /analyze:only and /analyze:quiet).
    • /analyze:plugin EspXEngine.dll このオプションは、PREfast にコード分析の拡張機能のエンジンを読み込みます。/analyze:plugin EspXEngine.dll This option loads the Code Analysis Extensions engine into the PREfast. このエンジンでは、C++ Core ガイドライン チェッカーを読み込みます。This engine, in turn, loads the C++ Core Guidelines Checker.

ガイドライン サポート ライブラリを使用します。Use the Guideline Support Library

ガイドライン サポート ライブラリは、Core Guidelines をフォローするように設計されています。The Guideline Support Library is designed to help you follow the Core Guidelines. GSL より安全な代替手段でエラーが発生しやすい構成要素を置き換えますできる定義が含まれます。The GSL includes definitions that let you replace error-prone constructs with safer alternatives. などに置き換えることができます、T*, lengthパラメーターのペア、span<T>型。For example, you can replace a T*, length pair of parameters with the span<T> type. GSL http://www.nuget.org/packages/Microsoft.Gslします。The GSL is available at http://www.nuget.org/packages/Microsoft.Gsl. ライブラリはオープン ソースはので、ソースを表示、コメントの作成、または投稿することができます。The library is open-source, so you can view the sources, make comments, or contribute. プロジェクトに掲載する https://github.com/Microsoft/GSLします。The project can be found at https://github.com/Microsoft/GSL.

Visual Studio 2015 のプロジェクトで、C++ Core Check のガイドラインを使用します。Use the C++ Core Check guidelines in Visual Studio 2015 projects

Visual Studio 2015 を使用する場合、C++ Core Check コード分析規則セットは既定ではインストールされていません。If you use Visual Studio 2015, the C++ Core Check code analysis rule sets are not installed by default. Visual Studio 2015 での C++ Core Check コード分析ツールを有効にする前に、追加の手順を実行する必要があります。You must perform some additional steps before you can enable the C++ Core Check code analysis tools in Visual Studio 2015. マイクロソフトでは、Nuget パッケージを使用して、Visual Studio 2015 プロジェクトのサポートを提供します。Microsoft provides support for Visual Studio 2015 projects by using a Nuget package. パッケージの名前は Microsoft.CppCoreCheck とで使用可能になる http://www.nuget.org/packages/Microsoft.CppCoreCheckします。The package is named Microsoft.CppCoreCheck, and it is available at http://www.nuget.org/packages/Microsoft.CppCoreCheck. このパッケージには少なくとも Visual Studio 2015 Update 1 でインストールが必要になります。This package requires you have at least Visual Studio 2015 with Update 1 installed.

パッケージには、依存関係をヘッダーのみのガイドライン サポート ライブラリ (GSL) として別のパッケージもインストールされます。The package also installs another package as a dependency, a header-only Guideline Support Library (GSL). GitHub の「使用可能な、GSL も https://github.com/Microsoft/GSLします。The GSL is also available on GitHub at https://github.com/Microsoft/GSL.

コード分析の規則が読み込まれるため、Visual Studio 2015 内でチェックする C++ プロジェクトごとに、Microsoft.CppCoreCheck NuGet パッケージをインストールする必要があります。Because of the way the code analysis rules are loaded, you must install the Microsoft.CppCoreCheck NuGet package into each C++ project that you want to check within Visual Studio 2015.

Visual Studio 2015 でプロジェクトに Microsoft.CppCoreCheck パッケージを追加するにはTo add the Microsoft.CppCoreCheck package to your project in Visual Studio 2015

  1. ソリューション エクスプ ローラー、右クリックすると、パッケージを追加するソリューションで、プロジェクトのコンテキスト メニューを開きます。In Solution Explorer, right-click to open the context menu of your project in the solution that you want to add the package to. 選択NuGet パッケージの管理を開く、 NuGet パッケージ マネージャーします。Choose Manage NuGet Packages to open the NuGet Package Manager.

  2. NuGet パッケージ マネージャーウィンドウで、Microsoft.CppCoreCheck を検索します。In the NuGet Package Manager window, search for Microsoft.CppCoreCheck.

    Nuget パッケージ マネージャー ウィンドウは、CppCoreCheck パッケージを示しています。

  3. Microsoft.CppCoreCheck パッケージを選択し、選択、インストールをプロジェクトに規則を追加するボタンをクリックします。Select the Microsoft.CppCoreCheck package and then choose the Install button to add the rules to your project.

    NuGet パッケージの追加、追加の MSBuild .targetsファイルをプロジェクトでコード分析を有効にしたときに呼び出されるプロジェクト。The NuGet package adds an additional MSBuild .targets file to your project that is invoked when you enable code analysis on your project. これは、 .targetsファイルは、Visual Studio コード分析ツールに追加の拡張機能として、C++ Core Check の規則を追加します。This .targets file adds the C++ Core Check rules as an additional extension to the Visual Studio code analysis tool. パッケージがインストールされている場合は、有効または無効、リリースと実験用のルールにプロパティ ページ ダイアログを使用できます。When the package is installed, you can use the Property Pages dialog to enable or disable the released and experimental rules.

関連項目See Also

Visual Studio の C++ Core Check 参照します。Visual Studio C++ Core Check Reference.