/analyze (コード分析)

コード分析とコントロール オプションを有効にします。

構文

一般的な分析オプション:

$
/analyze:only
/analyze:quiet
/analyze:max_paths number
/analyze:stacksize number
/analyze:WX-

分析プラグインのオプション:

/analyze:plugin plugin_dll

外部ファイルの分析オプション:

/analyze:external-
/analyze:external:ruleset ruleset_files

分析ログ オプション:

$
/analyze:autolog:ext extension
/analyze:log log_path

ログ ファイルの形式のオプション:

/analyze:log:format:sarif
/analyze:log:format:xml

ログ ファイルの内容のオプション:

$
$
/analyze:log:compilerwarnings
/analyze:log:includesuppressed

ルールセットのオプション:

/analyze:projectdirectory project_directory
/analyze:rulesetdirectory ruleset_directories
/analyze:ruleset ruleset_files

引数

一般的な分析オプション

$
コード分析をオンにします。 分析を明示的にオフにするには、/analyze- を使用します。 /analyze- が既定の動作です。

既定では、分析の出力は他のエラー メッセージと同様に、コンソールや Visual Studio の [出力] ウィンドウに表示されます。 また、コード分析によって filename.nativecodeanalysis.xml という名前のログ ファイルも作成されます。ここで、filename は分析されたソース ファイルの名前です。

/analyze:only
既定では、コード分析が実行される前に、コンパイラによってコードがコンパイルされ、オブジェクト ファイルが生成されます。 /analyze:only オプションを指定すると、コンパイラによってコード生成パスがスキップされ、コード分析が直接実行されます。 コンパイラ エラーが発生した場合は、コード分析の実行が妨げられます。 ただし、コンパイラは、コード生成パス中に検出される可能性のある他の警告を報告しません。 プログラムにコード生成の警告がある場合は、分析結果が信頼できないものになる可能性があります。 このオプションを使うのは、コードがコード生成の構文チェックをエラーや警告なしで通過ている場合だけにすることをお勧めします。

/analyze:quiet
コンソールや Visual Studio [出力] ウィンドウへの分析の出力をオフにします。

/analyze:max_paths number
number パラメーターで、分析するコード パスの最大数を指定します。 分析の既定値は 256 パスです。 値を大きくすると、より細かなチェックが実行されますが、分析に時間がかかることがあります。

/analyze:stacksize number
number パラメーターで、警告 C6262 を生成するスタック フレームのサイズ (バイト単位) を指定します。 スタック フレームの既定のサイズは 16 KB です。

/analyze:WX-
/WX オプションが使用されている場合でもコード分析の警告をエラーとして扱わないように、コンパイラに指示します。 詳細については、/WX (警告レベル) に関する記事を参照してください。

分析プラグインのオプション

/analyze:plugin plugin_dll
コード分析で指定したコード分析プラグイン DLL を有効にします。

