Quellserver

Der Quellserver ermöglicht es einem Client, die genaue Version der Quelldateien abzurufen, die zum Erstellen einer Anwendung verwendet wurden. Da sich der Quellcode für ein Modul zwischen den Versionen und im Laufe der Jahre ändern kann, ist es wichtig, den Quellcode so zu betrachten, wie er beim Erstellen der Version des betreffenden Moduls vorhanden war.

Der Quellserver ruft die entsprechenden Dateien aus der Quellcodeverwaltung ab. Um den Quellserver verwenden zu können, muss die Anwendung quellindiziert worden sein.

Quellindizierung

Das Quellindizierungssystem ist eine Sammlung ausführbarer Dateien und Perl-Skripts. Die Perl-Skripts erfordern Perl 5.6 oder höher.

Im Allgemeinen werden Binärdateien während des Buildprozesses nach dem Erstellen der Anwendung quellindiziert. Die vom Quellserver benötigten Informationen werden in den PDB-Dateien gespeichert.

Der Quellserver enthält derzeit Skripts, die mit den folgenden Quellcodeverwaltungssystemen funktionieren sollten.

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

Sie können auch ein benutzerdefiniertes Skript erstellen, um Ihren Code für ein anderes Quellcodeverwaltungssystem zu indizieren.

In der folgenden Tabelle sind die Quellservertools aufgeführt.

Tool	BESCHREIBUNG
Srcsrv.ini	Diese Datei ist die master Liste aller Quellcodeverwaltungsserver. Jeder Eintrag hat das folgende Format: MYSERVER=serverinfo Bei Verwendung von Perforce bestehen die Serverinformationen aus dem vollständigen Netzwerkpfad zum Server, gefolgt von einem Doppelpunkt, gefolgt von der verwendeten Portnummer. Beispiel: MYSERVER=machine.corp.company.com:1666 Diese Datei kann auf dem Computer installiert werden, auf dem der Debugger ausgeführt wird. Wenn der Quellserver gestartet wird, wird Srcsrv.ini nach Werten gesucht. Diese Werte überschreiben die in der PDB-Datei enthaltenen Informationen. Dadurch können Benutzer einen Debugger so konfigurieren, dass zur Debugzeit ein alternativer Quellcodeverwaltungsserver verwendet wird. Weitere Informationen finden Sie im Beispiel Srcsrv.ini, das mit den Quellservertools installiert wurde.
Ssindex.cmd	Dieses Skript erstellt die Liste der Dateien, die in die Quellcodeverwaltung eingecheckt sind, zusammen mit den Versionsinformationen jeder Datei. Es speichert eine Teilmenge dieser Informationen in den PDB-Dateien, die beim Erstellen der Anwendung generiert wurden. Das Skript verwendet eines der folgenden Perl-Module für die Schnittstelle mit der Quellcodeverwaltung: P4.pm (Perforce) oder Vss.pm (Visual Source Safe). Weitere Informationen finden Sie, wenn Sie das Skript mit -? ausführen. Oder-?? (ausführliche Hilfe) oder untersuchen Sie das Skript.
Srctool.exe	Dieses Hilfsprogramm listet alle Dateien auf, die in einer PDB-Datei indiziert sind. Für jede Datei werden der vollständige Pfad, der Quellcodeverwaltungsserver und die Versionsnummer der Datei aufgelistet. Sie können diese Informationen verwenden, um Dateien abzurufen, ohne den Quellserver zu verwenden. Für weitere Informationen führen Sie das Hilfsprogramm mit /? (Neuen Branch erstellen und Pull Request starten).
Pdbstr.exe	Dieses Hilfsprogramm wird von den Indizierungsskripts verwendet, um die Versionskontrollinformationen in den alternativen Stream "srcsrv" der PDB-Zieldatei einzufügen. Es kann auch jeden Stream aus einer PDB-Datei lesen. Anhand dieser Informationen können Sie überprüfen, ob die Indizierungsskripts ordnungsgemäß funktionieren. Für weitere Informationen führen Sie das Hilfsprogramm mit /? (Neuen Branch erstellen und Pull Request starten).

 

Abrufen der Quelldatei

Die DbgHelp-API bietet über die SymGetSourceFile-Funktion Zugriff auf quellserverfunktionen. Um den Namen der abzurufenden Quelldatei abzurufen, rufen Sie die Funktion SymEnumSourceFiles oder SymGetLineFromAddr64 auf.

Verwenden des Quellservers mit einem Debugger

Um den Quellserver mit WinDbg, KD, NTSD oder CDB zu verwenden, stellen Sie sicher, dass Sie eine aktuelle Version des Pakets Debugtools für Windows (Version 6.3 oder höher) installiert haben. Schließen Sie dann srv* wie folgt in den Befehl .srcpath ein:

.srcpath srv*;c:\mysource

Beachten Sie, dass dieses Beispiel auch einen herkömmlichen Quellpfad enthält. Wenn der Debugger die Datei nicht vom Quellserver abrufen kann, durchsucht er den angegebenen Pfad.

