语言规范 1

SrcSrv 的第一个版本如下所示。 （此行为可能会在将来的版本中发生更改。

首先，客户端调用 SrcSrvInit ，并将目标路径用作所有源文件提取的基础。 此路径存储在特殊变量 TARG 中。

当 DbgHelp 加载模块的 .pdb 文件时，它将从 .pdb 文件中提取 SrcSrv 流，并通过调用 SrcSrvLoadModule 将此数据块传递给 SrcSrv。

然后，当 DbgHelp 需要获取源文件时，它会调用 SrcSrvGetFile 从版本控制检索指定的源文件。

SrcSrv 检查数据块中的所有源文件条目，以获取与所请求的源规范完全匹配的条目。 此匹配在 VAR1 中找到。

在 SrcSrv 找到条目后，它会用此源文件条目的内容填充特殊变量（VAR1、VAR2 等）。 然后使用这些特殊变量解析 SRCSRVTRG 变量。

下面展示了如何使用特殊变量解析 SRCSRVTRG 变量。 我们假设源路径仍为：

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

每行显示一个特殊变量的分辨率。 解析的变量为粗体。

SRCSRVTRG=%sdtrg% 
SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\%fnbksl%( sdktools/debuggers/srcsrv/shell.cpp )\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\ sdktools\debuggers\srcsrv\shell.cpp\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%( c:\db\srcsrv\shell.cpp)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp

请注意，生成的目标路径是唯一的，不允许将同一文件的两个版本提取到同一位置。

SrcSrv 现在将查看文件是否已存在。 如果是，SrcSrv 会将位置返回到调用方。 否则，SrcSrv 通过解析 SRCSRVCMD 生成执行命令以提取文件。

在以下示例中，每行显示一个特殊变量的分辨率。 解析的变量为粗体。

DEPOT=//depot 
WIN_SDKTOOLS= sserver.microsoft.com:4444 
SRCSRVCMD=%sdcmd% 
SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4% 
sd.exe -p %fnvar%(WIN_SDKTOOLS) print -o %srcsrvtrg% -q %depot%/%var3%#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o %srcsrvtrg% -q %depot%/%var3%#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q %depot%/%var3%#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/%var3%#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#3 

现在 SrcSrv 执行此命令。 如果此命令的结果是预期位置中的文件，则此路径将返回到调用方。

请注意，如果无法解析变量，则会尝试将其查找为 OS 环境变量。 如果失败，将从正在处理的文本中删除变量名称。

连续两个百分比符号字符被解释为单一百分比符号。

源服务器数据块

SrcSrv 依赖于 .pdb 文件中的两个数据块、源文件列表和数据块。

生成模块时，将自动创建源文件列表。 此列表包含用于生成模块的源文件的完全限定路径。

数据块是在源索引期间创建的。 此时，名为“srcsrv”的备用流将添加到 .pdb 文件中。 插入此数据的脚本依赖于正在使用的特定生成过程和源代码管理系统。

数据块分为三个部分：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] 节包含描述要求的变量。 索引脚本可以将任意数量的变量添加到此部分。 下面是一些示例：

版本
语言规范版本。 此变量是必需的。 如果基于当前语言规范开发脚本，请将此值设置为 1。 SrcSrv 客户端代码不会尝试执行任何值大于其自己的值的脚本。 SrcSrv 的当前版本使用值 2。

VERCTRL
描述源版本控制系统的字符串。 此变量是可选的。

DATETIME
一个字符串，指示处理 .pdb 文件的日期和时间。 此变量是可选的。

数据块的 [variables] 节包含描述如何从源代码管理中提取文件的变量。 它还可用于将常用文本定义为变量，以减少数据块的大小。

SRCSRVTRG
介绍如何为提取的文件生成目标路径。 这是必需的变量。

SRCSRVCMD
介绍如何生成命令以从源代码管理中提取文件。 这包括可执行文件的名称及其命令行参数。 如果必须执行任何提取命令，则需要执行此作。

SRCSRVENV
列出在文件提取过程中要创建的环境变量。 这是一个字符串。 用后空字符（\b）分隔多个条目。 这是一个可选变量。

SRCSRVVERCTRL
指定正在使用的版本控制系统。 对于 Perforce，这就是 Perforce。 对于 Team Foundation Server，缩写为 TFS。 此变量用于保存服务器错误。 这是一个可选变量。

SRCSRVVERRDESC
指定要在版本控制客户端无法联系包含要提取的源文件的服务器时显示的文本。 SrcSrv 使用此值检查连接问题。 这是一个可选变量。

SRCSRVERRVAR
指示文件条目中的哪个变量对应于版本控制服务器。 SrcSrv 使用它来根据以前的失败来标识不起作用的命令。 文本的格式为 varX ，其中 X 是所指示变量的数目。 这是一个可选变量。

数据块的 [源文件] 节包含已编制索引的每个源文件的条目。 每行的内容被解释为名为 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%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%

处理服务器错误

有时，客户端无法从单个版本控制服务器提取任何文件。 原因可能是服务器已关闭和关闭网络，或者用户没有访问源的适当权限。 但是，尝试获取此源所花费的时间可能会显著降低处理速度。 在这种情况下，最好禁用任何尝试从已被证明不可用的源中提取数据。

每当 SrcSrv 无法提取文件时，它将检查命令生成的输出文本。 如果此命令中有任何部分与 SRCSRVERRDESC 的内容完全匹配，则后续对同一版本控制服务器的所有命令将被跳过。 请注意，可以通过向 SRCSRVERRDESC 变量名称末尾添加数字或任意文本来定义多个错误字符串。 下面是一个示例：

SRCSRVERRDESC=lime: server not found
SRCSRVERRDESC_2=pineapple: network error

从变量 SRCSRVERRVAR 获取服务器的标识。 因此，如果 SRCSRVERRVAR 包含“var2”，并且 .pdb 文件中的文件条目如下所示：

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

所有未来使用变量 2 中包含“TOOLS_PRJ”的文件条目获取源的尝试将被绕过。

还可以通过编辑 Srcsrv.ini在调试器客户端上添加错误指示器。 有关详细信息，请参阅 srcsrv.ini 包含的示例版本。