Especificación del lenguaje 1
Nota
En este tema se describe el funcionamiento interno de SrcSrv. Para obtener información general sobre cómo funcionan las rutas de acceso de origen, consulte Ruta de acceso de origen. Para obtener información sobre el uso de SrcSrv, consulte Uso de SrcSrv. Para determinar la operación actual de carga de origen en el entorno, habilite la carga de origen ruidosa como se describe en .srcnoisy (Carga de origen ruidoso)
La primera versión de SrcSrv funciona de la siguiente manera. (Este comportamiento puede cambiar en versiones futuras).
En primer lugar, el cliente llama a SrcSrvInit con la ruta de acceso de destino que se usará como base para todas las extracciones de archivos de origen. Esta ruta de acceso se almacena en la variable especial TARG.
Cuando DbgHelp carga el archivo .pdb de un módulo, extrae la secuencia SrcSrv del archivo .pdb y pasa este bloque de datos a SrcSrv mediante una llamada a SrcSrvLoadModule.
A continuación, cuando DbgHelp necesita obtener un archivo de código fuente, llama a SrcSrvGetFile para recuperar un archivo de código fuente especificado del control de versiones.
SrcSrv revisa todas las entradas del archivo de origen del bloque de datos para una entrada que coincida exactamente con la especificación de origen solicitada. Esta coincidencia se encuentra en VAR1.
Una vez que SrcSrv encuentra la entrada, rellena las variables especiales (VAR1, VAR2, etc.) con el contenido de esta entrada de archivo de origen. A continuación, la variable SRCSRVTRG se resuelve mediante estas variables especiales.
A continuación se muestra cómo se resuelve la variable SRCSRVTRG mediante las variables especiales. Se supone que la ruta de acceso de origen sigue siendo:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
Cada línea muestra la resolución de una variable especial más. Las variables resueltas están en negrita.
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
Observe cómo esta ruta de acceso de destino generada es única y no permite extraer dos versiones del mismo archivo en la misma ubicación.
SrcSrv ahora busca ver si el archivo ya está ahí. Si es así, SrcSrv devuelve la ubicación al autor de la llamada. De lo contrario, SrcSrv compila el comando de ejecución para extraer el archivo resolviendo SRCSRVCMD.
En el ejemplo siguiente, cada línea muestra la resolución de una variable especial más. Las variables resueltas están en negrita.
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
Ahora SrcSrv ejecuta este comando. Si el resultado de este comando es un archivo en la ubicación esperada, esta ruta de acceso se devuelve al autor de la llamada.
Tenga en cuenta que si no se puede resolver una variable, se intenta buscarla como una variable de entorno del sistema operativo. Si se produce un error, el nombre de la variable se elimina del texto que se está procesando.
Los caracteres de signo de dos porcentajes consecutivos se interpretan como un signo de un solo porcentaje.
Bloques de datos del servidor de origen
SrcSrv se basa en dos bloques de datos dentro del archivo .pdb, la lista de archivos de origen y el bloque de datos.
La lista de archivos de origen se crea automáticamente cuando se compila un módulo. Esta lista contiene rutas de acceso completas a los archivos de origen que se usan para compilar el módulo.
El bloque de datos se crea durante la indexación de origen. En este momento, se agrega una secuencia alternativa denominada "srcsrv" al archivo .pdb. El script que inserta estos datos depende del proceso de compilación específico y del sistema de control de código fuente que se emplee.
El bloque de datos se divide en tres secciones: ini, variables y archivos de origen. El bloque de datos 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 resolver.
%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 y dejarse solo el nombre de archivo.
La sección [ini] del bloque de datos 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 la especificación del lenguaje. Esta variable es necesaria. Si desarrolla un script basado en la especificación de lenguaje actual, establezca este valor en 1. El código de cliente SrcSrv no intenta ejecutar ningún script que tenga un valor mayor que el suyo propio. Las versiones actuales de SrcSrv usan un valor de 2.
VERCTRL
Cadena que describe el sistema de control de versiones 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] del bloque de datos contiene variables que describen cómo extraer un archivo del control de código fuente. También se puede usar para definir el texto que se usa 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. Es una variable obligatoria.
SRCSRVCMD
Describe cómo crear el comando para extraer el archivo de control del código fuente. Esto incluye el nombre del archivo ejecutable y sus parámetros de línea de comandos. Esto es necesario si se debe ejecutar cualquier comando de extracción.
SRCSRVENV
Enumera las variables de entorno que se van a crear durante la extracción de archivos. Se trata de una cadena. Separe las distintas entradas por caracteres de retroceso (\b). Se trata de una variable opcional.
SRCSRVVERCTRL
Especifica el sistema de control de versiones en uso. Para Perforce, esto es perforce. Para Team Foundation Server, esto es tfs. Esta variable se usa para conservar los errores del servidor. Se trata de una variable opcional.
SRCSRVVERRDESC
Especifica el texto que se va a mostrar cuando el cliente de control de versiones no puede ponerse en contacto con el servidor que contiene los archivos de origen que se van a extraer. SrcSrv usa este valor para comprobar si hay problemas de conexión. Se trata de una variable opcional.
SRCSRVERRVAR
Indica qué variable de una entrada de archivo corresponde a un servidor de control de versiones. SrcSrv lo usa para identificar los comandos que no funcionan, en función de los errores anteriores. El formato del texto es varX , donde X es el número de la variable que se indica. Se trata de una variable opcional.
La sección [archivos de origen] del bloque de datos 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:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
se interpreta así:
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 revisión. Sin embargo, la mayoría de los sistemas de control de código fuente admiten archivos de etiquetado para que se pueda restaurar el estado de origen de una compilación determinada. Por lo tanto, en su lugar, podría usar la etiqueta para la compilación. El bloque de datos de ejemplo se puede modificar para contener una variable como la siguiente:
LABEL=BUILD47
A continuación, supongamos que el sistema de control de código fuente usa el signo de arroba (@) para indicar una etiqueta; podría modificar la variable SRCSRVCMD de la siguiente manera:
sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%
Control de errores del servidor
A veces, un cliente no puede extraer ningún archivo en absoluto desde un único servidor de control de versiones. Esto puede deberse a que el servidor está inactivo y fuera de la red o porque el usuario no tiene los privilegios adecuados para acceder al origen. Sin embargo, el tiempo que se tarda en intentar obtener este origen puede ralentizar significativamente las cosas. En esta situación, es mejor deshabilitar cualquier intento de extraer de un origen que se ha demostrado que no está disponible.
Cada vez que SrcSrv no extrae un archivo, examina el texto de salida generado por el comando . Si alguna parte de este comando contiene una coincidencia exacta para el contenido del SRCSRVERRDESC, se omiten todos los comandos futuros en el mismo servidor de control de versiones. Tenga en cuenta que puede definir varias cadenas de error agregando números o texto arbitrario al final del nombre de la variable SRCSRVERRDESC. Este es un ejemplo:
SRCSRVERRDESC=lime: server not found
SRCSRVERRDESC_2=pineapple: network error
La identidad del servidor se adquiere de SRCSRVERRVAR. Por lo tanto, si SRCSRVERRVAR contiene "var2" y la entrada de archivo en el archivo .pdb tiene este aspecto:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
todos los intentos futuros de obtener el origen mediante una entrada de archivo que contiene "TOOLS_PRJ" en la variable 2 se omiten.
También puede agregar indicadores de error en el cliente del depurador editando Srcsrv.ini. Consulte la versión de ejemplo incluida de srcsrv.ini para obtener más información.