Serveur source

Le serveur source permet à un client de récupérer la version exacte des fichiers sources qui ont été utilisés pour créer une application. Étant donné que le code source d’un module peut changer entre les versions et au fil des années, il est important d’examiner le code source tel qu’il existait lors de la création de la version du module en question.

Le serveur source récupère les fichiers appropriés à partir du contrôle de code source. Pour utiliser le serveur source, l’application doit avoir été indexée par la source.

Indexation de la source

Le système d’indexation source est une collection de fichiers exécutables et de scripts Perl. Les scripts Perl nécessitent Perl 5.6 ou supérieur.

En règle générale, les fichiers binaires sont indexés à la source pendant le processus de génération après la création de l’application. Les informations requises par le serveur source sont stockées dans les fichiers PDB.

Le serveur source est actuellement fourni avec des scripts qui doivent fonctionner avec les systèmes de contrôle de code source suivants.

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

Vous pouvez également créer un script personnalisé pour indexer votre code pour un autre système de contrôle de code source.

Le tableau suivant répertorie les outils serveur source.

Récupération du fichier source

L’API DbgHelp permet d’accéder aux fonctionnalités du serveur source via la fonction SymGetSourceFile . Pour récupérer le nom du fichier source à récupérer, appelez la fonction SymEnumSourceFiles ou SymGetLineFromAddr64 .

Utilisation du serveur source avec un débogueur

Pour utiliser le serveur source avec WinDbg, KD, NTSD ou CDB, vérifiez que vous avez installé une version récente du package Outils de débogage pour Windows (version 6.3 ou ultérieure). Ensuite, incluez srv* dans la commande .srcpath comme suit :

.srcpath srv*;c:\mysource

Notez que cet exemple inclut également un chemin d’accès source traditionnel. Si le débogueur ne peut pas récupérer le fichier à partir du serveur source, il effectue une recherche dans le chemin d’accès spécifié.

Si un fichier source est récupéré par le serveur source, il reste sur votre disque dur une fois la session de débogage terminée. Les fichiers sources sont stockés localement dans le sous-répertoire src du répertoire d’installation Outils de débogage pour Windows.

Blocs de données du serveur source

Le serveur source s’appuie sur deux blocs de données dans le fichier PDB.

• Liste des fichiers sources. La génération d’un module crée automatiquement une liste de chemins d’accès complets aux fichiers sources utilisés pour générer le module.
• Bloc de données. L’indexation de la source comme décrit précédemment ajoute un autre flux au fichier PDB nommé « srcsrv ». Le script qui insère ces données dépend du processus de génération et du système de contrôle de code source en cours d’utilisation.

Dans la spécification de langage version 1, le bloc de données est divisé en trois sections : ini, variables et fichiers sources. Il 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 placé dans 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é dans des signes de pourcentage et traité comme une variable à développer.

%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 de chemin d’accès dans le texte du paramètre doivent être supprimées, en laissant uniquement le nom de fichier.

La section ini 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.

VERCTL

Chaîne qui décrit le produit du contrôle de code 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 contient des variables qui décrivent comment extraire un fichier du contrôle de code source. Il peut également être utilisé pour définir du texte couramment utilisé en tant que variables afin de réduire la taille du bloc de données.

SRCSRVTRG

Décrit comment générer le chemin d’accès cible pour le fichier extrait. Il s’agit d’une variable obligatoire.

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. Il s’agit d’une variable obligatoire.

SRCSRVENV

Chaîne qui répertorie les variables d’environnement à créer pendant l’extraction de fichier. Séparez plusieurs entrées par un caractère d’arrière (\b). Il s’agit d’une variable facultative.

La section Fichiers sources 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, etc. jusqu’à VAR10. Les variables sont séparées par des astérisque. VAR1 doit spécifier le chemin complet du fichier source, comme indiqué ailleurs dans le fichier PDB. Par exemple, la ligne suivante :

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 version. 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 également utiliser l’étiquette pour la build. L’exemple de bloc de données peut être modifié pour contenir une variable telle que la suivante :

LABEL=BUILD47

Ensuite, en supposant que le système de contrôle de code source utilise 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%

Fonctionnement du serveur source

