Språkspecifikation 1

Anmärkning

Det här avsnittet beskriver den interna driften av SrcSrv. Allmän information om hur källsökvägar fungerar finns i Källsökväg. Information om hur du använder SrcSrv finns i Använda SrcSrv. Om du vill fastställa den aktuella processen för källinläsning i din miljö, aktiverar du bruskällans inläsning som beskrivs i .srcnoisy (Noisy Source Loading)

Den första versionen av SrcSrv fungerar på följande sätt. (Det här beteendet kan ändras i framtida versioner.)

Först anropar klienten SrcSrvInit med målsökvägen som ska användas som bas för alla extrahering av källfiler. Den här sökvägen lagras i specialvariabeln TARG.

När DbgHelp läser in en moduls .pdb-fil extraherar den SrcSrv-strömmen från .pdb-filen och skickar datablocket till SrcSrv genom att anropa SrcSrvLoadModule.

När DbgHelp sedan behöver hämta en källfil anropas SrcSrvGetFile för att hämta en angiven källfil från versionskontroll.

SrcSrv granskar alla källfilposter i datablocket för en post som matchar exakt den begärda källspecifikationen. Den här matchningen finns i VAR1.

När SrcSrv hittar posten, fyller den i de särskilda variablerna (VAR1, VAR2 osv.) med innehållet från denna källfilspost. Sedan löses variabeln SRCSRVTRG med hjälp av dessa specialvariabler.

Följande visar hur variabeln SRCSRVTRG löses med hjälp av specialvariablerna. Vi antar att källsökvägen fortfarande är:

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

Varje rad visar upplösningen för ytterligare en specialvariabel. De lösta variablerna är fetstil.

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

Observera att den här genererade målsökvägen är unik och inte tillåter att två versioner av samma fil extraheras till samma plats.

SrcSrv ser nu ut att se om filen redan finns där. I så fall returnerar SrcSrv platsen till anroparen. Annars skapar SrcSrv ett körningskommando för att extrahera filen genom att lösa SRCSRVCMD.

I följande exempel visar varje rad upplösningen för ytterligare en specialvariabel. De lösta variablerna är i fetstil.

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 kör SrcSrv det här kommandot. Om resultatet av det här kommandot är en fil på den förväntade platsen returneras den här sökvägen till anroparen.

Observera att om en variabel inte kan matchas görs ett försök att söka upp den som en os-miljövariabel. Om det misslyckas tas variabelnamnet bort från texten som bearbetas.

Två procentsymboler i följd tolkas som en enda procentsymbol.

Datablock för källserver

SrcSrv förlitar sig på två datablock i .pdb-filen, källfillistan och datablocket.

Källfillistan skapas automatiskt när en modul skapas. Den här listan innehåller fullständigt kvalificerade sökvägar till de källfiler som används för att skapa modulen.

Datablocket skapas under källindexering. För närvarande läggs en alternativ ström med namnet "srcsrv" till i .pdb-filen. Skriptet som infogar dessa data är beroende av den specifika byggprocess och det källkontrollsystem som används.

Datablocket är indelat i tre avsnitt: ini, variabler och källfiler. Datablocket har följande syntax.

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

All text tolkas bokstavligen, förutom text som omges av procenttecken (%). Text som omges av procenttecken behandlas som ett variabelnamn som ska matchas rekursivt, såvida det inte är någon av följande funktioner:

%fnvar%()
Parametertexten ska omges av procenttecken och behandlas som en variabel som ska matchas.

%fnbksl%()
Alla snedstreck (/) i parametertexten bör ersättas med bakåtsnedstreck ().

%fnfile%()
All sökvägsinformation i parametertexten ska tas bort och endast filnamnet lämnas kvar.

Avsnittet [ini] i datablocket innehåller variabler som beskriver kraven. Indexeringsskriptet kan lägga till valfritt antal variabler i det här avsnittet. Följande är exempel:

VERSION
Språkspecifikationsversionen. Den här variabeln krävs. Om du utvecklar ett skript baserat på den aktuella språkspecifikationen anger du det här värdet till 1. SrcSrv-klientkoden försöker inte köra något skript som har ett värde som är större än det egna. Aktuella versioner av SrcSrv använder värdet 2.

