ソース サーバー
ソース サーバーを使用すると、クライアントは、アプリケーションのビルドに使用されたソース ファイルの正確なバージョンを取得できます。 モジュールのソース コードはバージョン間で変更される可能性があるため、問題のモジュールのバージョンがビルドされたときに存在していたソース コードを確認することが重要です。
ソース サーバーは、ソース管理から適切なファイルを取得します。 ソース サーバーを使用するには、アプリケーションにソース インデックスが作成されている必要があります。
ソース インデックス作成
ソース インデックス作成システムは、実行可能ファイルと Perl スクリプトのコレクションです。 Perl スクリプトには Perl 5.6 以上が必要です。
一般に、バイナリは、アプリケーションのビルド後にビルド プロセス中にソースインデックスが作成されます。 ソース サーバーで必要な情報は、PDB ファイルに格納されます。
現在、ソース サーバーには、次のソース管理システムで動作する必要があるスクリプトが付属しています。
- Team Foundation Server
- Perforce
- Visual SourceSafe
- CVS
- Subversion
別のソース管理システムのコードにインデックスを付けるカスタム スクリプトを作成することもできます。
次の表に、ソース サーバー ツールの一覧を示します。
道具 | 形容 |
---|---|
Srcsrv.ini | このファイルは、すべてのソース管理サーバーのマスター リストです。 各エントリの形式は次のとおりです。MYSERVER=serverinfo Perforce を使用する場合、サーバー情報は、サーバーへの完全なネットワーク パスの後にコロンが続き、その後に使用されるポート番号で構成されます。 例えば: MYSERVER=machine.corp.company.com:1666 このファイルは、デバッガーを実行しているコンピューターにインストールできます。 ソース サーバーが起動すると、Srcsrv.ini で値が検索されます。これらの値は、PDB ファイルに含まれる情報をオーバーライドします。 これにより、ユーザーはデバッグ時に代替ソース管理サーバーを使用するようにデバッガーを構成できます。 詳細については、ソース サーバー ツールと共にインストール Srcsrv.ini 例を参照してください。 |
Ssindex.cmd | このスクリプトは、ソース管理にチェックインされたファイルの一覧と、各ファイルのバージョン情報をビルドします。 この情報のサブセットは、アプリケーションのビルド時に生成された .pdb ファイルに格納されます。 このスクリプトでは、次のいずれかの Perl モジュールを使用して、P4.pm (Perforce) または Vss.pm (Visual Source Safe) のソース管理とインターフェイスします。詳細については、-? を使用してスクリプトを実行します。 又は-。。 (詳細ヘルプ) オプションを選択するか、スクリプトを確認します。 |
Srctool.exe | このユーティリティは、.pdb ファイル内でインデックスが作成されたすべてのファイルを一覧表示します。 ファイルごとに、ファイルの完全なパス、ソース管理サーバー、およびバージョン番号が一覧表示されます。 この情報を使用すると、ソース サーバーを使用せずにファイルを取得できます。詳細については、/? を使用してユーティリティを実行します。 オプション。 |
Pdbstr.exe | このユーティリティは、インデックス作成スクリプトによって、ターゲット .pdb ファイルの "srcsrv" 代替ストリームにバージョン 管理情報を挿入するために使用されます。 また、.pdb ファイルから任意のストリームを読み取ることもできます。 この情報を使用して、インデックス作成スクリプトが正常に動作していることを確認できます。詳細については、/? を使用してユーティリティを実行します。 オプション。 |
ソース ファイルの取得
DbgHelp API は、SymGetSourceFile 関数を使用してソース サーバー機能にアクセスできるようにします。 取得するソース ファイルの名前を取得するには、SymEnumSourceFilesを呼び出すか、SymGetLineFromAddr64関数呼び出します。
デバッガーでのソース サーバーの使用
WinDbg、KD、NTSD、または CDB でソース サーバーを使用するには、最新バージョンの Debugging Tools for Windows パッケージ (バージョン 6.3 以降) がインストールされていることを確認します。 次に、次のように .srcpath コマンドに srv* を含めます。
.srcpath srv*;c:\mysource
この例には、従来のソース パスも含まれていることに注意してください。 デバッガーがソース サーバーからファイルを取得できない場合は、指定したパスが検索されます。
ソース サーバーによって取得されたソース ファイルは、デバッグ セッションが終了した後もハード ドライブ上に残ります。 ソース ファイルは、Debugging Tools for Windows インストール ディレクトリの src サブディレクトリにローカルに格納されます。
ソース サーバー データ ブロック
ソース サーバーは、PDB ファイル内の 2 つのデータ ブロックに依存します。
- ソース ファイルの一覧。 モジュールをビルドすると、モジュールのビルドに使用されるソース ファイルへの完全修飾パスの一覧が自動的に作成されます。
- データ ブロック。 前述のようにソースのインデックスを作成すると、"srcsrv" という名前の PDB ファイルに代替ストリームが追加されます。 このデータを挿入するスクリプトは、使用中の特定のビルド プロセスとソース管理システムに依存します。
言語仕様バージョン 1 では、データ ブロックは ini、variables、source ファイルの 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 セクションには、要件を記述する変数が含まれています。 インデックス作成スクリプトは、このセクションに任意の数の変数を追加できます。 次に例を示します。
-
バージョン
-
言語仕様のバージョン。 この変数は必須です。
-
VERCTL の
-
ソース管理製品を記述する文字列。 この変数は省略可能です。
-
DATETIME の
-
PDB ファイルが処理された日時を示す文字列。 この変数は省略可能です。
variables セクションには、ソース管理からファイルを抽出する方法を説明する変数が含まれています。 また、一般的に使用されるテキストを変数として定義して、データ ブロックのサイズを小さくすることもできます。
-
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%) 印刷 -o %srcsrvtrg% -q %depot%/%var3%@%label%
ソース サーバーのしくみ
ソース サーバー クライアントは、Symsrv.dllに実装されます。 クライアントは PDB ファイルから直接情報を抽出しません。Dbghelp.dllで実装されているようなシンボル ハンドラーを使用します。 これは基本的に、ソース管理システムから適切なソース ファイルを抽出するために使用できるコマンド ラインを作成する再帰変数置換エンジンです。 コードで Symsrv.dll を直接呼び出さないでください。 その機能をアプリケーションに統合するには、SymGetSourceFile 関数を使用します。
ソース サーバーの最初のバージョンは次のように動作します。 この動作は、将来のバージョンで変更される可能性があります。
- クライアントは SrcSrvInit 関数を呼び出し、ターゲット パスを使用して、すべてのソース ファイル抽出のベースとして使用します。 このパスは TARG 変数に格納されます。
- クライアントは、モジュール PDB が読み込まれるときに PDB から Srcsrv ストリームを抽出し、SrcSrvLoadModule 関数を呼び出して、データ ブロックをソース サーバーに渡します。
- Dbghelp がソース ファイルを取得すると、クライアントは srcSrvGetFile 関数 呼び出してソース管理からソース ファイルを取得します。
- ソース サーバーは、データ ブロック内のソース ファイル エントリで、要求されたファイルと一致するエントリを検索します。 VAR1 から VARn にソース ファイル エントリの内容が入力されます。 次に、VAR1 を使用して SRCSRVTRG 変数を varn展開します。 ファイルが既にこの場所にある場合は、呼び出し元に場所を返します。 それ以外の場合は、SRCSRVCMD 変数を展開して、ソース管理からファイルを取得してターゲットの場所にコピーするために必要なコマンドをビルドします。 最後に、このコマンドを実行します。
ソース管理プロバイダー モジュールの作成
ソース サーバーには、Perforce (p4.pm) と Visual Source Safe (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は、ソース インデックス ストリームに書き込まれる情報の量を減らすために、1 つのデバッグ ファイルで使用されるすべてのソース ファイルに対してこれらの変数をキャッシュします。 (2) ソース 管理からこのファイルを抽出できるように、ソース インデックス ストリームに書き込むファイル エントリ SrcSrv.dll。 この行の正確な形式は、ソース管理システムに固有です。
-
$TextString = $objref- LongName()>
-
目的: エンド ユーザーにソース管理プロバイダーを識別するための説明文字列を提供します。
パラメーター: なし
戻り値: ソース管理システムのわかりやすい名前。
-
@StreamVariableLines = $objref->SourceStreamVariables()
-
目的: ソース管理プロバイダーが、各デバッグ ファイルのソース ストリームにソース管理固有の変数を追加できるようにします。 サンプル モジュールでは、このメソッドを使用して、必要なEXTRACT_CMDとEXTRACT_TARGET変数を記述します。
パラメーター: なし
戻り値: ソース ストリーム変数のエントリの一覧。