Le client du serveur source est implémenté dans Symsrv.dll. Le client n’extrait pas d’informations directement du fichier PDB ; il utilise un gestionnaire de symboles tel que celui implémenté dans Dbghelp.dll. Il s’agit essentiellement d’un moteur de substitution de variable récursive qui crée une ligne de commande qui peut être utilisée pour extraire le fichier source approprié du système de contrôle de code source. Votre code ne doit pas appeler Symsrv.dll directement. Pour intégrer ses fonctionnalités à votre application, utilisez la fonction SymGetSourceFile .

La première version du serveur source fonctionne comme suit. Ce comportement peut changer dans les versions ultérieures.

• Le client appelle la fonction SrcSrvInit avec le chemin cible à utiliser comme base pour toutes les extractions de fichiers sources. Il stocke ce chemin dans la variable TARG.
• Le client extrait le flux Srcsrv du PDB lorsque le module PDB est chargé et appelle la fonction SrcSrvLoadModule pour passer le bloc de données au serveur source.
• Lorsque Dbghelp récupère un fichier source, le client appelle la fonction SrcSrvGetFile pour récupérer les fichiers sources à partir du contrôle de code source.
• Le serveur source recherche dans les entrées de fichier source dans le bloc de données une entrée qui correspond au fichier demandé. Il remplit VAR1 à VARn avec le contenu de l’entrée de fichier source. Ensuite, il développe la variable SRCSRVTRG à l’aide de VAR1 à VARn. Si le fichier se trouve déjà à cet emplacement, il retourne l’emplacement à l’appelant. Sinon, il développe la variable SRCSRVCMD pour générer la commande nécessaire pour récupérer le fichier à partir du contrôle de code source et le copier vers l’emplacement cible. Enfin, il exécute cette commande.

Création d’un module fournisseur de contrôle de code source

Le serveur source comprend des modules de fournisseur pour Perforce (p4.pm) et Visual Source Safe (vss.pm). Pour créer votre propre module fournisseur, vous devez implémenter l’ensemble d’interfaces suivant.

$module::SimpleUsage()

Objectif : affiche des informations d’utilisation de module simples pour STDOUT.

Paramètres : aucun

Valeur de retour : None

$module::VerboseUsage()

Objectif : affiche des informations détaillées sur l’utilisation du module pour STDOUT.

Paramètres : aucun

Valeur de retour : None

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

Objectif : initialise une instance du module fournisseur.

Paramètres : tous les @ARGV arguments qui n’ont pas été reconnus par SSIndex.cmd comme étant des arguments généraux.

Valeur de retour : référence qui peut être utilisée dans des opérations ultérieures.

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

Objectif : permet au module de collecter les informations d’indexation sources requises pour le répertoire spécifié par le paramètre $SourcePath. Le module ne doit pas supposer que cette entrée ne sera appelée qu’une seule fois pour chaque objet instance, car SSIndex.cmd peut l’appeler plusieurs fois pour différents chemins.

Paramètres : (1) Répertoire local contenant la source à indexer. (2) Référence à un hachage contenant toutes les entrées du fichier Srcsrv.ini spécifié.

Valeur de retour : None

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

Objectif : fournit les informations nécessaires pour extraire un seul fichier spécifique du système de contrôle de code source.

Paramètres : nom de fichier complet

Valeur de retour : (1) Référence de hachage des variables nécessaires pour interpréter le $FileEntry retourné. SSIndex.cmd met en cache ces variables pour chaque fichier source utilisé par un seul fichier de débogage afin de réduire la quantité d’informations écrites dans le flux d’index source. (2) Entrée de fichier à écrire dans le flux d’index source pour permettre à SrcSrv.dll d’extraire ce fichier du contrôle de code source. Le format exact de cette ligne est spécifique au système de contrôle de code source.

$TextString = $objref-LongName>()

Objectif : fournit une chaîne descriptive pour identifier le fournisseur de contrôle de code source à l’utilisateur final.

Paramètres : aucun

Valeur de retour : nom descriptif du système de contrôle de code source.

@StreamVariableLines = $objref-SourceStreamVariables>()

Objectif : permet au fournisseur de contrôle de code source d’ajouter des variables spécifiques au contrôle de code source au flux source pour chaque fichier de débogage. Les exemples de modules utilisent cette méthode pour écrire les variables EXTRACT_CMD et EXTRACT_TARGET requises.

Paramètres : aucun

Valeur de retour : liste des entrées pour les variables de flux source.