來源伺服器

  • 發行項

來源伺服器可讓用戶端擷取用來建置應用程式之原始程式檔的確切版本。 因為模組的原始程式碼可以在版本之間變更，而且一段時間后，請務必在建置有問題的模組版本時查看原始程式碼。

來源伺服器會從原始檔控制擷取適當的檔案。 若要使用來源伺服器，應用程式必須已編製來源索引。

來源索引編製

來源索引系統是可執行檔和 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 保管庫）。如需詳細資訊，請使用 -？ 執行腳本？ 或-?? （詳細資訊說明） 選項或檢查文稿。
Srctool.exe 此公用程式會列出在 .pdb 檔案內編製索引的所有檔案。 針對每個檔案，它會列出檔案的完整路徑、原始檔控制伺服器和版本號碼。 您可以使用這項資訊來擷取檔案，而不使用來源伺服器。如需詳細資訊，請使用 /？ 執行 公用程式？ 選項。
Pdbstr.exe 索引腳本會使用此公用程式，將版本控制資訊插入目標 .pdb 檔案的 “srcsrv” 替代數據流中。 它也可以從 .pdb 檔案讀取任何數據流。 您可以使用這項資訊來驗證索引腳本是否正常運作。如需詳細資訊，請使用 /？ 執行 公用程式？ 選項。

 

擷取來源檔案

DbgHelp API 可透過 SymGetSourceFile 函式來存取來源伺服器功能。 若要擷取要擷取的來源檔名，請呼叫 SymEnumSourceFiles 或 SymGetLineFromAddr64 函式。

搭配調試程式使用來源伺服器

若要搭配 WinDbg、KD、NTSD 或 CDB 使用來源伺服器，請確定您已安裝最新版的 Windows 套件偵錯工具（6.3 版或更新版本）。 然後，在 .srcpath 命令中包含 srv* ，如下所示：

.srcpath srv*;c：\mysource

請注意，此範例也包含傳統的來源路徑。 如果調試程式無法從來源伺服器擷取檔案，它會搜尋指定的路徑。

如果來源伺服器擷取來源檔案，偵錯會話結束之後，它將會保留在硬碟上。 來源檔案會儲存在 Windows 安裝目錄偵錯工具的 src 子目錄中。

源伺服器數據區塊

來源伺服器依賴 PDB 檔案內的兩個數據區塊。

  • 來源檔案清單。 建置模組會自動建立用來建置模組之原始程序檔的完整路徑清單。
  • 數據區塊。 如先前所述，為來源編製索引，將替代數據流新增至名為 “srcsrv” 的 PDB 檔案。 插入此資料的文稿取決於使用中的特定建置程式和原始檔控制系統。

在語言規格第 1 版中，數據區塊分成三個區段：ini、變數和來源檔案。 它有下列語法。

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）。 這是選擇性變數。

原始程式檔區段包含已編製索引之每個原始程式檔的專案。 每個行的內容都會解譯為名稱為 VAR1、VAR2、VAR3 等等的變數，直到 VAR10 為止。 變數會以星號分隔。 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

然後，假設原始檔控制系統使用 at sign （@） 來指出標籤，您可以修改 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 保管庫 （vss.pm） 的提供者模組。 若要建立您自己的提供者模組，您必須實作下列一組介面。

$module：：SimpleUsage（）

目的：對 STDOUT 顯示簡單的模組使用資訊。

參數：無

傳回值：無

$module：：VerboseUsage（）

目的：向 STDOUT 顯示深入模組使用資訊。

參數：無

傳回值：無

$objref = $module：：new（@CommandArguments）

目的：初始化提供者模組的實例。

參數:SSIndex.cmd無法辨識為一般自變數的所有 @ARGV 自變數。

傳回值：可用於後續作業的參考。

$objref-GatherFileInformation>（$SourcePath，$ServerHashReference）

目的：讓模組能夠收集 $SourcePath 參數所指定目錄所需的來源索引資訊。 模組不應該假設每個物件實例只會呼叫此專案一次，因為SSIndex.cmd可能會針對不同的路徑多次呼叫它。

參數：（1） 包含要編製索引來源的本機目錄。 （2） 包含指定Srcsrv.ini檔案中所有專案的哈希參考。

傳回值：無

（$VariableHashReference，$FileEntry） = $objref-GetFileInfo>（$LocalFile）

目的：提供從原始檔控制系統擷取單一特定檔案的必要資訊。

參數：完整檔名

傳回值：（1） 解譯傳回$FileEntry所需變數的哈希參考。 SSIndex.cmd針對單一偵錯檔案所使用的每個來源檔案快取這些變數，以減少寫入來源索引數據流的資訊量。 （2） 要寫入來源索引數據流的檔案專案，以允許SrcSrv.dll從原始檔控制擷取此檔案。 此行的確切格式專屬於原始檔控制系統。

$TextString = $objref-LongName>（）

目的：提供描述性字串，以識別使用者的原始檔控制提供者。

參數：無

傳回值：原始檔控制系統的描述性名稱。

@StreamVariableLines = $objref-SourceStreamVariables>（）

目的：可讓原始檔控制提供者將原始檔控制特定變數新增至每個偵錯檔案的來源數據流。 範例模組會使用這個方法來撰寫必要的EXTRACT_CMD和EXTRACT_TARGET變數。

參數：無

傳回值：來源數據流變數的項目清單。