ソース サーバー

ソース サーバー を使用すると、クライアントは、アプリケーションのビルドに使用されたソース ファイルの正確なバージョンを取得できます。 モジュールのソース コードはバージョン間で、また何年にもわたって変更される可能性があるため、問題のモジュールのバージョンが構築されたときに存在していたソース コードを確認することが重要です。

ソース サーバーは、ソース管理から適切なファイルを取得します。 ソース サーバーを使用するには、アプリケーションにソース インデックスが作成されている必要があります。

ソースのインデックス作成

ソース インデックス作成システムは、実行可能ファイルと Perl スクリプトのコレクションです。 Perl スクリプトには Perl 5.6 以上が必要です。

一般に、バイナリは、アプリケーションのビルド後にビルド プロセス中にソースインデックスが作成されます。 ソース サーバーで必要な情報は、PDB ファイルに格納されます。

現在、ソース サーバーには、次のソース管理システムで動作する必要があるスクリプトが付属しています。

• Team Foundation Server
• Perforce
• Visual SourceSafe
• CVS
• Subversion

別のソース管理システムのコードにインデックスを付けるカスタム スクリプトを作成することもできます。

次の表に、ソース サーバー ツールの一覧を示します。

ソース ファイルの取得

DbgHelp API は、SymGetSourceFile 関数を介してソース サーバー機能へのアクセスを提供します。 取得するソース ファイルの名前を取得するには、SymEnumSourceFiles 関数または SymGetLineFromAddr64 関数を呼び出します。

デバッガーでのソース サーバーの使用

WinDbg、KD、NTSD、または CDB でソース サーバーを使用するには、最新バージョンの Windows 用デバッグ ツール パッケージ (バージョン 6.3 以降) がインストールされていることを確認してください。 次に、次のように .srcpath コマンドに srv* を含めます。

.srcpath srv*;c:\mysource

この例には、従来のソース パスも含まれていることに注意してください。 デバッガーがソース サーバーからファイルを取得できない場合は、指定したパスが検索されます。

ソース サーバーによってソース ファイルが取得された場合、デバッグ セッションが終了すると、ハード ドライブにメインされます。 ソース ファイルは、Debugging Tools for Windows インストール ディレクトリの src サブディレクトリにローカルに格納されます。

ソース サーバー データ ブロック

ソース サーバーは、PDB ファイル内の 2 つのデータ ブロックに依存します。

• ソース ファイル リスト。 モジュールをビルドすると、モジュールのビルドに使用されるソース ファイルへの完全修飾パスの一覧が自動的に作成されます。
• データ ブロック。 前述のようにソースにインデックスを付けると、「srcsrv」という名前の PDB ファイルに代替ストリームが追加されます。 このデータを挿入するスクリプトは、使用中の特定のビルド プロセスとソース管理システムに依存します。

言語仕様バージョン 1 では、データ ブロックは、ini、変数、ソース ファイルの 3 つのセクションに分割されています。 構文は次のとおりです。

SRCSRV: ini ------------------------------------------------ 
VERSION=1
VERCTRL=<source_control_str>
DATETIME=<date_time_str>
SRCSRV: variables ------------------------------------------ 
SRCSRVTRG=%sdtrg% 
SRCSRVCMD=%sdcmd% 
SRCSRVENV=var1=string1\bvar2=string2 
DEPOT=//depot 
SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%
SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%) 
WIN_SDKTOOLS= sserver.microsoft.com:4444 
SRCSRV: source files --------------------------------------- 
<path1>*<var2>*<var3>*<var4> 
<path2>*<var2>*<var3>*<var4> 
<path3>*<var2>*<var3>*<var4> 
<path4>*<var2>*<var3>*<var4> 
SRCSRV: end ------------------------------------------------

パーセント記号 (%) で囲まれたテキストを除き、すべてのテキストはリテラルで解釈されます。 パーセント記号で囲まれたテキストは、次のいずれかの関数でない限り、再帰的に解決される変数名として扱われます。

%fnvar%()

パラメーター テキストはパーセント記号で囲み、展開する変数として扱う必要があります。

%fnbksl%()

パラメーター テキスト内のすべてのスラッシュ (/) は、後方スラッシュ (\) に置き換える必要があります。

%fnfile%()

パラメーター テキスト内のすべてのパス情報を削除し、ファイル名のみを残す必要があります。

ini セクションには、要件を記述する変数が含まれています。 インデックス作成スクリプトは、このセクションに任意の数の変数を追加できます。 エントリにはたとえば次のような種類があります。

VERSION

言語仕様のバージョン。 この変数は必須です。

VERCTL

ソース管理製品を記述する文字列。 この変数は省略可能です。

DATETIME

PDB ファイルが処理された日時を示す文字列。 この変数は省略可能です。

変数セクションには、ソース管理からファイルを抽出する方法を説明する変数が含まれています。 また、一般的に使用されるテキストを変数として定義して、データ ブロックのサイズを小さくすることもできます。

SRCSRVTRG

抽出されたファイルのターゲット パスを作成する方法について説明します。 これは必須の変数です。

SRCSRVCMD

ソース管理からファイルを抽出するコマンドをビルドする方法について説明します。 これには、実行可能ファイルの名前とそのコマンド ライン パラメーターが含まれます。 これは必須の変数です。

SRCSRVENV

ファイル抽出中に作成される環境変数をリストする文字列。 複数のエントリをバックスペース文字 (\b) で区切ります。 これは省略可能な変数です。