パスに二重引用符 (") が必要ない場合は、/analyze:plugin と plugin_dll ファイル パスの間のスペースは省略可能です。 たとえば、/analyze:plugin EspxEngine.dll を書き込むことができます。 ただし、パスが二重引用符で囲まれている場合は、/analyze:plugin とファイル パスの間に空白を入れることはできません。 次に例を示します: /analyze:plugin"c:\path\to\EspxEngine.dll"

コード分析エンジンでは、プラグインを使って、特定のカテゴリの欠陥を見つけやすくします。 コード分析エンジンには、さまざまな欠陥を検出する組み込みプラグインがいくつか付属しています。 コード分析エンジンで別のプラグインを使うには、/analyze:plugin オプションを使って指定します。

Visual Studio に付属する EspXEngine.dll などの一部のプラグインには、さらなる分析を行うことができる拡張機能が備わっています。 Visual Studio には、EspXEngine の次の拡張機能が含まれています: ConcurrencyCheck.dll、CppCoreCheck.dll、EnumIndex.dll、HResultCheck.dll、VariantClear.dll。 これらはそれぞれ、コンカレンシーの問題、CppCoreGuidelines の違反、enum 値のインデックスとしての不適切な使用、HRESULT 値、VARIANT 値に関する欠陥をチェックします。

コマンド ライン上でビルドする場合は、Esp.Extensions 環境変数を使って EspXEngine の拡張機能を指定できます。 次に例を示します。

set Esp.Extensions=ConcurrencyCheck.dll;CppCoreCheck.dll;

例に示したように、各拡張機能を区切るにはセミコロン (;) を使います。 末尾のセミコロンは必要ではありません。 拡張機能の絶対ファイル パスを使ったり、EspXEngine.dll を含むディレクトリからの相対パスを指定したりすることもできます。

EspXEngine.dll プラグインは ConcurrencyCheck.dll を使用して、コンカレンシーに関連するコード分析チェックを実装します。 これらのチェックでは、C261XX という範囲の警告が発生します (C26100 から C26167 など)。

開発者コマンド プロンプト ウィンドウでビルドする場合は、まず Esp.Extensions 環境変数を設定して、ConcurrencyCheck.dll 拡張機能を指定します。

set Esp.Extensions=ConcurrencyCheck.dll

その後、コンパイラ オプション /analyze:plugin EspXEngine.dll を使って、EspXEngine プラグインを使用します。

外部ファイルの分析オプション

Visual Studio 2019 バージョン 16.10 以降では、外部ヘッダーに対して異なる分析ルールと動作を指定できます。 ディレクトリを "外部" ディレクトリとして指定するには、/external:I、/external:env、または /external:anglebrackets オプションを使用します。 #include を使用して外部ディレクトリまたはそのサブディレクトリからインクルードされたファイルは、外部ヘッダーと見なされます。 詳細については、「/external (外部ヘッダー診断)」を参照してください。

コード分析には、外部ファイルの分析を制御するために次のオプションが用意されています。

/analyze:external-
外部ヘッダー ファイルの分析をスキップします。 既定では、コード分析は他のファイルと同様に外部ヘッダー ファイルを分析します。 /analyze:external- オプションを設定すると、外部ファイルのテンプレートを除き、外部として指定したすべてのファイルがコード分析によってスキップされます。 外部ヘッダーで定義されているテンプレートは、/external:templates- オプションを使用して非外部として扱われます。 /external:Wn オプションはコード分析には影響しません。 たとえば、/external:W0 が指定されている場合でも、コード分析は外部ファイルを分析し、欠陥を報告します。

/analyze:external:ruleset ruleset_files
ruleset_files パラメーターでは、外部ファイルの分析に使用する、セミコロンで区切られた 1 つ以上のルールセット ファイルを指定します。 ルールセットの詳細については、「ルールセットのオプション」セクションを参照してください。

環境変数 (CAExcludePath) では、環境変数で指定されているディレクトリ下にあるファイルの分析をスキップするのと同様の、ただしよりシンプルな機能が提供されます。 ディレクトリが /external:* オプションと CAExcludePath 環境変数の両方で指定されている場合は、除外対象と見なされ、/analyze:external* オプションはそのディレクトリに適用されません。

分析ログ オプション

$
このフラグは、分析対象のソース ファイルごとに分析ログ ファイルの作成を有効にするために以前は必要でした。 ログ ファイルが既定で作成されるようになったため、通常このフラグは冗長になります。 使用すると、既定のログの拡張子が .xml ではなく *.pftlog に変更されます。 ファイルへのログ記録を無効にするには、/analyze:autolog- を使います。

/analyze:autolog:ext extension
分析ログ ファイルの既定の拡張子をオーバーライドし、代わりに extension を使います。 .sarif 拡張子を使う場合、ログ ファイルでは既定の XML 形式ではなく SARIF 形式が使用されます。

/analyze:log log_path
自動的に生成されるログ ファイルのパスの代わりに、log_path というログ ファイルのパスを指定します。 パス log_path の末尾に円記号があり、既存のディレクトリを参照している場合、コード分析ではすべてのログ ファイルが指定したディレクトリ内に作成されます。 それ以外の場合、log_path ではファイル パスを指定します。 ファイル パスは、分析したすべてのソース ファイルのログを指定したログ ファイルにまとめるようコンパイラに指示します。 ファイル パスに .sarif 拡張子が付いている場合、ログ ファイルでは既定の XML 形式ではなく SARIF 形式が使用されます。 この動作は、/analyze:log:format:* オプションを使用してオーバーライドできます。

ログ ファイルの形式のオプション

Visual Studio 2019 バージョン 16.9 以降では、コード分析に対して異なるログ形式のオプションを指定できます。

/analyze:log:format:xml
使用されるファイル拡張子と関係なく、XML ログ形式の使用を強制します。

/analyze:log:format:sarif
使用されるファイル拡張子と関係なく、SARIF ログ形式の使用を強制します。

ログ ファイルの内容のオプション

Visual Studio 2019 バージョン 16.9 以降では、コード分析に対して異なるログ内容のオプションを指定できます。

$
警告を発行しない分析されたファイルに対して、SARIF ログ ファイルにファイル成果物エントリを追加します。 既定では、このオプションは無効になっています。 ソース ファイルと結果を出力したファイルの成果物は、常に含まれます。

$
ルール構成エントリを追加して、ユーザーが既定のルール構成をオーバーライドした方法を判別します (既定では無効)。

/analyze:log:compilerwarnings
分析エンジンによって検出されたすべての欠陥と、すべてのコンパイラの警告を、分析ログ ファイルに追加します。 既定では、コンパイラの警告は分析ログ ファイルに含まれません。 コード分析中のコンパイラの警告について詳しくは、/analyze:only オプションを参照してください。

/analyze:log:includesuppressed
抑制された警告と抑制されていない警告の両方を、分析ログ ファイルに追加します。 既定では、抑制された警告は分析ログ ファイルに含まれません。 分析に対してルールセット ファイルを指定する場合、そのルールセット ファイルによって無効にされる警告は、/analyze:log:includesuppressed を指定した場合でもログには含まれません。

ルールセットのオプション

/analyze:projectdirectory project_directory
現在のプロジェクト ディレクトリを指定します。 ルールセット (またはそれに含まれる項目) がファイル名の場合、コンパイラではまず最初に、指定した project_directory の下にあるファイルを検索します。 見つからない場合は、次に /analyze:rulesetdirectory で指定した ruleset_directories を検索します (指定した場合)。 ルールセット (またはそれに含まれる項目) が相対パスの場合、コンパイラではまず最初に、プロジェクト ディレクトリの下にあるファイルを検索します。 ルールセットが見つからない場合は、次に現在の作業ディレクトリを検索します。 このオプションは、Visual Studio 2019 バージョン 16.9 以降で使用できます。

/analyze:rulesetdirectory ruleset_directories
ルールセットの検索パスのセミコロンで区切られたリストを指定します。 ルールセット (またはそれに含まれる項目) がファイル名の場合、コンパイラではまず最初に、/analyze:projectdirectory で指定した project_directory の下にあるファイルを検索し (指定した場合)、次に指定した ruleset_directories を検索します。 このオプションは、Visual Studio 2019 バージョン 16.9 以降で使用できます。

/analyze:ruleset ruleset_files
分析に使用する 1 つ以上のルールセット ファイルを指定します。 このオプションを使用すると、分析の効率が向上します。分析エンジンが、実行前に、ルールセット ファイルでアクティブなルールが指定されていないチェッカーを除外しようとするためです。 それ以外の場合、エンジンは有効になっているすべてのチェッカーを実行します。

Visual Studio に付属するルールセット ファイルは、%VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets 内にあります。

次のカスタム ルールセットの例では、C6001 と C26494 をチェックし、それらを警告として報告する必要があることを分析エンジンに指示します。

このファイルは、引数で完全なパスを指定する限り任意の場所に、または /analyze:projectdirectory か /analyze:rulesetdirectory オプションで指定するディレクトリの下に配置できます。

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description="New rules to apply." ToolsVersion="15.0">
  <Rules AnalyzerId="Microsoft.Analyzers.NativeCodeAnalysis" RuleNamespace="Microsoft.Rules.Native">
    <Rule Id="C6001" Action="Warning" />
    <Rule Id="C26494" Action="Warning" />
  </Rules>
</RuleSet>

既定では、ルールセット ファイルのファイル拡張子は *.ruleset です。 Visual Studio では、ルールセット ファイルを参照するときに既定の拡張子を使用します。 ただし、任意の拡張子を使用できます。

ルールセットの詳細については、「ルール セットを使用して実行対象の C++ ルールを指定する」を参照してください。

解説

詳細については、「C/C++ のコード分析の概要」と「C/C++ のコード分析に関する警告」を参照してください。

Visual Studio 開発環境でこのコンパイラ オプションを設定するには

1. プロジェクトの [プロパティ ページ] ダイアログ ボックスを開きます。 詳細については、Visual Studio での C++ コンパイラとビルド プロパティの設定に関する記事を参照してください。

2. [構成プロパティ]>[コード分析]>[全般] プロパティ ページを選択します。

3. [コード分析] のプロパティを 1 つ以上変更します。

4. [OK] または [適用] を選択して、変更内容を保存します。

Visual Studio 2019 バージョン 16.10 以降で外部ファイル分析オプションを設定するには、次の手順を実行します。

1. プロジェクトの [プロパティ ページ] ダイアログ ボックスを開きます。

2. [構成プロパティ]>[C/C++]>[出力ファイル] プロパティ ページを選択します。

3. プロパティを設定します。

   • [外部ヘッダーのコード分析を無効にする] を選択すると、/analyze:external- オプションが設定されます。

   • [外部ヘッダーの分析ルールセット] を選択すると、/analyze:external:ruleset path オプションが設定されます。

4. [OK] または [適用] を選択して、変更内容を保存します。

このコンパイラ オプションをコードから設定するには

1. 以下を参照してください。EnablePREfast

関連項目

MSVC コンパイラ オプション
MSVC コンパイラのコマンド ライン構文