Servidor de origen

El servidor de origen permite a un cliente recuperar la versión exacta de los archivos de origen que se usaron para compilar una aplicación. Dado que el código fuente de un módulo puede cambiar entre versiones y durante un transcurso de años, es importante examinar el código fuente tal como existía cuando se compiló la versión del módulo en cuestión.

El servidor de origen recupera los archivos adecuados del control de código fuente. Para usar el servidor de origen, la aplicación debe haberse indexado de origen.

Indexación de origen

El sistema de indexación de origen es una colección de archivos ejecutables y scripts de Perl. Los scripts de Perl requieren Perl 5.6 o superior.

Por lo general, los archivos binarios se indexan de origen durante el proceso de compilación una vez compilada la aplicación. La información necesaria para el servidor de origen se almacena en los archivos PDB.

El servidor de origen se distribuye actualmente con scripts que deben funcionar con los siguientes sistemas de control de código fuente.

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

También puede crear un script personalizado para indexar el código para un sistema de control de código fuente diferente.

En la tabla siguiente se enumeran las herramientas del servidor de origen.

Herramienta	Descripción
Srcsrv.ini	Este archivo es la lista maestra de todos los servidores de control de código fuente. Cada entrada tiene el siguiente formato:MYSERVER=serverinfo Cuando se usa Perforce, la información del servidor consta de la ruta de acceso de red completa al servidor, seguida de dos puntos, seguida del número de puerto que usa. Por ejemplo: MYSERVER=machine.corp.company.com:1666 Este archivo se puede instalar en el equipo que ejecuta el depurador. Cuando se inicia el servidor de origen, examina Srcsrv.ini para los valores; estos valores invalidarán la información contenida en el archivo PDB. Esto permite a los usuarios configurar un depurador para que use un servidor de control de código fuente alternativo en tiempo de depuración. Para obtener más información, vea el ejemplo Srcsrv.ini instalado con las herramientas del servidor de origen.
Ssindex.cmd	Este script compila la lista de archivos protegidos en el control de código fuente junto con la información de versión de cada archivo. Almacena un subconjunto de esta información en los archivos .pdb generados al compilar la aplicación. El script usa uno de los siguientes módulos Perl para interactuar con el control de código fuente: P4.pm (Perforce) o Vss.pm (Visual Source Safe). Para obtener más información, ejecute el script con -? ¿¿O-?? (ayuda detallada) o examine el script.
Srctool.exe	Esta utilidad enumera todos los archivos indexados dentro de un archivo .pdb. Para cada archivo, se muestra la ruta de acceso completa, el servidor de control de código fuente y el número de versión del archivo. Puede usar esta información para recuperar archivos sin usar el servidor de origen. Para obtener más información, ejecute la utilidad con /? .
Pdbstr.exe	Los scripts de indexación usan esta utilidad para insertar la información del control de versiones en la secuencia alternativa "srcsrv" del archivo .pdb de destino. También puede leer cualquier secuencia de un archivo .pdb. Puede usar esta información para comprobar que los scripts de indexación funcionan correctamente. Para obtener más información, ejecute la utilidad con /? .

 

Recuperación del archivo de origen

La API DbgHelp proporciona acceso a la funcionalidad del servidor de origen a través de la función SymGetSourceFile . Para recuperar el nombre del archivo de origen que se va a recuperar, llame a la función SymEnumSourceFiles o SymGetLineFromAddr64 .

Uso del servidor de origen con un depurador

Para usar el servidor de origen con WinDbg, KD, NTSD o CDB, asegúrese de que ha instalado una versión reciente del paquete Herramientas de depuración para Windows (versión 6.3 o posterior). A continuación, incluya srv* en el comando .srcpath de la siguiente manera:

.srcpath srv*;c:\mysource

Tenga en cuenta que en este ejemplo también se incluye una ruta de acceso de origen tradicional. Si el depurador no puede recuperar el archivo del servidor de origen, buscará en la ruta de acceso especificada.

Si el servidor de origen recupera un archivo de origen, permanecerá en el disco duro una vez finalizada la sesión de depuración. Los archivos de origen se almacenan localmente en el subdirectorio src del directorio de instalación de Herramientas de depuración para Windows.

