Spécification de langage 1

La première version de SrcSrv fonctionne comme suit. (Ce comportement peut changer dans les futures versions.)

Tout d’abord, le client appelle SrcSrvInit avec le chemin cible à utiliser comme base pour toutes les extractions de fichiers sources. Ce chemin d’accès est stocké dans la variable spéciale TARG.

Lorsque DbgHelp charge le fichier .pdb d’un module, il extrait le flux SrcSrv du fichier .pdb et transmet ce bloc de données à SrcSrv en appelant SrcSrvLoadModule.

Ensuite, quand DbgHelp doit obtenir un fichier source, il appelle SrcSrvGetFile pour récupérer un fichier source spécifié à partir du contrôle de version.

SrcSrv examine toutes les entrées de fichier source dans le bloc de données pour une entrée qui correspond exactement à la spécification source demandée. Cette correspondance est trouvée dans VAR1.

Une fois que SrcSrv trouve l’entrée, elle remplit les variables spéciales (VAR1, VAR2, etc.) avec le contenu de cette entrée de fichier source. Ensuite, la variable SRCSRVTRG est résolue à l’aide de ces variables spéciales.

L’exemple suivant montre comment la variable SRCSRVTRG est résolue à l’aide des variables spéciales. Nous partons du principe que le chemin source est toujours :

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

Chaque ligne affiche la résolution d’une variable plus spéciale. Les variables résolues sont en gras.

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

Notez que ce chemin cible généré est unique et n’autorise pas l’extraction de deux versions du même fichier vers le même emplacement.

SrcSrv recherche maintenant si le fichier est déjà là. Si c’est le cas, SrcSrv retourne l’emplacement à l’appelant. Sinon, SrcSrv génère la commande d’exécution pour extraire le fichier en résolvant SRCSRVCMD.

Dans l’exemple suivant, chaque ligne affiche la résolution d’une variable plus spéciale. Les variables résolues sont en gras.

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 

À présent, SrcSrv exécute cette commande. Si le résultat de cette commande est un fichier à l’emplacement attendu, ce chemin d’accès est retourné à l’appelant.

Notez que si une variable ne peut pas être résolue, une tentative est effectuée pour la rechercher en tant que variable d’environnement du système d’exploitation. En cas d’échec, le nom de la variable est supprimé du texte en cours de traitement.

Deux caractères de signe de pourcentage consécutifs sont interprétés comme un signe de pourcentage unique.

Blocs de données du serveur source

SrcSrv s’appuie sur deux blocs de données dans le fichier .pdb, la liste de fichiers source et le bloc de données.

La liste de fichiers sources est créée automatiquement lorsqu’un module est généré. Cette liste contient des chemins d’accès complets aux fichiers sources utilisés pour générer le module.

Le bloc de données est créé pendant l’indexation source. À ce stade, un autre flux nommé « srcsrv » est ajouté au fichier .pdb. Le script qui insère ces données dépend du processus de génération spécifique et du système de contrôle de code source en cours d’utilisation.

Le bloc de données est divisé en trois sections : ini, variables et fichiers sources. Le bloc de données a la syntaxe suivante.

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

Tout le texte est interprété littéralement, à l’exception du texte placé entre des signes de pourcentage (%). Le texte placé entre des signes de pourcentage est traité comme un nom de variable à résoudre de manière récursive, sauf s’il s’agit de l’une des fonctions suivantes :

%fnvar%()
Le texte du paramètre doit être placé entre des signes de pourcentage et traité comme une variable à résoudre.

%fnbksl%()
Toutes les barres obliques (/) dans le texte du paramètre doivent être remplacées par des barres obliques descendantes ().

%fnfile%()
Toutes les informations de chemin d’accès dans le texte du paramètre doivent être supprimées, en laissant uniquement le nom du fichier.

La section [ini] du bloc de données contient des variables qui décrivent les exigences. Le script d’indexation peut ajouter n’importe quel nombre de variables à cette section. Voici quelques exemples :

VERSION
Version de la spécification du langage. Cette variable est requise. Si vous développez un script basé sur la spécification actuelle du langage, définissez cette valeur sur 1. Le code client SrcSrv ne tente pas d’exécuter un script dont la valeur est supérieure à sa propre valeur. Les versions actuelles de SrcSrv utilisent la valeur 2.

VERCTRL
Chaîne qui décrit le système de contrôle de version de code source. Cette variable est facultative.

DATETIME
Chaîne qui indique la date et l’heure du traitement du fichier .pdb. Cette variable est facultative.

