Källserver

Med källservern kan en klient hämta den exakta versionen av källfilerna som användes för att skapa ett program. Eftersom källkoden för en modul kan ändras mellan versioner och under flera år är det viktigt att titta på källkoden som den fanns när versionen av modulen i fråga skapades.

Källservern hämtar lämpliga filer från källkontrollen. Om du vill använda källservern måste programmet ha källindexerats.

Källindexering

Källindexeringssystemet är en samling körbara filer och Perl-skript. Perl-skripten kräver Perl 5.6 eller senare.

I allmänhet är binärfiler källindexerade under byggprocessen när programmet har skapats. Den information som behövs av källservern lagras i PDB-filerna.

Källservern levereras för närvarande med skript som ska fungera med följande källkontrollsystem.

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

Du kan också skapa ett anpassat skript för att indexera koden för ett annat källkontrollsystem.

I följande tabell visas källserververktygen.

Hämtar källfilen

DbgHelp-API:et ger åtkomst till källserverfunktioner via funktionen SymGetSourceFile. Om du vill hämta namnet på källfilen som ska hämtas anropar du funktionen SymEnumSourceFiles eller SymGetLineFromAddr64.

Använda källservern med ett felsökningsprogram

Om du vill använda källservern med WinDbg, KD, NTSD eller CDB kontrollerar du att du har installerat en ny version av felsökningsverktygen för Windows-paketet (version 6.3 eller senare). Inkludera sedan srv* i kommandot .srcpath enligt följande:

.srcpath srv*;c:\mysource

Observera att det här exemplet även innehåller en traditionell källsökväg. Om felsökaren inte kan hämta filen från källservern söker den efter den angivna sökvägen.

Om en källfil hämtas av källservern finns den kvar på hårddisken när felsökningssessionen är över. Källfiler lagras lokalt i underkatalogen src i installationskatalogen Felsökningsverktyg för Windows.

Källserverdatablock

Källservern förlitar sig på två datablock i PDB-filen.

• Källfillista. När du skapar en modul skapas automatiskt en lista över fullständigt kvalificerade sökvägar till de källfiler som används för att skapa modulen.
• Datablock. Indexering av källan enligt beskrivningen ovan lägger till en alternativ ström till PDB-filen med namnet "srcsrv". Skriptet som infogar dessa data är beroende av den specifika byggprocess och det källkontrollsystem som används.

I språkspecifikation version 1 är datablocket indelat i tre avsnitt: ini, variabler och källfiler. Den 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 expanderas.

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

Ini-avsnittet 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.

VERCTL

En sträng som beskriver källkontrollprodukten. 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 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. Det här är en obligatorisk variabel.

SRCSRVENV

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

Avsnittet källfiler 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ändigt kvalificerade sökvägen till källfilen enligt listan någon annanstans i PDB-filen. Till exempel följande rad:

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 versionsnummer. 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 alternativt 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%) skriv ut -o %srcsrvtrg% -q %depot%/%var3%@%label%

Så här fungerar källservern

Källserverklienten implementeras i Symsrv.dll. Klienten extraherar inte information direkt från PDB-filen. den använder en symbolhanterare, till exempel den som implementerades i Dbghelp.dll. Det är i princip en rekursiv variabel ersättningsmotor som skapar en kommandorad som kan användas för att extrahera rätt källfil från källkontrollsystemet. Koden bör inte anropa Symsrv.dll direkt. Om du vill integrera dess funktioner i ditt program använder du funktionen SymGetSourceFile.

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

• Klienten anropar funktionen SrcSrvInit med målsökvägen som ska användas som bas för alla extrahering av källfiler. Den lagrar den här sökvägen i TARG-variabeln.
• Klienten extraherar Srcsrv-strömmen från PDB när modulen PDB läses in och anropar funktionen SrcSrvLoadModule för att skicka datablocket till källservern.
• När Dbghelp hämtar en källfil anropar klienten funktionen SrcSrvGetFile för att hämta källfilerna från källkontrollen.
• Källservern söker i källfilposterna i datablocket efter en post som matchar den begärda filen. Den fyller VAR1 till VARn med innehållet i källfilposten. Därefter expanderar den variabeln SRCSRVTRG med var1 till VARn. Om filen redan finns på den här platsen returneras platsen till anroparen. Annars expanderar den variabeln SRCSRVCMD för att skapa det kommando som behövs för att hämta filen från källkontrollen och kopiera den till målplatsen. Slutligen kör den det här kommandot.

Skapa en providermodul för källkontroll

Källservern innehåller providermoduler för Perforce (p4.pm) och Visual Source Safe (vss.pm). Om du vill skapa en egen providermodul måste du implementera följande uppsättning gränssnitt.

$module::SimpleUsage()

Syfte: Visar enkel modulanvändningsinformation för STDOUT.

Parametrar: Ingen

Returvärde: Ingen

$module::VerboseUsage()

Syfte: Visar detaljerad information om modulanvändning till STDOUT.

Parametrar: Ingen

Returvärde: Ingen

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

Syfte: Initierar en instans av providermodulen.

Parametrar: Alla @ARGV argument som inte kändes igen av SSIndex.cmd som allmänna argument.

Returvärde: En referens som kan användas i senare åtgärder.

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

Syfte: Gör att modulen kan samla in nödvändig källindexeringsinformation för den katalog som anges av parametern $SourcePath. Modulen bör inte förutsätta att den här posten bara anropas en gång för varje objektinstans, eftersom SSIndex.cmd kan anropa den flera gånger för olika sökvägar.

Parametrar: (1) Den lokala katalogen som innehåller den källa som ska indexeras. (2) En referens till en hash som innehåller alla poster från den angivna Srcsrv.ini filen.

Returvärde: Ingen

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

Syfte: Tillhandahåller nödvändig information för att extrahera en enda, specifik fil från källkontrollsystemet.

Parametrar: Ett fullständigt kvalificerat filnamn

Returvärde: (1) En hashreferens för de variabler som krävs för att tolka den returnerade $FileEntry. SSIndex.cmd cachelagrar dessa variabler för varje källfil som används av en enda felsökningsfil för att minska mängden information som skrivs till källindexströmmen. (2) Filposten som ska skrivas till källindexströmmen så att SrcSrv.dll kan extrahera filen från källkontrollen. Det exakta formatet för den här raden är specifikt för källkontrollsystemet.

$TextString = $objref>LongName()

Syfte: Tillhandahåller en beskrivande sträng för att identifiera källkontrollprovidern för slutanvändaren.

Parametrar: Ingen

Returvärde: Källkontrollsystemets beskrivande namn.

@StreamVariableLines = $objref–>SourceStreamVariables()

Syfte: Gör att källkontrollprovidern kan lägga till källkontrollspecifika variabler i källströmmen för varje felsökningsfil. Exempelmodulerna använder den här metoden för att skriva nödvändiga EXTRACT_CMD och EXTRACT_TARGET variabler.

Parametrar: Ingen

Returvärde: Listan över poster för källströmsvariablerna.