语言规范 1

注意

本主题介绍 SrcSrv 的内部操作。 有关源路径工作原理的一般信息，请参阅 源路径。 有关使用 SrcSrv 的信息，请参阅 使用 SrcSrv。 若要确定环境中源加载的当前操作，请启用干扰源加载，如 .srcnoisy (干扰源加载)

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 

假设源代码管理系统使用 @ 符号来指示标签，则你可以如下所示修改 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。