Bronserver

Met de bronserver kan een client de exacte versie ophalen van de bronbestanden die zijn gebruikt om een toepassing te bouwen. Omdat de broncode voor een module kan veranderen tussen versies en gedurende een bepaalde periode, is het belangrijk om de broncode te bekijken zoals deze bestond toen de betreffende versie van de module werd gebouwd.

De bronserver haalt de juiste bestanden op uit broncodebeheer. Als u de bronserver wilt gebruiken, moet de toepassing zijn geïndexeerd.

Bronindexering

Het bronindexeringssysteem is een verzameling uitvoerbare bestanden en Perl-scripts. Voor de Perl-scripts is Perl 5.6 of hoger vereist.

Over het algemeen worden binaire bestanden geïndexeerd tijdens het buildproces nadat de toepassing is gebouwd. De informatie die nodig is voor de bronserver wordt opgeslagen in de PDB-bestanden.

De bronserver wordt momenteel geleverd met scripts die moeten werken met de volgende broncodebeheersystemen.

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

U kunt ook een aangepast script maken om uw code te indexeren voor een ander broncodebeheersysteem.

De volgende tabel bevat de bronserverhulpprogramma's.

Werktuig	Beschrijving
Srcsrv.ini	Dit bestand is de hoofdlijst van alle bronbeheerservers. Elke vermelding heeft de volgende indeling:MYSERVER=serverinfo Wanneer u Perforce gebruikt, bestaat de servergegevens uit het volledige netwerkpad naar de server, gevolgd door een dubbele punt, gevolgd door het poortnummer dat wordt gebruikt. Bijvoorbeeld: MYSERVER=machine.corp.company.com:1666 Dit bestand kan worden geïnstalleerd op de computer waarop het foutopsporingsprogramma wordt uitgevoerd. Wanneer de bronserver wordt gestart, kijkt deze naar Srcsrv.ini voor waarden; met deze waarden wordt de informatie in het PDB-bestand overschreven. Hierdoor kunnen gebruikers een foutopsporingsprogramma configureren voor het gebruik van een alternatieve bronbeheerserver op het moment van foutopsporing. Zie het voorbeeld Srcsrv.ini geïnstalleerd met de bronserverhulpprogramma's voor meer informatie.
Ssindex.cmd	Met dit script wordt de lijst met bestanden gebouwd die zijn ingecheckt in broncodebeheer, samen met de versiegegevens van elk bestand. Er wordt een subset van deze informatie opgeslagen in de PDB-bestanden die zijn gegenereerd tijdens het bouwen van de toepassing. Het script maakt gebruik van een van de volgende Perl-modules om interface te maken met broncodebeheer: P4.pm (Perforce) of Vss.pm (Visual Source Safe). Voer het script uit met de -voor meer informatie? of-?? (uitgebreide Help) optie of onderzoek het script.
Srctool.exe	Dit hulpprogramma bevat alle bestanden die zijn geïndexeerd in een .pdb-bestand. Voor elk bestand wordt het volledige pad, de bronbeheerserver en het versienummer van het bestand vermeld. U kunt deze informatie gebruiken om bestanden op te halen zonder de bronserver te gebruiken. Voor meer informatie voert u het hulpprogramma uit met de /? optie.
Pdbstr.exe	Dit hulpprogramma wordt gebruikt door de indexeringsscripts om de versiebeheergegevens in te voegen in de alternatieve stroom 'srcsrv' van het doel.pdb-bestand. Het kan ook elke stream lezen vanuit een .pdb-bestand. U kunt deze informatie gebruiken om te controleren of de indexeringsscripts goed werken. Voor meer informatie voert u het hulpprogramma uit met de /? optie.

 

Het bronbestand ophalen

De DbgHelp-API biedt toegang tot de functionaliteit van de bronserver via de functie SymGetSourceFile. Als u de naam wilt ophalen van het bronbestand dat moet worden opgehaald, roept u de functie SymEnumSourceFiles of SymGetLineFromAddr64 aan.

Bronserver gebruiken met een foutopsporingsprogramma

Als u de bronserver wilt gebruiken met WinDbg, KD, NTSD of CDB, moet u ervoor zorgen dat u een recente versie van het pakket Foutopsporingsprogramma's voor Windows (versie 6.3 of hoger) hebt geïnstalleerd. Neem vervolgens srv* op in de opdracht .srcpath als volgt:

.srcpath srv*;c:\mysource-

Houd er rekening mee dat dit voorbeeld ook een traditioneel bronpad bevat. Als het foutopsporingsprogramma het bestand niet kan ophalen van de bronserver, wordt het opgegeven pad doorzocht.

Als een bronbestand wordt opgehaald door de bronserver, blijft het op de harde schijf staan nadat de foutopsporingssessie is afgelopen. Bronbestanden worden lokaal opgeslagen in de submap src van de installatiemap Foutopsporingsprogramma's voor Windows.

Bronservergegevensblokken

De bronserver is afhankelijk van twee gegevensblokken in het PDB-bestand.

• Lijst met bronbestanden. Als u een module bouwt, wordt automatisch een lijst met volledig gekwalificeerde paden gemaakt naar de bronbestanden die worden gebruikt om de module te bouwen.
• Gegevensblok. Als u de bron indexeert zoals eerder beschreven, wordt een alternatieve stroom toegevoegd aan het PDB-bestand met de naam 'srcsrv'. Het script dat deze gegevens invoegt, is afhankelijk van het specifieke buildproces en het bronbeheersysteem dat wordt gebruikt.

In versie 1 van de taalspecificatie is het gegevensblok onderverdeeld in drie secties: ini, variabelen en bronbestanden. Deze 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 uitgevouwen.

%fnbksl%()

