Partager via

Serveur source

  • Article

Le serveur source permet à un client de récupérer la version exacte des fichiers sources utilisés pour générer une application. Étant donné que le code source d’un module peut changer entre les versions et au cours des années, il est important d’examiner le code source tel qu’il existait lors de la génération 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 à la source.

Indexation 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 une version ultérieure.

En règle générale, les fichiers binaires sont indexés au cours du processus de génération après la génération 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
  • Forcément
  • 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 de serveur source.

Outil Description
Srcsrv.ini Ce fichier est la liste principale de tous les serveurs de contrôle de code source. Chaque entrée a le format suivant :MYSERVER=serverinfo
Lorsque vous utilisez Perforce, les informations du serveur se composent du chemin d’accès réseau complet au serveur, suivi d’un signe deux-points, suivi du numéro de port qu’il utilise. Par exemple:
MYSERVER=machine.corp.company.com :1666
Ce fichier peut être installé sur l’ordinateur exécutant le débogueur. Lorsque le serveur source démarre, il examine Srcsrv.ini pour les valeurs ; ces valeurs remplacent les informations contenues dans le fichier PDB. Cela permet aux utilisateurs de configurer un débogueur pour utiliser un autre serveur de contrôle de code source au moment du débogage.
Pour plus d’informations, consultez l’exemple Srcsrv.ini installé avec les outils serveur source.
Ssindex.cmd Ce script génère la liste des fichiers archivés dans le contrôle de code source, ainsi que les informations de version de chaque fichier. Il stocke un sous-ensemble de ces informations dans les fichiers .pdb générés lorsque vous avez créé l’application. Le script utilise l’un des modules Perl suivants pour interfacer avec le contrôle de code source : P4.pm (Perforce) ou Vss.pm (Visual Source Safe). Pour plus d’informations, exécutez le script avec le - ? ou-?? (aide détaillée) ou examinez le script.
Srctool.exe Cet utilitaire répertorie tous les fichiers indexés dans un fichier .pdb. Pour chaque fichier, il répertorie le chemin d’accès complet, le serveur de contrôle de code source et le numéro de version du fichier. Vous pouvez utiliser ces informations pour récupérer des fichiers sans utiliser le serveur source. Pour plus d’informations, exécutez l’utilitaire avec / ? option.
Pdbstr.exe Cet utilitaire est utilisé par les scripts d’indexation pour insérer les informations de contrôle de version dans le flux alternatif « srcsrv » du fichier .pdb cible. Il peut également lire n’importe quel flux à partir d’un fichier .pdb. Vous pouvez utiliser ces informations pour vérifier que les scripts d’indexation fonctionnent correctement. Pour plus d’informations, exécutez l’utilitaire avec / ? option.

 

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 fonctionSymEnumSourceFilesou 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 recherche 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 des 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 de fichiers sources. La création d’un module crée automatiquement une liste de chemins complets vers les 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 spécifique et du système de contrôle de code source en cours d’utilisation.

Dans la spécification du langage version 1, le bloc de données est divisé en trois sections : ini, variables et fichiers sources. Elle 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 à développer.

%fnbksl%()

Toutes les barres obliques (/) du 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 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.

VERCTL

Chaîne qui décrit le produit de contrôle de code source. Cette variable est facultative.

DATETIME

Chaîne qui indique la date et l’heure à laquelle le fichier PDB a été traité. Cette variable est facultative.

La section variables 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. Il s’agit d’une variable requise.

SRCSRVENV

Chaîne qui répertorie les variables d’environnement à créer pendant l’extraction de fichiers. Séparez plusieurs entrées avec un caractère 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, 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, 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 :

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%) imprimer -o %srcsrvtrg% -q %depot%/%var3%@%label%

Fonctionnement du serveur source

Le client de serveur source est implémenté dans Symsrv.dll. Le client n’extrait pas d’informations directement à partir 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 futures versions.

  • 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 à partir de la base de données 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 les entrées de fichier source dans le bloc de données pour 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 vers 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 à l’emplacement cible. Enfin, elle exécute cette commande.

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

Le serveur source inclut 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 sur STDOUT.

Paramètres : Aucun

Valeur de retour : None

$module ::VerboseUsage()

Objectif : affiche des informations d’utilisation détaillées du module dans STDOUT.

Paramètres : Aucun

Valeur de retour : None

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

Objectif : initialise une instance du module fournisseur.

Paramètres : tous les arguments @ARGV 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 les opérations ultérieures.

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

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

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 la $FileEntry retournée. SSIndex.cmd met en cache ces variables pour chaque fichier source utilisé par un seul fichier de débogage pour 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 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.