Wenn eine Quelldatei vom Quellserver abgerufen wird, verbleibt sie auf Ihrer Festplatte, nachdem die Debugsitzung beendet wurde. Quelldateien werden lokal im src-Unterverzeichnis des Installationsverzeichnisses Debugtools für Windows gespeichert.

Quellserverdatenblöcke

Der Quellserver basiert auf zwei Datenblöcken in der PDB-Datei.

• Quelldateiliste. Beim Erstellen eines Moduls wird automatisch eine Liste vollqualifizierter Pfade zu den Quelldateien erstellt, die zum Erstellen des Moduls verwendet werden.
• Datenblock. Durch die zuvor beschriebene Indizierung der Quelle wird der PDB-Datei "srcsrv" ein alternativer Stream hinzugefügt. Das Skript, das diese Daten einfügt, hängt vom jeweiligen Buildprozess und dem Quellcodeverwaltungssystem ab, das verwendet wird.

In version 1 der Sprachspezifikation ist der Datenblock in drei Abschnitte unterteilt: ini, variablen und Quelldateien. Sie weist die folgende Syntax auf.

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

Der gesamte Text wird wörtlich interpretiert, mit Ausnahme von Text, der in Prozentzeichen (%). Text, der in Prozentzeichen eingeschlossen ist, wird als Variablenname behandelt, der rekursiv aufgelöst werden soll, es sei denn, es handelt sich um eine der folgenden Funktionen:

%fnvar%()

Der Parametertext sollte in Prozentzeichen eingeschlossen und als Variable behandelt werden, die erweitert werden soll.

%fnbksl%()

Alle Schrägstriche (/) im Parametertext sollten durch rückwärts gerichtete Schrägstriche (\) ersetzt werden.

%fnfile%()

Alle Pfadinformationen im Parametertext sollten entfernt werden, wobei nur der Dateiname übrig bleibt.

Der Abschnitt ini enthält Variablen, die die Anforderungen beschreiben. Das Indizierungsskript kann diesem Abschnitt eine beliebige Anzahl von Variablen hinzufügen. Hier finden Sie einige Beispiele:

VERSION

Die Sprachspezifikationsversion. Diese Variable ist erforderlich.

VERCTL

Eine Zeichenfolge, die das Quellcodeverwaltungsprodukt beschreibt. Diese Variable ist optional.

DATETIME

Eine Zeichenfolge, die das Datum und die Uhrzeit der Verarbeitung der PDB-Datei angibt. Diese Variable ist optional.

Der Abschnitt variablen enthält Variablen, in denen beschrieben wird, wie eine Datei aus der Quellcodeverwaltung extrahiert wird. Es kann auch verwendet werden, um häufig verwendeten Text als Variablen zu definieren, um die Größe des Datenblocks zu reduzieren.

SRCSRVTRG

Beschreibt, wie der Zielpfad für die extrahierte Datei erstellt wird. Dies ist eine erforderliche Variable.

SRCSRVCMD

Beschreibt, wie Sie den Befehl erstellen, um die Datei aus der Quellcodeverwaltung zu extrahieren. Dies schließt den Namen der ausführbaren Datei und deren Befehlszeilenparameter ein. Dies ist eine erforderliche Variable.

SRCSRVENV

Eine Zeichenfolge, die Umgebungsvariablen auflistet, die während der Dateiextraktion erstellt werden sollen. Trennen Sie mehrere Einträge mit einem Rücktastenzeichen (\b). Dies ist eine optionale Variable.

Der Abschnitt Quelldateien enthält einen Eintrag für jede Quelldatei, die indiziert wurde. Die Inhalte jeder Zeile werden bis VAR10 als Variablen mit den Namen VAR1, VAR2, VAR3 usw. interpretiert. Die Variablen sind durch Sternchen getrennt. VAR1 muss den vollqualifizierten Pfad zur Quelldatei angeben, wie an anderer Stelle in der PDB-Datei aufgeführt. Beispiel: die folgende Zeile:

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

wird wie folgt interpretiert:

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

In diesem Beispiel ist VAR4 eine Versionsnummer. Die meisten Quellcodeverwaltungssysteme unterstützen jedoch die Bezeichnung von Dateien so, dass der Quellzustand für einen bestimmten Build wiederhergestellt werden kann. Daher können Sie alternativ die Bezeichnung für den Build verwenden. Der Beispieldatenblock kann so geändert werden, dass er eine Variable wie die folgende enthält:

LABEL=BUILD47

Angenommen, das Quellcodeverwaltungssystem verwendet das At-Zeichen (@), um eine Bezeichnung anzugeben, können Sie die SRCSRVCMD-Variable wie folgt ändern:

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

Funktionsweise des Quellservers

Der Quellserverclient wird in Symsrv.dll implementiert. Der Client extrahiert keine Informationen direkt aus der PDB-Datei. Es verwendet einen Symbolhandler, wie er in Dbghelp.dll implementiert ist. Es handelt sich im Wesentlichen um eine rekursive Variablenersetzungs-Engine, die eine Befehlszeile erstellt, mit der die richtige Quelldatei aus dem Quellcodeverwaltungssystem extrahiert werden kann. Ihr Code sollte Symsrv.dll nicht direkt aufrufen. Verwenden Sie die SymGetSourceFile-Funktion , um die Funktionalität in Ihre Anwendung zu integrieren.

