Спецификация языка 1

Замечание

В этом разделе описывается внутренняя операция SrcSrv. Общие сведения о работе путей к источнику см. в разделе "Путь к источнику". Дополнительные сведения об использовании SrcSrv см. в разделе Using 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-файла. Эта переменная является необязательной.

Раздел [переменных] блока данных содержит переменные, которые описывают, как извлечь файл из системы контроля версий. Его также можно использовать для определения часто используемого текста в качестве переменных для уменьшения размера блока данных.

SRCSRVTRG
Описывает, как создать целевой путь для извлеченного файла. Это обязательная переменная.

SRCSRVCMD
Описывает, как создать команду для извлечения файла из системы контроля версий. Сюда входят имя исполняемого файла и его параметры командной строки. Это необходимо, если необходимо выполнить любую команду извлечения.

SRCSRVENV
Перечисляет переменные среды, которые необходимо создать во время извлечения файла. Это строка. Разделите несколько записей с символом backspace (\b). Это необязательная переменная.

SRCSRVVERCTRL
Указывает используемую систему управления версиями. Для 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

Все будущие попытки получить источник с помощью записи файла, содержащей "TOOLS_PRJ" в переменной 2, обходятся.

Вы также можете добавить индикаторы ошибок на клиент отладчика, изменив Srcsrv.ini. Дополнительные сведения см. в прилагаемом образце версии srcsrv.ini.