Spécification de langage 1
Notes
Cette rubrique décrit le fonctionnement interne de SrcSrv. Pour obtenir des informations générales sur le fonctionnement des chemins sources, consultez Chemin d’accès source. Pour plus d’informations sur l’utilisation de SrcSrv, consultez Utilisation de SrcSrv. Pour déterminer l’opération actuelle du chargement de la source dans votre environnement, activez le chargement de source bruyant, comme décrit dans .srcnoisy (chargement de source bruyant)
La première version de SrcSrv fonctionne comme suit. (Ce comportement peut changer dans les versions ultérieures.)
Tout d’abord, le client appelle SrcSrvInit avec le chemin cible à utiliser comme base pour toutes les extractions de fichiers sources. Ce chemin 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, lorsque 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 de source demandée. Cette correspondance se trouve dans VAR1.
Une fois que SrcSrv a trouvé l’entrée, il 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 d’accès 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 spéciale supplémentaire. 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 d’accès cible généré est unique et n’autorise pas l’extraction de deux versions du même fichier au même emplacement.
SrcSrv recherche maintenant si le fichier est déjà présent. 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 spéciale supplémentaire. 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 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 de 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 pour cent 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 des fichiers sources et le bloc de données.
La liste des 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éé lors de 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 construction et du système de contrôle des sources utilisés.
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é dans des signes de pourcentage (%). Le texte entouré de 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é dans 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 antérieures ().
%fnfile%()
Toutes les informations relatives au chemin d’accès dans le texte du paramètre doivent être supprimées, pour ne laisser que 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 un nombre quelconque 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 de langage actuelle, définissez cette valeur sur 1. Le code client SrcSrv ne tente pas d’exécuter un script dont la valeur est supérieure à la sienne. Les versions actuelles de SrcSrv utilisent la valeur 2.
VERCTRL
Chaîne qui décrit le système de gestion de version source. Cette variable est facultative.
DATETIME
Chaîne qui indique la date et l’heure de 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 du contrôle de code source. Il peut également être utilisé pour définir un texte couramment utilisé comme variable afin de réduire la taille du bloc de données.
SRCSRVTRG
Décrit comment construire le chemin cible pour le fichier extrait. Il s’agit d’une variable obligatoire.
SRCSRVCMD
Décrit comment construire la commande pour extraire le fichier du contrôle de source. Cela inclut le nom du fichier exécutable et ses paramètres de ligne de commande. Cela est obligatoire si une commande d’extraction doit être exécutée.
SRCSRVENV
Répertorie les variables d’environnement à créer lors de l’extraction de fichier. Il s’agit d’une chaîne. Séparez les entrées multiples par un caractère de retour en arrière (\b). Cette variable est facultative.
SRCSRVVERCTRL
Spécifie le système de gestion de version en cours d’utilisation. Pour Perforce, il s’agit de perforce. Pour Team Foundation Server, il s’agit de tfs. Cette variable est utilisée pour conserver les erreurs de serveur. Cette variable est facultative.
SRCSRVVERRDESC
Spécifie le texte à afficher lorsque le client de contrôle de version ne peut pas contacter le serveur qui contient les fichiers sources à extraire. SrcSrv utilise cette valeur pour case activée pour les problèmes de connexion. Cette variable est 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 est le nombre de la variable indiquée. Cette variable est 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 portant 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 d’accès complet au 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ée de la manière suivante :
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 du code source permettent d’étiqueter les fichiers de manière à restaurer l’état des sources pour une version donnée. Par conséquent, vous pouvez utiliser l’étiquette pour la build. Le bloc de données de l’échantillon pourrait être modifié pour contenir une variable telle que la suivante :
LABEL=BUILD47
Ensuite, en supposant que le système de contrôle des sources utilise le signe arobase (@) 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 de serveur
Parfois, un client n’est pas en mesure d’extraire des fichiers à partir d’un serveur de contrôle de version unique. Cela peut être dû au fait que le serveur est hors réseau ou que l’utilisateur ne dispose pas des privilèges appropriés pour accéder à la source. Toutefois, le temps consommé pour tenter d’obtenir cette source peut ralentir considérablement les choses. Dans ce cas, il est préférable de désactiver toute tentative d’extraction à partir 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 produit par la commande . Si une partie de cette commande contient une correspondance exacte pour le contenu de SRCSRVERRDESC, toutes les commandes futures sur le même serveur de contrôle de version 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 à partir 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 tentatives futures 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 modifiantSrcsrv.ini. Pour plus d’informations, consultez l’exemple de version de srcsrv.ini inclus.