VERCTRL
En sträng som beskriver källversionskontrollsystemet. Den här variabeln är valfri.

DATETIME
En sträng som anger datum och tid då .pdb-filen bearbetades. Den här variabeln är valfri.

Avsnittet [variabler] i datablocket innehåller variabler som beskriver hur du extraherar en fil från källkontrollen. Den kan också användas för att definiera vanlig text som variabler för att minska storleken på datablocket.

SRCSRVTRG
Beskriver hur du skapar målsökvägen för den extraherade filen. Det här är en obligatorisk variabel.

SRCSRVCMD
Beskriver hur du skapar kommandot för att extrahera filen från källkontrollen. Detta inkluderar namnet på den körbara filen och dess kommandoradsparametrar. Detta krävs om något extraheringskommando måste köras.

SRCSRVENV
Visar en lista över miljövariabler som ska skapas under filextraheringen. Det här är en sträng. Avgränsa flera poster med ett backstegstecken (\b). Det här är en valfri variabel.

SRCSRVVERCTRL
Anger det versionskontrollsystem som används. För Perforce är detta perforce. För Team Foundation Server är detta tfs. Den här variabeln används för att bevara serverfel. Det här är en valfri variabel.

SRCSRVVERRDESC
Anger vilken text som ska visas när versionskontrollklienten inte kan kontakta den server som innehåller källfilerna som ska extraheras. SrcSrv använder det här värdet för att söka efter anslutningsproblem. Det här är en valfri variabel.

SRCSRVERRVAR
Anger vilken variabel i en filpost som motsvarar en versionskontrollserver. Den används av SrcSrv för att identifiera kommandon som inte fungerar, baserat på tidigare fel. Textens format är varX där X är antalet variabeln som anges. Det här är en valfri variabel.

Avsnittet [källfiler] i datablocket innehåller en post för varje källfil som har indexerats. Innehållet på varje rad tolkas som variabler med namnen VAR1, VAR2, VAR3 och så vidare fram till VAR10. Variablerna avgränsas med asterisker. VAR1 måste ange den fullständiga sökvägen till källfilen enligt vad som angetts någon annanstans i .pdb-filen. Till exempel:

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

tolkas på följande sätt:

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

I det här exemplet är VAR4 ett revisionsnummer. De flesta källkontrollsystem stöder dock etikettering av filer på ett sådant sätt att källtillståndet för en viss version kan återställas. Därför kan du i stället använda etiketten för bygget. Exempeldatablocket kan ändras så att det innehåller en variabel, till exempel följande:

LABEL=BUILD47 

Om du antar att källkontrollsystemet sedan använder at-tecknet (@) för att ange en etikett kan du ändra variabeln SRCSRVCMD enligt följande:

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

Hantera serverfel

Ibland kan en klient inte extrahera några filer alls från en enskild versionskontrollserver. Det kan bero på att servern är nere och utanför nätverket eller på att användaren inte har rätt behörighet att komma åt källan. Den tid det tar att försöka hämta den här källan kan dock göra saker och ting betydligt långsammare. I den här situationen är det bäst att inaktivera alla försök att extrahera från en källa som har visat sig vara otillgänglig.

När SrcSrv inte kan extrahera en fil undersöker den utdatatexten som genereras av kommandot. Om någon del av det här kommandot exakt motsvarar innehållet i SRCSRVERRDESC, kommer alla framtida kommandon till samma versionskontrollserver att hoppas över. Observera att du kan definiera flera felsträngar genom att lägga till tal eller godtycklig text i slutet av variabelnamnet SRCSRVERRDESC. Här är ett exempel:

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

Serverns identitet hämtas från SRCSRVERRVAR. Så om SRCSRVERRVAR innehåller "var2" och filposten i .pdb-filen ser ut så här:

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

alla framtida försök att hämta källan med hjälp av en filpost som innehåller "TOOLS_PRJ" i variabel 2 kringgås.

Du kan också lägga till felindikatorer på felsökningsklienten genom att redigeraSrcsrv.ini. Mer information finns i den inkluderade exempelversionen av srcsrv.ini.