Taalspecificatie 1

De eerste versie van SrcSrv werkt als volgt. (Dit gedrag kan in toekomstige versies veranderen.)

Eerst roept de client SrcSrvInit aan met het doelpad dat moet worden gebruikt als basis voor alle bronbestandextracties. Dit pad wordt opgeslagen in de speciale variabele TARG.

Wanneer het .pdb-bestand van een module wordt geladen, wordt de SrcSrv-stroom uit het .pdb-bestand geëxtraheerd en wordt dit gegevensblok doorgegeven aan SrcSrv door SrcSrvLoadModule aan te roepen.

Wanneer DbgHelp vervolgens een bronbestand moet verkrijgen, roept het SrcSrvGetFile aan om een opgegeven bronbestand op te halen uit versiebeheer.

SrcSrv controleert alle bronbestandvermeldingen in het gegevensblok voor een vermelding die exact overeenkomt met de aangevraagde bronspecificatie. Deze match wordt gevonden in VAR1.

Nadat SrcSrv de vermelding heeft gevonden, vult deze de speciale variabelen (VAR1, VAR2, enzovoort) in met de inhoud van deze bronbestandvermelding. Vervolgens wordt de variabele SRCSRVTRG opgelost met behulp van deze speciale variabelen.

Hieronder ziet u hoe de variabele SRCSRVTRG wordt omgezet met behulp van de speciale variabelen. We gaan ervan uit dat het bronpad nog steeds bestaand is.

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

Elke regel toont de resolutie van een andere speciale variabele. De opgeloste variabelen zijn vetgedrukt.

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

U ziet hoe dit gegenereerde doelpad uniek is en niet toestaat dat twee versies van hetzelfde bestand worden geëxtraheerd naar dezelfde locatie.

SrcSrv ziet er nu naar uit of het bestand er al is. Als dit het is, retourneert SrcSrv de locatie naar de beller. Anders bouwt SrcSrv de uitvoeringsopdracht om het bestand op te halen door SRCSRVCMD op te lossen.

In het volgende voorbeeld toont elke regel de resolutie van een andere speciale variabele. De opgeloste variabelen zijn vetgedrukt.

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 

Nu voert SrcSrv deze opdracht uit. Als het resultaat van deze opdracht een bestand op de verwachte locatie is, wordt dit pad geretourneerd naar de beller.

Als een variabele niet kan worden opgelost, wordt geprobeerd deze op te zoeken als een omgevingsvariabele van het besturingssysteem. Als dat mislukt, wordt de naam van de variabele verwijderd uit de tekst die wordt verwerkt.

Twee opeenvolgende procenttekens worden geïnterpreteerd als één procentteken.

Bronservergegevensblokken

SrcSrv is afhankelijk van twee gegevensblokken in het .pdb-bestand, de lijst met bronbestanden en het gegevensblok.

De lijst met bronbestanden wordt automatisch gemaakt wanneer een module wordt gemaakt. Deze lijst bevat volledig gekwalificeerde paden naar de bronbestanden die worden gebruikt om de module te bouwen.

Het gegevensblok wordt gemaakt tijdens het indexeren van de bron. Op dit moment wordt een alternatieve stroom met de naam 'srcsrv' toegevoegd aan het .pdb-bestand. Het script dat deze gegevens invoegt, is afhankelijk van het specifieke buildproces en het bronbeheersysteem dat wordt gebruikt.

Het gegevensblok is onderverdeeld in drie secties: ini, variabelen en bronbestanden. Het gegevensblok heeft de volgende syntaxis.

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

Alle tekst wordt letterlijk geïnterpreteerd, met uitzondering van tekst tussen procenttekens (%). Tekst tussen procenttekens wordt behandeld als een variabelenaam die recursief moet worden omgezet, tenzij dit een van de volgende functies is:

%fnvar%()
De parametertekst moet tussen procenttekens worden geplaatst en worden behandeld als een variabele die moet worden opgelost.

%fnbksl%()
Alle slashes (/) in de parametertekst moeten worden vervangen door achterwaartse slashes ().

%fnfile%()
Alle padinformatie in de parametertekst moet worden verwijderd, waardoor alleen de bestandsnaam behouden blijft.

De sectie [ini] van het gegevensblok bevat variabelen die de vereisten beschrijven. Het indexeringsscript kan een willekeurig aantal variabelen toevoegen aan deze sectie. Hier volgen enkele voorbeelden:

VERSIE
De versie van de taalspecificatie. Deze variabele is vereist. Als u een script ontwikkelt op basis van de huidige taalspecificatie, stelt u deze waarde in op 1. De SrcSrv-clientcode probeert geen script uit te voeren met een waarde die groter is dan een eigen waarde. In de huidige versies van SrcSrv wordt een waarde van 2 gebruikt.

VERCTRL
Een tekenreeks die het broncodebeheersysteem beschrijft. Deze variabele is optioneel.

