Спецификация языка 1
Примечание
В этом разделе описывается внутренняя операция SrcSrv. Общие сведения о работе исходных путей см. в разделе Исходный путь. Сведения об использовании SrcSrv см. в разделе Использование SrcSrv. Чтобы определить текущую операцию загрузки источника в вашей среде, включите шумную загрузку источника, как описано в разделе .srcnoisy (шумная загрузка источника).
Первая версия SrcSrv работает следующим образом. (Это поведение может измениться в будущих версиях.)
Во-первых, клиент вызывает SrcSrvInit с целевым путем, который будет использоваться в качестве основы для всех извлечений исходных файлов. Этот путь хранится в специальной переменной TARG.
Когда DbgHelp загружает PDB-файл модуля, он извлекает поток SrcSrv из PDB-файла и передает этот блок данных в SrcSrv путем вызова SrcSrvLoadModule.
Затем, когда 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 выполняет эту команду. Если результатом выполнения этой команды является файл в ожидаемом расположении, этот путь возвращается вызывающей объекту.
Обратите внимание, что если не удается разрешить переменную, предпринимается попытка найти ее как переменную среды ОС. Если это не удается, имя переменной удаляется из обрабатываемого текста.
Два последовательных знака процента интерпретируются как один знак процента.
Блоки данных исходного сервера
SrcSrv использует два блока данных в PDB-файле: список исходных файлов и блок данных.
Список исходных файлов создается автоматически при сборке модуля. Этот список содержит полные пути к исходным файлам, используемым для сборки модуля.
Блок данных создается во время индексирования источника. В настоящее время в PDB-файл добавляется альтернативный поток с именем srcsrv. Скрипт, который вставляет эти данные, зависит от конкретного процесса сборки и используемой системы управления версиями.
Блок данных состоит из трех разделов: 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
Список переменных среды, создаваемых во время извлечения файла. Это строка. Разделите несколько записей символом backspace (\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 (@) для обозначения метки, можно изменить переменную 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
Все последующие попытки получить источник с помощью записи файла, содержащей "TOOLS_PRJ" в переменной 2, пропускаются.
Вы также можете добавить индикаторы ошибок в клиенте отладчика, изменив Srcsrv.ini. Дополнительные сведения см. в примере версии srcsrv.ini.