WPP プリプロセッサ

  • [アーティクル]

このセクションでは、 Windows ソフトウェア トレース プリプロセッサ (一般に WPP プリプロセッサと呼ばれます) について説明します。

WPP プリプロセッサの呼び出し

WPP プリプロセッサは、Visual Studio と MSBuild 環境を使用して呼び出すことができます。

WPP プリプロセッサを呼び出すには

  1. ソリューション エクスプローラーで、テスト プロジェクトを右クリックし、 [プロパティ] をクリックします。

  2. プロジェクトプロパティページで、 構成プロパティ をクリックして WPP トレース をクリックします。

  3. [全般] で、 [WPP の実行] オプションを [はい] に設定します。

  4. [コマンド ライン] で、以下のオプションを追加してトレース動作をカスタマイズできます。

    たとえば、 WPP トレース では、単一の スキャン構成データ ファイルを指定できます。

    カスタム データ型を指定するなど、複数の構成ファイルを指定する必要がある場合は、 -scan オプションを使用して コマンド ライン でファイルを参照します。次に例を示します。

    -scan:"$(KMDF_INC_PATH)\$(KMDF_VER_PATH)\WdfTraceEnums.h"

ビルド プロセスの詳細については、「TraceWPP タスク と WDK および Visual Studio のビルド環境」を参照してください。

TraceWPP ツール (TraceWPP.exe) を使用して、ビルド環境とは別にプリプロセッサを実行することもできます。 このツールは、WDK の bin/x86 サブディレクトリにあります。

WPP トレースの全般オプション

次の表では、WPP プリプロセッサのオプションについて説明します。 これらのオプションは、プロジェクトの WPP トレース プロパティ ページを使用するか、TraceWPP ツールのパラメーターとして Visual Studio で構成できます。

WPP トレース オプション 説明

WPP の実行

true の場合、WPP を呼び出します。

簡易リビルドの有効化

true の場合、追跡対象のインクリメンタル ビルドが実行され、false の場合は、リビルドが実行されます。

関数とマクロのオプション

WPP トレース オプション TraceWPP コマンド オプション 説明

プリプロセッサの定義

-Dマクロ

生成されたファイルの先頭にマクロ #defineマクロ を追加します。 マクロ はマクロの名前です。

このオプションは、 /D (マクロの定義) コンパイラ オプションと同じ効果を持ちます。 TMH ファイルの開始時に定義が有効であることを確認するために含まれています。

-Dマクロ=の展開

生成されたファイルの先頭に #defineマクロ展開 を追加します。 マクロ はマクロの名前で、 展開 は展開値です。

このオプションは、 /D (マクロの定義) コンパイラ オプションと同じ効果を持ちます。 TMH ファイルの開始時に定義が有効であることを確認するために含まれています。

カーネル モード コンポーネントのトレース

-km

カーネル モード コンポーネントをトレースするWPP_KERNEL_MODE マクロを定義します。 既定では、ユーザー モード コンポーネントのみがトレースされます。

Dll マクロを有効にする

-dll

WPP_DLL マクロを定義します。これにより、WPP_INIT_TRACINGが呼び出されるたびに WPP データ構造が初期化されます。 それ以外の場合、構造体は 1 回だけ初期化されます。

コントロール GUID の指定

-ctl:GUID

 指定した コントロール GUID と Error、Unusual、Noise という名前のWPP_DEFINE_BITエントリを使用して、 WPP_CONTROL_GUIDS マクロを定義します。

これは、ソース ファイルにマクロを追加する代わりに使用します。

GUID はコントロール GUID を表します。

検索と書式設定のオプション

WPP トレース オプション TraceWPP コマンド オプション 説明

感嘆符を無視する

-noshrieks

"シュリケ" とも呼ばれる感嘆符を無視するよう WPP に指示します。

%!timestamp!% などの複雑な書式設定で使用されます。 既定では、感嘆符が必要であり、WPP はそれらを解釈しようとします。

書式指定文字列の番号付けの数値ベース

-argbase:Number

"%1!d!, %2!s!" などの書式指定文字列の番号付けの数値ベースを確立します。 既定値は 1 です。

トレース メッセージを生成する関数

-func:FunctionDescription

DoTraceMessage マクロの代替手段を指定します。 これらの関数を使用して、トレース メッセージを生成できます。

たとえば、次のようなトレース メッセージのフラグとレベルの両方を指定する関数を定義できます。