La section [variables] du bloc de données contient des variables qui décrivent comment extraire un fichier à partir du contrôle de code source. Il peut également être utilisé pour définir du texte couramment utilisé en tant que variables pour réduire la taille du bloc de données.

SRCSRVTRG
Décrit comment générer le chemin cible du fichier extrait. Il s’agit d’une variable requise.

SRCSRVCMD
Décrit comment générer la commande pour extraire le fichier du contrôle de code source. Cela inclut le nom du fichier exécutable et ses paramètres de ligne de commande. Cette opération est requise si une commande d’extraction doit être exécutée.

SRCSRVENV
Répertorie les variables d’environnement à créer lors de l’extraction de fichiers. Il s’agit d’une chaîne. Séparez plusieurs entrées avec un caractère arrière (\b). Il s’agit d’une variable facultative.

SRCSRVVERCTRL
Spécifie le système de contrôle de version en cours d’utilisation. Pour Perforce, c'est la nécessité même. Pour Team Foundation Server, il s’agit de tfs. Cette variable est utilisée pour rendre persistantes les erreurs de serveur. Il s’agit d’une variable facultative.

SRCSRVVERRDESC
Spécifie le texte à afficher lorsque le client de contrôle de version ne parvient pas à contacter le serveur qui contient les fichiers sources à extraire. SrcSrv utilise cette valeur pour vérifier les problèmes de connexion. Il s’agit d’une variable facultative.

SRCSRVERRVAR
Indique quelle variable dans une entrée de fichier correspond à un serveur de contrôle de version. Il est utilisé par SrcSrv pour identifier les commandes qui ne fonctionnent pas, en fonction des échecs précédents. Le format du texte est varX où X correspond au nombre de la variable indiquée. Il s’agit d’une variable facultative.

La section [fichiers sources] du bloc de données contient une entrée pour chaque fichier source qui a été indexé. Le contenu de chaque ligne est interprété comme des variables avec les noms VAR1, VAR2, VAR3, et ainsi de suite jusqu’à VAR10. Les variables sont séparées par des astérisques. VAR1 doit spécifier le chemin complet du fichier source comme indiqué ailleurs dans le fichier .pdb. Par exemple:

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

est interprété comme suit :

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

Dans cet exemple, VAR4 est un numéro de révision. Toutefois, la plupart des systèmes de contrôle de code source prennent en charge l’étiquetage des fichiers de telle sorte que l’état source d’une build donnée puisse être restauré. Par conséquent, vous pouvez utiliser plutôt l’étiquette pour la build. L’exemple de bloc de données peut être modifié pour contenir une variable telle que :

LABEL=BUILD47 

Ensuite, en présumant le système de contrôle de code source, utilisez le signe at (@) pour indiquer une étiquette, vous pouvez modifier la variable SRCSRVCMD comme suit :

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

Gestion des erreurs du serveur

Parfois, un client ne peut pas extraire de fichiers à partir d’un serveur de contrôle de version unique. Cela peut être dû au fait que le serveur est arrêté et hors du réseau ou que l’utilisateur n’a pas les privilèges appropriés pour accéder à la source. Toutefois, le temps consommé lors de la tentative d’obtention de cette source peut ralentir considérablement les choses. Dans ce cas, il est préférable de désactiver toute tentative d’extraction d’une source qui s’est avérée indisponible.

Chaque fois que SrcSrv ne parvient pas à extraire un fichier, il examine le texte de sortie généré par la commande. Si une partie de cette commande contient une correspondance exacte avec le contenu du SRCSRVERRDESC, toutes les commandes ultérieures au même serveur de gestion de versions sont ignorées. Notez que vous pouvez définir plusieurs chaînes d’erreur en ajoutant des nombres ou du texte arbitraire à la fin du nom de la variable SRCSRVERRDESC. Voici un exemple :

SRCSRVERRDESC=lime: server not found
SRCSRVERRDESC_2=pineapple: network error

L’identité du serveur est acquise auprès de SRCSRVERRVAR. Par conséquent, si SRCSRVERRVAR contient « var2 » et que l’entrée de fichier dans le fichier .pdb ressemble à ceci :

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

toutes les futures tentatives d’obtention de la source à l’aide d’une entrée de fichier qui contient « TOOLS_PRJ » dans la variable 2 sont ignorées.

Vous pouvez également ajouter des indicateurs d’erreur sur le client du débogueur en modifiant Srcsrv.ini. Pour plus d’informations, consultez l’exemple de version incluse de srcsrv.ini.