Bloques de datos del servidor de origen

El servidor de origen se basa en dos bloques de datos dentro del archivo PDB.

• Lista de archivos de origen. La creación de un módulo crea automáticamente una lista de rutas de acceso completas a los archivos de origen que se usan para compilar el módulo.
• Bloque de datos. La indexación del origen tal y como se ha descrito anteriormente agrega una secuencia alternativa al archivo PDB denominado "srcsrv". El script que inserta estos datos depende del proceso de compilación específico y del sistema de control de código fuente en uso.

En la versión 1 de la especificación del lenguaje, el bloque de datos se divide en tres secciones: ini, variables y archivos de origen. Tiene la siguiente sintaxis.

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 ------------------------------------------------

Todo el texto se interpreta literalmente, excepto el texto entre signos de porcentaje (%). El texto entre signos de porcentaje se trata como un nombre de variable que se va a resolver de forma recursiva, a menos que sea una de las siguientes funciones:

%fnvar%()

El texto del parámetro debe ir entre signos de porcentaje y tratarse como una variable que se va a expandir.

%fnbksl%()

Todas las barras diagonales (/) del texto del parámetro deben reemplazarse por barras diagonales inversas (\).

%fnfile%()

Toda la información de la ruta de acceso del texto del parámetro debe quitarse, dejando solo el nombre de archivo.

La sección ini contiene variables que describen los requisitos. El script de indexación puede agregar cualquier número de variables a esta sección. A continuación, se muestran algunos ejemplos:

VERSIÓN

Versión de especificación del lenguaje. Esta variable es necesaria.

VERCTL

Cadena que describe el producto de control de código fuente. Esta variable es opcional.

DATETIME

Cadena que indica la fecha y hora en que se procesó el archivo PDB. Esta variable es opcional.

La sección variables contiene variables que describen cómo extraer un archivo del control de código fuente. También se puede usar para definir texto usado habitualmente como variables para reducir el tamaño del bloque de datos.

SRCSRVTRG

Describe cómo compilar la ruta de acceso de destino para el archivo extraído. Se trata de una variable necesaria.

SRCSRVCMD

Describe cómo compilar el comando para extraer el archivo del control de código fuente. Esto incluye el nombre del archivo ejecutable y sus parámetros de línea de comandos. Se trata de una variable necesaria.

SRCSRVENV

Cadena que enumera las variables de entorno que se van a crear durante la extracción de archivos. Separe varias entradas con un carácter de retroceso (\b). Se trata de una variable opcional.

La sección de archivos de origen contiene una entrada para cada archivo de origen que se ha indexado. El contenido de cada línea se interpreta como variables con los nombres VAR1, VAR2, VAR3, etc. hasta VAR10. Las variables están separadas por asteriscos. VAR1 debe especificar la ruta de acceso completa al archivo de origen como se muestra en otra parte del archivo PDB. Por ejemplo, la línea siguiente:

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

se interpreta de la siguiente manera:

VAR1=c:\proj\src\file.cpp
VAR2=TOOLS_PRJ
VAR3=tools/mytool/src/file.cpp
VAR4=3

En este ejemplo, VAR4 es un número de versión. Sin embargo, la mayoría de los sistemas de control de código fuente admiten el etiquetado de archivos de forma que se pueda restaurar el estado de origen de una compilación determinada. Por lo tanto, podría usar alternativamente la etiqueta para la compilación. El bloque de datos de ejemplo se puede modificar para que contenga una variable como la siguiente:

LABEL=BUILD47

A continuación, la enumeración previa del sistema de control de código fuente usa el signo at (@) para indicar una etiqueta, podría modificar la variable SRCSRVCMD de la siguiente manera:

sd.exe -p %fnvar%(%var2%) imprimir -o %srcsrvtrg% -q %depot%/%var3%@%label%

Funcionamiento del servidor de origen