-func (DoMyTraceMessage(LEVEL,FLAGS,MSG,...)

-func オプションの複数のインスタンスを使用できます。

このオプションは、ローカル構成ファイルで関数の説明を指定する代わりに使用できます。

検索する文字列を指定する

-lookfor:String

トレースを開始するために、指定された文字列のソース ファイルを検索するように WPP に指示します。 既定では、WPP は文字列 "WPP_INIT_TRACING" を検索します。

これは、独自のテンプレートを作成するユーザー向けの高度なオプションです。

たとえば、default.tpl では次のようになります。

IF FOUND WPP_INIT_TRACING
 INCLUDE um-init.tpl
ENDIF

モジュール名の指定

-p:String

この トレース プロバイダーからのメッセージの メッセージ GUID の代替フレンドリ名を指定します。 既定では、メッセージ GUID のフレンドリ名は、トレース プロバイダーが構築されたディレクトリの名前です。

既定では、メッセージ GUID のフレンドリ名は、変数 %1 で表される トレース メッセージ プレフィックス に表示されます。 このパラメーターを使用すると、トレース プロバイダーのフレンドリ名、トレース プロバイダーを含むモジュールの名前、複数のトレース プロバイダーを作成して実装されるプロジェクトの名前など、ユーザーがトレース プロバイダーを識別するのに役立つ文字列をプレフィックスに追加できます。 この情報は、ユーザーが異なるファイルまたは異なるパスにある関連するトレース プロバイダーを関連付けるのに役立ちます。

-p パラメーターには、Windows Vista 用 Windows Driver Kit (WDK) およびそれ以降のバージョンの WDK に含まれている WPP のバージョンが必要です。 -p パラメーターは、Windows 2000 以降のバージョンの Windows で動作します。

例 :

-p:TraceDrv
-p:AudioModule

ファイル オプション

WPP トレース オプション TraceWPP コマンド オプション 説明

追加のインクルード ディレクトリ

-IPath1[;Path2]

インクルード パスに追加するディレクトリを 1 つ以上指定します。複数指定する場合には、セミコロンで区切ってください。 -cfgdirと同じです。

構成ディレクトリ

-cfgdir:Path1[;Path2]

構成ファイルとテンプレート ファイルの場所を指定します。

Path1 と Path2 は、ディレクトリへの完全修飾パスを表します。 次のようにして、複数のパスを指定できます。 既定の場所は、ローカル ディレクトリです。

ファイル拡張子

-ext:.ext1[.ext2]

WPP がソース ファイルとして認識するファイルの種類を指定します。 WPP は、別のファイル名拡張子を持つファイルを無視します。

既定では、WPP は .c、.c++、.cpp、および .cxx ファイルのみを認識します。

このオプションを使用すると、WPP で使用しないリソース ファイル (.rc ファイルや .mc ファイルなど) を削除したり名前を変更したりする必要なく、WPP の既定の設定を使用できます。

たとえば、C++ ファイルとヘッダー (.h) ファイルにトレースを追加するには、次のコマンドを使用します。

-ext:.cpp。CPP.h.H

また、C++ ファイルとヘッダー ファイルの TMH ファイルに異なる名前を付けるために、 -preserveext オプションを使用します。

ファイル拡張子を保持する

-preserveext:.ext1[.ext2]

TMH ファイルの作成時に、指定したファイル名拡張子を保持します。

既定では、すべてのファイルの種類の TMH ファイルには filename.tmh という名前が付けられます。 これにより、同じ名前のソース ファイルが複数ある場合に、ファイル名の競合が発生します。

たとえば、既定では、C ファイル (.c) ファイルとヘッダー (.h) ファイルの TMH ファイルには <filename.tmh> という名前が付けられます。 -preserveext:.c .h を使用すると、TMH ファイルの名前は <filename>.c.tmh と <filename>.h.tmh になります。

出力ディレクトリ

 -odir:path

WPPが作成する出力ファイルのディレクトリを指定します。

Path は、ディレクトリへの完全修飾パスです。 既定の場所は、ローカル ディレクトリです。

テンプレート ファイルの指定

-gen{ File.tpl }. ext

WPP が中かっこ {}の間に指定された名前で処理するすべてのソース ファイルに対して、指定したファイル名拡張子を持つ別のファイルを作成します。

File.tpl はソース ファイルを表します。 *.ext は、作成されるファイルの種類とそのファイル名拡張子を表します。

複数 の -gen オプションを 指定できます。

たとえば、 -gen{um-default.tpl}.tmh は、WPP が処理するすべての um-default.tpl ファイルについて、 um-default.tmh ファイルを生成することを意味します。

構成データのスキャン

-scan:File

カスタム データ型などの構成データを、構成ファイルではないファイルとdefaultwpp.iniで検索します。

構成データの周囲に begin_wpp config と end_wpp 文字列を配置して、識別します。 defaultwpp.iniで使用されるのと同じ形式を構成データに使用します。

構成データをカスタム構成ファイルに追加した場合は、 -ini パラメーターを使用します。

代替構成ファイル

-defwpp:path

代替構成ファイルを指定します。 Wpp では、defaultwpp.ini ファイルの代わりにこのファイルが使用されます。

その他の構成ファイル

-ini:Path

追加の構成ファイルを指定します。 WPP では、既定のファイルdefaultwpp.iniに加えて、指定したファイルが使用されます。

トレース用の構成データを格納する新しい構成ファイルを作成した場合は、このパラメーターを使用します。 構成データをソース ファイルやヘッダー ファイルなどの別の種類のファイルに追加した場合は、 -scan パラメーターを使用します。

WPP ビルド プロセス

ドライバーまたはユーザー モード アプリケーションに対して WPP が有効になっている場合、ドライバーまたはアプリケーションをビルドすると、ドライバーまたはアプリケーション ファイルがコンパイルされる前に WPP プリプロセッサが呼び出されます。

WPP ビルド プロセスは次のプロセスを完了します。

  1. WPP プリプロセッサは、各ソース ファイルの WPP マクロを 処理し、各ソース ファイルの トレース メッセージ ヘッダー ファイル を作成します。 ソース コードは直接変更されません。

  2. WPP プリプロセッサがトレース メッセージ ヘッダー ファイルを作成した後、C プリプロセッサは、トレース メッセージ ヘッダー ファイル内の組み込みの WPP マクロを通常の方法で処理します。