Datum-tijd
Een tekenreeks die de datum en tijd aangeeft waarop het PDB-bestand is verwerkt. Deze variabele is optioneel.

De sectie [variabelen] van het gegevensblok bevat variabelen waarin wordt beschreven hoe u een bestand kunt extraheren uit broncodebeheer. Het kan ook worden gebruikt om veelgebruikte tekst te definiëren als variabelen om de grootte van het gegevensblok te verkleinen.

SRCSRVTRG
Hierin wordt beschreven hoe u het doelpad voor het geëxtraheerde bestand bouwt. Dit is een vereiste variabele.

SRCSRVCMD
Beschrijft hoe u de opdracht bouwt om het bestand uit broncodebeheer te extraheren. Dit omvat de naam van het uitvoerbare bestand en de bijbehorende opdrachtregelparameters. Dit is vereist als een extractieopdracht moet worden uitgevoerd.

SRCSRVENV
Geeft een lijst weer van omgevingsvariabelen die moeten worden gemaakt tijdens het extraheren van bestanden. Dit is een tekenreeks. Scheid meerdere vermeldingen met een backspace-teken (\b). Dit is een optionele variabele.

SRCSRVVERCTRL
Hiermee specificeert u het versiebeheersysteem dat in gebruik is. Voor Perforce is dit noodzakelijkerwijs. Voor Team Foundation Server is dit tfs. Deze variabele wordt gebruikt voor het persistent maken van serverfouten. Dit is een optionele variabele.

SRCSRVVERRDESC
Hiermee geeft u de tekst weer die moet worden weergegeven wanneer de versiebeheerclient geen verbinding kan maken met de server die de bronbestanden bevat die moeten worden geëxtraheerd. SrcSrv gebruikt deze waarde om te controleren op verbindingsproblemen. Dit is een optionele variabele.

SRCSRVERRVAR
Geeft aan welke variabele in een bestandsvermelding overeenkomt met een versiebeheerserver. Het wordt gebruikt door SrcSrv om opdrachten te identificeren die niet werken, op basis van eerdere fouten. De notatie van de tekst is varX , waarbij X het getal is van de variabele die wordt aangegeven. Dit is een optionele variabele.

De sectie [bronbestanden] van het gegevensblok bevat een vermelding voor elk bronbestand dat is geïndexeerd. De inhoud van elke regel wordt geïnterpreteerd als variabelen met de namen VAR1, VAR2, VAR3, enzovoort tot var10. De variabelen worden gescheiden door sterretjes. VAR1 moet het volledig gekwalificeerde pad naar het bronbestand opgeven, zoals elders in het PDB-bestand wordt vermeld. Voorbeeld:

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

wordt als volgt geïnterpreteerd:

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

In dit voorbeeld is VAR4 een revisienummer. De meeste broncodebeheersystemen ondersteunen echter het labelen van bestanden op een zodanige manier dat de bronstatus voor een bepaalde build kan worden hersteld. Daarom kunt u in plaats daarvan het label voor de build gebruiken. Het voorbeeldgegevensblok kan worden gewijzigd om een variabele te bevatten, zoals de volgende:

LABEL=BUILD47 

Als het bronbeheersysteem vervolgens het at-teken (@) gebruikt om een label aan te geven, kunt u de variabele SRCSRVCMD als volgt wijzigen:

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

Serverfouten afhandelen

Soms kan een client helemaal geen bestanden uit één versiebeheerserver extraheren. Dit kan zijn omdat de server niet beschikbaar is in het netwerk of omdat de gebruiker niet over de juiste bevoegdheden beschikt om toegang te krijgen tot de bron. De tijd die nodig is om deze bron te verkrijgen, kan de zaken echter aanzienlijk vertragen. In deze situatie kunt u het beste elke poging uitschakelen om te extraheren uit een bron die is bewezen niet beschikbaar te zijn.

Wanneer SrcSrv een bestand niet kan extraheren, wordt de uitvoertekst onderzocht die door de opdracht wordt geproduceerd. Als een deel van deze opdracht een exacte overeenkomst bevat voor de inhoud van de SRCSRVERRDESC, worden alle toekomstige commando's naar dezelfde versiebeheerserver overgeslagen. U kunt meerdere fouttekenreeksen definiëren door getallen of willekeurige tekst toe te voegen aan het einde van de variabele SRCSRVERRDESC. Hier volgt een voorbeeld:

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

De identiteit van de server wordt verkregen van SRCSRVERRVAR. Dus als SRCSRVERRVAR 'var2' bevat en de bestandsvermelding in het .pdb-bestand er als volgt uitziet:

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

alle toekomstige pogingen om bron te verkrijgen met behulp van een bestandsvermelding die 'TOOLS_PRJ' in variabele 2 bevat, worden overgeslagen.

U kunt ook foutindicatoren toevoegen aan de foutopsporingsprogrammaclient door Srcsrv.inite bewerken. Zie de opgenomen voorbeeldversie van srcsrv.ini voor meer informatie.