Alle slashes (/) in de parametertekst moeten worden vervangen door schuine streepjes (\).

%fnfile%()

Alle padinformatie in de parametertekst moet worden verwijderd, waardoor alleen de bestandsnaam behouden blijft.

De ini-sectie 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.

VERCTL

Een tekenreeks die het broncodebeheerproduct 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 bevat variabelen waarmee wordt beschreven hoe u een bestand uit broncodebeheer kunt extraheren. 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 een vereiste variabele.

SRCSRVENV

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

De sectie bronbestanden 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. Bijvoorbeeld de volgende regel:

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 versienummer. 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 ook 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%) afdrukken -o %srcsrvtrg% -q %depot%/%var3%@%label%

Hoe bronserver werkt

De bronserverclient wordt geïmplementeerd in Symsrv.dll. De client extraheert geen gegevens rechtstreeks uit het PDB-bestand; het maakt gebruik van een symboolhandler zoals de handler die is geïmplementeerd in Dbghelp.dll. Het is in wezen een recursieve variabele vervangingsengine die een opdrachtregel maakt die kan worden gebruikt om het juiste bronbestand uit het broncodebeheersysteem te extraheren. Uw code mag Symsrv.dll niet rechtstreeks aanroepen. Als u de functionaliteit ervan in uw toepassing wilt integreren, gebruikt u de functie SymGetSourceFile.

De eerste versie van de bronserver werkt als volgt. Dit gedrag kan in toekomstige versies veranderen.

• De client roept de SrcSrvInit--functie aan met het doelpad dat moet worden gebruikt als basis voor alle bronbestandextracties. Dit pad wordt opgeslagen in de TARG-variabele.
• De client extraheert de Srcsrv-stroom uit de PDB wanneer de module PDB wordt geladen en roept de SrcSrvLoadModule--functie aan om het gegevensblok door te geven aan de bronserver.
• Wanneer Dbghelp een bronbestand ophaalt, roept de client de SrcSrvGetFile functie aan om de bronbestanden op te halen uit broncodebeheer.
• De bronserver doorzoekt de vermeldingen in het bronbestand in het gegevensblok naar een vermelding die overeenkomt met het aangevraagde bestand. Het vult VAR1 in op VARn met de inhoud van de bronbestandvermelding. Vervolgens wordt de variabele SRCSRVTRG uitgebreid met behulp van VAR1 naar VARn. Als het bestand zich al op deze locatie bevindt, wordt de locatie naar de beller geretourneerd. Anders wordt de variabele SRCSRVCMD uitgebreid om de opdracht te bouwen die nodig is om het bestand op te halen uit broncodebeheer en deze naar de doellocatie te kopiëren. Ten slotte wordt deze opdracht uitgevoerd.

Een broncodebeheerprovidermodule maken

De bronserver bevat providermodules voor Perforce (p4.pm) en Visual Source Safe (vss.pm). Als u uw eigen providermodule wilt maken, moet u de volgende set interfaces implementeren.

$module::SimpleUsage()

Doel: geeft eenvoudige modulegebruiksgegevens weer voor STDOUT.

Parameters: Geen

Retourwaarde: Geen

$module::VerboseUsage()

Doel: geeft gedetailleerde informatie over het gebruik van modules weer voor STDOUT.

Parameters: Geen

Retourwaarde: Geen

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

Doel: initialiseert een exemplaar van de providermodule.

Parameters: Alle @ARGV argumenten die niet door SSIndex.cmd zijn herkend als algemene argumenten.

Retourwaarde: een verwijzing die kan worden gebruikt in latere bewerkingen.

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

Doel: hiermee kan de module de vereiste bronindexeringsgegevens verzamelen voor de map die is opgegeven door de parameter $SourcePath. In de module mag niet worden aangenomen dat deze vermelding slechts eenmaal wordt aangeroepen voor elk objectexemplaren, omdat SSIndex.cmd deze meerdere keren voor verschillende paden kan aanroepen.

Parameters: (1) De lokale map met de bron die moet worden geïndexeerd. (2) Een verwijzing naar een hash met alle vermeldingen uit het opgegeven Srcsrv.ini bestand.

Retourwaarde: Geen

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

Doel: biedt de benodigde informatie voor het extraheren van één specifiek bestand uit het broncodebeheersysteem.

Parameters: Een volledig gekwalificeerde bestandsnaam

Retourwaarde: (1) Een hash-verwijzing van de variabelen die nodig zijn om de geretourneerde $FileEntry te interpreteren. SSIndex.cmd slaat deze variabelen in de cache op voor elk bronbestand dat wordt gebruikt door één foutopsporingsbestand om de hoeveelheid informatie die naar de bronindexstroom wordt geschreven, te verminderen. (2) De bestandsvermelding die naar de bronindexstroom moet worden geschreven, zodat SrcSrv.dll dit bestand kan extraheren uit broncodebeheer. De exacte indeling van deze regel is specifiek voor het broncodebeheersysteem.

$TextString = $objref->LongName()

Doel: biedt een beschrijvende tekenreeks om de bronbeheerprovider aan de eindgebruiker te identificeren.

Parameters: Geen

Retourwaarde: de beschrijvende naam van het broncodebeheersysteem.

@StreamVariableLines = $objref->SourceStreamVariables()

Doel: hiermee kan de bronbeheerprovider specifieke variabelen voor broncodebeheer toevoegen aan de bronstroom voor elk foutopsporingsbestand. De voorbeeldmodules gebruiken deze methode voor het schrijven van de vereiste EXTRACT_CMD en EXTRACT_TARGET variabelen.

Parameters: Geen

Retourwaarde: de lijst met vermeldingen voor de bronstroomvariabelen.