El cliente de servidor de origen se implementa en Symsrv.dll. El cliente no extrae información directamente del archivo PDB; usa un controlador de símbolos como el implementado en Dbghelp.dll. Básicamente, es un motor de sustitución de variables recursiva que crea una línea de comandos que se puede usar para extraer el archivo de código fuente adecuado del sistema de control de código fuente. El código no debe llamar directamente a Symsrv.dll. Para integrar su funcionalidad en la aplicación, use la función SymGetSourceFile .

La primera versión del servidor de origen funciona de la siguiente manera. Este comportamiento puede cambiar en versiones futuras.

• El cliente llama a la función SrcSrvInit con la ruta de acceso de destino que se usará como base para todas las extracciones de archivos de origen. Almacena esta ruta de acceso en la variable TARG.
• El cliente extrae la secuencia Srcsrv de la PDB cuando se carga el módulo PDB y llama a la función SrcSrvLoadModule para pasar el bloque de datos al servidor de origen.
• Cuando Dbghelp recupera un archivo de origen, el cliente llama a la función SrcSrvGetFile para recuperar los archivos de origen del control de código fuente.
• El servidor de origen busca en las entradas del archivo de origen del bloque de datos una entrada que coincida con el archivo solicitado. Rellena VAR1 a VARn con el contenido de la entrada del archivo de origen. A continuación, expande la variable SRCSRVTRG mediante VAR1 a VARn. Si el archivo ya está en esta ubicación, devuelve la ubicación al autor de la llamada. De lo contrario, expande la variable SRCSRVCMD para compilar el comando necesario para recuperar el archivo del control de código fuente y copiarlo en la ubicación de destino. Por último, ejecuta este comando.

Creación de un módulo de proveedor de control de código fuente

El servidor de origen incluye módulos de proveedor para Perforce (p4.pm) y Visual Source Safe (vss.pm). Para crear su propio módulo de proveedor, debe implementar el siguiente conjunto de interfaces.

$module::SimpleUsage()

Propósito: muestra información de uso de módulos sencilla a STDOUT.

Parámetros: None

Valor devuelto: Ninguno

$module::VerboseUsage()

Propósito: muestra información de uso del módulo en profundidad a STDOUT.

Parámetros: None

Valor devuelto: Ninguno

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

Propósito: inicializa una instancia del módulo de proveedor.

Parámetros: todos los @ARGV argumentos no reconocidos por SSIndex.cmd como argumentos generales.

Valor devuelto: referencia que se puede usar en operaciones posteriores.

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

Propósito: permite al módulo recopilar la información de indexación de origen necesaria para el directorio especificado por el parámetro $SourcePath. El módulo no debe suponer que esta entrada se llamará solo una vez para cada instancia de objeto, ya que SSIndex.cmd puede llamarla varias veces para distintas rutas de acceso.

Parámetros: (1) Directorio local que contiene el origen que se va a indexar. (2) Referencia a un hash que contiene todas las entradas del archivo de Srcsrv.ini especificado.

Valor devuelto: Ninguno

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

Propósito: proporciona la información necesaria para extraer un único archivo específico del sistema de control de código fuente.

Parámetros: un nombre de archivo completo

Valor devuelto: (1) Referencia hash de las variables necesarias para interpretar el $FileEntry devuelto. SSIndex.cmd almacena en caché estas variables para cada archivo de origen utilizado por un único archivo de depuración para reducir la cantidad de información escrita en el flujo de índice de origen. (2) Entrada de archivo que se va a escribir en el flujo de índice de origen para permitir que SrcSrv.dll extraiga este archivo del control de código fuente. El formato exacto de esta línea es específico del sistema de control de código fuente.

$TextString = $objref-LongName>()

Propósito: proporciona una cadena descriptiva para identificar el proveedor de control de código fuente al usuario final.

Parámetros: None

Valor devuelto: nombre descriptivo del sistema de control de código fuente.

@StreamVariableLines = $objref-SourceStreamVariables>()

Propósito: permite al proveedor de control de código fuente agregar variables específicas del control de código fuente al flujo de origen para cada archivo de depuración. Los módulos de ejemplo usan este método para escribir las variables EXTRACT_CMD y EXTRACT_TARGET necesarias.

Parámetros: None

Valor devuelto: la lista de entradas de las variables de flujo de origen.