Исходный сервер

Исходный сервер позволяет клиенту получить точную версию исходных файлов, которые использовались для создания приложения. Так как исходный код модуля может меняться между версиями и в течение нескольких лет, важно взглянуть на исходный код, так как он существовал при создании версии модуля.

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

Индексирование источника

Исходная система индексирования — это коллекция исполняемых файлов и скриптов Perl. Для сценариев Perl требуется Perl 5.6 или более поздней версии.

Как правило, двоичные файлы индексируются в процессе сборки после создания приложения. Сведения, необходимые исходному серверу, хранятся в PDB-файлах.

Исходный сервер в настоящее время поставляется со скриптами, которые должны работать со следующими системами управления версиями.

• Team Foundation Server
• Perforce
• Visual SourceSafe
• CVS
• Subversion

Вы также можете создать пользовательский скрипт для индексирования кода для другой системы управления версиями.

В следующей таблице перечислены средства исходного сервера.

Средство	Description
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-файла. Эти сведения можно использовать для проверки правильности работы скриптов индексирования. Дополнительные сведения см. в программе /? предложения.

 

Извлечение исходного файла

API DbgHelp предоставляет доступ к функциям исходного сервера через функцию SymGetSourceFile . Чтобы получить имя извлекаемого исходного файла, вызовите функцию SymEnumSourceFiles или SymGetLineFromAddr64.

Использование исходного сервера с отладчиком

Чтобы использовать исходный сервер с WinDbg, KD, NTSD или CDB, убедитесь, что установлена последняя версия пакета средств отладки для Windows (версия 6.3 или более поздняя). Затем включите srv* в команду Srcpath следующим образом:

.srcpath srv*;c:\mysource

Обратите внимание, что этот пример также включает традиционный исходный путь. Если отладчик не может получить файл с исходного сервера, он будет искать указанный путь.

Если исходный файл извлекается исходным сервером, он останется на жестком диске после завершения сеанса отладки. Исходные файлы хранятся локально в подкаталоге src в каталоге установки средств отладки для Windows.

Блоки данных исходного сервера

Исходный сервер использует два блока данных в файле PDB.

• Список исходных файлов. Создание модуля автоматически создает список полных путей к исходным файлам, используемым для сборки модуля.
• Блок данных. Индексирование источника, как описано ранее, добавляет альтернативный поток в PDB-файл с именем srcsrv. Скрипт, который вставляет эти данные, зависит от конкретного процесса сборки и системы управления версиями, используемой.

В спецификации языка версии 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-файла. Эта переменная является необязательной.

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

SRCSRVTRG

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

SRCSRVCMD

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

SRCSRVENV

Строка, которая перечисляет переменные среды, создаваемые во время извлечения файла. Разделите несколько записей с символом backspace (\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 (@) для указания метки, можно изменить переменную SRCSRVCMD следующим образом:

sd.exe -p %fnvar%(%var2%) печать -o %srcsrvtrg% -q %depot%/%var3%@%label%

Как работает исходный сервер

Клиент исходного сервера реализуется в Symsrv.dll. Клиент не извлекает информацию непосредственно из PDB-файла; в нем используется обработчик символов, например тот, который реализован в Dbghelp.dll. По сути, это подсистема подстановки рекурсивной переменной, которая создает командную строку, которую можно использовать для извлечения правильного исходного файла из системы управления версиями. Код не должен вызывать Symsrv.dll напрямую. Чтобы интегрировать ее функциональные возможности в приложение, используйте функцию SymGetSourceFile .

Первая версия исходного сервера работает следующим образом. Это поведение может измениться в будущих версиях.

• Клиент вызывает функцию SrcSrvInit с целевым путем, который будет использоваться в качестве базы для всех извлечения исходных файлов. Он сохраняет этот путь в переменной TARG.
• Клиент извлекает поток Srcsrv из PDB при загрузке PDB модуля и вызывает функцию SrcSrvLoadModule , чтобы передать блок данных исходному серверу.
• Когда Dbghelp извлекает исходный файл, клиент вызывает функцию SrcSrvGetFile , чтобы получить исходные файлы из системы управления версиями.
• Исходный сервер выполняет поиск записей исходного файла в блоке данных для записи, которая соответствует запрошенным файлам. Он заполняет VAR1 на VARn с содержимым записи исходного файла. Затем он расширяет переменную SRCSRVTRG с помощью VAR1 до VARn. Если файл уже находится в этом расположении, он возвращает расположение вызывающему объекту. В противном случае она расширяет переменную SRCSRVCMD, чтобы создать команду, необходимую для получения файла из системы управления версиями и скопировать его в целевое расположение. Наконец, она выполняет эту команду.

Создание модуля поставщика системы управления версиями

Исходный сервер включает модули поставщика для Perforce (p4.pm) и visual Source Сейф (vss.pm). Чтобы создать собственный модуль поставщика, необходимо реализовать следующий набор интерфейсов.

$module::SimpleUsage()

Назначение. Отображение простых сведений об использовании модуля в STDOUT.

Параметры: нет

Возвращаемое значение: None

$module::VerboseUsage()

Назначение. Отображает подробные сведения об использовании модуля в STDOUT.

Параметры: нет

Возвращаемое значение: None

$objref = $module::new(@CommandArguments)

Назначение. Инициализирует экземпляр модуля поставщика.

Параметры: все @ARGV аргументы, которые не были распознаны SSIndex.cmd как общие аргументы.

Возвращаемое значение: ссылка, которую можно использовать в последующих операциях.

$objref-GatherFileInformation>($SourcePath, $ServerHashReference)

Назначение. Позволяет модулю собирать необходимые сведения об индексировании источника для каталога, указанного параметром $SourcePath. Модуль не должен предполагать, что эта запись будет вызываться только один раз для каждого экземпляра объекта, так как SSIndex.cmd может вызывать ее несколько раз для разных путей.

Параметры: (1) Локальный каталог, содержащий источник для индексирования. (2) Ссылка на хэш, содержащий все записи из указанного Srcsrv.ini файла.

Возвращаемое значение: None

($VariableHashReference, $FileEntry) = $objref-GetFileInfo>($LocalFile)

Назначение. Предоставляет необходимые сведения для извлечения одного конкретного файла из системы управления версиями.

Параметры: полное имя файла

Возвращаемое значение: (1) Хэш-ссылка переменных, необходимых для интерпретации возвращаемого $FileEntry. SSIndex.cmd кэширует эти переменные для каждого исходного файла, используемого одним отладочным файлом, чтобы уменьшить объем данных, записанных в поток исходного индекса. (2) Запись файла, записанная в поток исходного индекса, чтобы разрешить SrcSrv.dll извлечь этот файл из системы управления версиями. Точный формат этой строки зависит от системы управления версиями.

$TextString = $objref-LongName>()

Назначение. Предоставляет описательную строку для идентификации поставщика системы управления версиями для конечного пользователя.

Параметры: нет

Возвращаемое значение: описательное имя системы управления версиями.

@StreamVariableLines = $objref-SourceStreamVariables>()

Назначение. Позволяет поставщику системы управления версиями добавлять определенные переменные системы управления версиями в исходный поток для каждого файла отладки. Примеры модулей используют этот метод для записи необходимых EXTRACT_CMD и EXTRACT_TARGET переменных.

Параметры: нет

Возвращаемое значение: список записей для переменных исходного потока.