ソース ファイル セクションには、インデックスが作成された各ソース ファイルのエントリが含まれています。 各行の内容は、VAR10 まで VAR1、VAR2、VAR3 などの名前の変数として解釈されます。 変数はアスタリスクで区切られます。 VAR1 には、PDB ファイル内の他の場所にリストされているソース ファイルへの完全修飾パスを指定する必要があります。 たとえば、次の行は、

c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3

次のように解釈されます。

VAR1=c:\proj\src\file.cpp
VAR2=TOOLS_PRJ
VAR3=tools/mytool/src/file.cpp
VAR4=3

この例では、VAR4 はバージョン番号です。 ただし、ほとんどのソース管理システムは、特定のビルドのソース状態を復元できるようにファイルのラベル付けをサポートしています。 そのため、代わりにビルドのラベルを使用することもできます。 サンプル データ ブロックは、次のような変数を含むよう変更できます。

LABEL=BUILD47

次に、ソース管理システムがアットマーク (@) を使用してラベルを示していると仮定して、SRCSRVCMD 変数を次のように変更できます。

sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%

ソース サーバーのしくみ

ソース サーバー クライアントは、Symsrv.dll に実装されます。 クライアントは PDB ファイルから直接情報を抽出しません。 Dbghelp.dll に実装されているようなシンボル ハンドラーを使用します。 これは本質的に、ソース管理システムから適切なソース ファイルを抽出するために使用できるコマンド ラインを作成する再帰的変数置換エンジンです。 コードでは SYSrv.dll を直接呼び出さないでください。 その機能をアプリケーションに統合するには、SymGetSourceFile 関数を使用します。

ソース サーバーの最初のバージョンは次のように動作します。 この動作は将来のバージョンで変更される可能性があります。

• クライアントは、ターゲット パスを使用して SrcSrvInit 関数を呼び出し、すべてのソース ファイル抽出のベースとして使用します。 このパスは TARG 変数に格納されます。
• クライアントは、モジュール PDB が読み込まれるときに PDB から Srcsrv ストリームを抽出し、SrcSrvLoadModule 関数を呼び出してデータ ブロックをソース サーバーに渡します。
• Dbghelp がソース ファイルを取得すると、クライアントは SrcSrvGetFile 関数を呼び出してソース管理からソース ファイルを取得します。
• ソース サーバーは、データ ブロック内のソース ファイル エントリで、要求されたファイルと一致するエントリを検索します。 VAR1 から VARn にソース ファイル エントリの内容が入力されます。 次に、VAR1 を使用して SRCSRVTRG 変数を VARn に拡張します。 ファイルが既にこの場所にある場合は、呼び出し元に場所を返します。 それ以外の場合は、SRCSRVCMD 変数を展開して、ソース管理からファイルを取得し、ターゲットの場所にコピーするために必要なコマンドを構築します。 最後に、このコマンドを実行します。

ソース管理プロバイダー モジュールの作成

ソース サーバーには、Perforce (p4.pm) と Visual Source セーフ (vss.pm) のプロバイダー モジュールが含まれています。 独自のプロバイダー モジュールを作成するには、次のインターフェイスのセットを実装する必要があります。

$module::SimpleUsage()

目的: STDOUT に単純なモジュール使用状況情報を表示します。

パラメーター: なし

戻り値: なし

$module::VerboseUsage()

目的: 詳細なモジュール使用情報を STDOUT に表示します。

パラメーター: なし

戻り値: なし

$objref = $module::new(@CommandArguments)

目的: プロバイダー モジュールのインスタンスを初期化します。

パラメーター: SSIndex.cmdによって一般的な引数として認識されなかったすべての @ARGV 引数。

戻り値: 後の操作で使用できる参照。

$objref->GatherFileInformation($SourcePath, $ServerHashReference)

目的: モジュールが、$SourcePath パラメーターで指定されたディレクトリに必要なソース インデックス情報を収集できるようにします。 SSIndex.cmd は異なるパスに対してこのエントリを複数回呼び出す可能性があるため、モジュールはこのエントリがオブジェクト インスタンスごとに 1 回だけ呼び出されると想定すべきではありません。

パラメーター: (1) インデックスを作成するソースを含むローカル ディレクトリ。 (2) 指定した Srcsrv.ini ファイルのすべてのエントリを含むハッシュへの参照。

戻り値: なし

($VariableHashReference, $FileEntry) = $objref->GetFileInfo($LocalFile)

目的: ソース管理システムから 1 つの特定のファイルを抽出するために必要な情報を提供します。

パラメーター: 完全修飾ファイル名

戻り値: (1) 返された $FileEntry を解釈するために必要な変数のハッシュ参照。 SSIndex.cmd は、単一のデバッグ ファイルで使用されるソース ファイルごとにこれらの変数をキャッシュし、ソース インデックス ストリームに書き込まれる情報の量を削減します。 (2) SrcSrv.dll がソース管理からこのファイルを抽出できるようにするために、ソース インデックス ストリームに書き込まれるファイル エントリ。 この行の正確な形式は、ソース管理システムに固有です。

$TextString = $objref->LongName()

目的: エンド ユーザーにソース管理プロバイダーを識別するための説明文字列を提供します。

パラメーター: なし

戻り値: ソース管理システムのわかりやすい名前。

@StreamVariableLines = $objref->SourceStreamVariables()

目的: ソース管理プロバイダーが、各デバッグ ファイルのソース ストリームにソース管理固有の変数を追加できるようにします。 サンプル モジュールでは、このメソッドを使用して、必要な EXTRACT_CMD 変数および EXTRACT_TARGET 変数を書き込みます。

パラメーター: なし

戻り値: ソース ストリーム変数のエントリの一覧。