Die erste Version des Quellservers funktioniert wie folgt. Dieses Verhalten kann sich in zukünftigen Versionen ändern.

• Der Client ruft die SrcSrvInit-Funktion mit dem Zielpfad auf, der als Basis für alle Quelldateiextraktionen verwendet werden soll. Dieser Pfad wird in der TARG-Variablen gespeichert.
• Der Client extrahiert den Srcsrv-Stream aus dem PDB, wenn das Modul PDB geladen wird, und ruft die SrcSrvLoadModule-Funktion auf, um den Datenblock an den Quellserver zu übergeben.
• Wenn Dbghelp eine Quelldatei abruft, ruft der Client die SrcSrvGetFile-Funktion auf, um die Quelldateien aus der Quellcodeverwaltung abzurufen.
• Der Quellserver durchsucht die Quelldateieinträge im Datenblock nach einem Eintrag, der der angeforderten Datei entspricht. Er füllt VAR1 bis VARn mit dem Inhalt des Quelldateieintrags aus. Als Nächstes wird die Variable SRCSRVTRG mithilfe von VAR1 zu VARn erweitert. Wenn sich die Datei bereits an diesem Speicherort befindet, wird der Speicherort an den Aufrufer zurückgegeben. Andernfalls wird die SRCSRVCMD-Variable erweitert, um den Befehl zu erstellen, der zum Abrufen der Datei aus der Quellcodeverwaltung und zum Kopieren an den Zielspeicherort erforderlich ist. Schließlich wird dieser Befehl ausgeführt.

Erstellen eines Moduls für den Quellcodeverwaltungsanbieter

Der Quellserver enthält Anbietermodule für Perforce (p4.pm) und Visual Source Safe (vss.pm). Um Ein eigenes Anbietermodul zu erstellen, müssen Sie die folgenden Schnittstellen implementieren.

$module::SimpleUsage()

Zweck: Zeigt einfache Modulnutzungsinformationen für STDOUT an.

Parameter: keine

Rückgabewert: Keine

$module::VerboseUsage()

Zweck: Zeigt ausführliche Modulnutzungsinformationen für STDOUT an.

Parameter: keine

Rückgabewert: Keine

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

Zweck: Initialisiert eine instance des Anbietermoduls.

Parameter: Alle @ARGV Argumente, die von SSIndex.cmd nicht als allgemeine Argumente erkannt wurden.

Rückgabewert: Ein Verweis, der in späteren Vorgängen verwendet werden kann.

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

Zweck: Ermöglicht dem Modul das Sammeln der erforderlichen Quellindizierungsinformationen für das durch den $SourcePath-Parameter angegebene Verzeichnis. Das Modul sollte nicht davon ausgehen, dass dieser Eintrag nur einmal für jedes Objekt instance aufgerufen wird, da SSIndex.cmd ihn für verschiedene Pfade mehrmals aufrufen kann.

Parameter: (1) Das lokale Verzeichnis, das die zu indizierte Quelle enthält. (2) Ein Verweis auf einen Hash, der alle Einträge aus der angegebenen Srcsrv.ini Datei enthält.

Rückgabewert: Keine

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

Zweck: Stellt die erforderlichen Informationen bereit, um eine einzelne, spezifische Datei aus dem Quellcodeverwaltungssystem zu extrahieren.

Parameter: Ein vollqualifizierter Dateiname

Rückgabewert: (1) Ein Hashverweis der Variablen, die zum Interpretieren der zurückgegebenen $FileEntry erforderlich sind. SSIndex.cmd speichert diese Variablen für jede Quelldatei zwischen, die von einer einzelnen Debugdatei verwendet wird, um die Menge der in den Quellindexdatenstrom geschriebenen Informationen zu reduzieren. (2) Der Dateieintrag, der in den Quellindexdatenstrom geschrieben werden soll, damit SrcSrv.dll diese Datei aus der Quellcodeverwaltung extrahieren können. Das genaue Format dieser Zeile ist spezifisch für das Quellcodeverwaltungssystem.

$TextString = $objref-LongName>()

Zweck: Stellt eine beschreibende Zeichenfolge bereit, um den Quellcodeverwaltungsanbieter für den Endbenutzer zu identifizieren.

Parameter: keine

Rückgabewert: Der beschreibende Name des Quellcodeverwaltungssystems.

@StreamVariableLines = $objref-SourceStreamVariables>()

Zweck: Ermöglicht dem Quellcodeverwaltungsanbieter das Hinzufügen spezifischer Variablen zum Quellstream für jede Debugdatei. Die Beispielmodule verwenden diese Methode zum Schreiben der erforderlichen EXTRACT_CMD und EXTRACT_TARGET Variablen.

Parameter: keine

Rückgabewert: Die Liste der Einträge für die Quellstreamvariablen.