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 Versionen und im Laufe von Jahren ändern kann, ist es wichtig, den Quellcode so zu betrachten, wie es vorhanden war, als die betreffende Version des betreffenden Moduls erstellt wurde.

Der Quellserver ruft die entsprechenden Dateien aus der Quellcodeverwaltung ab. Um den Quellserver zu verwenden, muss die Anwendung indiziert 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 indiziert, nachdem die Anwendung erstellt wurde. Die vom Quellserver benötigten Informationen werden in den PDB-Dateien gespeichert.

Der Quellserver wird derzeit mit Skripts ausgeliefert, die mit den folgenden Quellcodeverwaltungssystemen funktionieren sollten.

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

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

In der folgenden Tabelle sind die Quellservertools aufgeführt.

Werkzeug	Beschreibung
Srcsrv.ini	Diese Datei ist die Masterliste aller Quellcodeverwaltungsserver. Jeder Eintrag hat das folgende Format:MYSERVER=serverinfo Bei Verwendung von Perforce besteht die Serverinformationen aus dem vollständigen Netzwerkpfad zum Server, gefolgt von einem Doppelpunkt, gefolgt von der verwendeten Portnummer. Zum 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 nach Werten Srcsrv.ini gesucht. diese Werte setzen die in der PDB-Datei enthaltenen Informationen außer Kraft. Auf diese Weise können Benutzer einen Debugger konfigurieren, um zur Debugzeit einen alternativen Quellcodeverwaltungsserver zu verwenden. 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, sowie die Versionsinformationen jeder Datei. Sie speichert eine Teilmenge dieser Informationen in den PDB-Dateien, die beim Erstellen der Anwendung generiert wurden. Das Skript verwendet eines der folgenden Perl-Module, um eine Schnittstelle mit der Quellcodeverwaltung zu erstellen: P4.pm (Perforce) oder Vss.pm (Visual Source Safe). Um weitere Informationen zu erfahren, führen Sie das Skript mit dem -? oder-?? (ausführliche Hilfe) Option oder Untersuchen des Skripts.
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. Wenn Sie weitere Informationen wünschen, führen Sie das Hilfsprogramm mit dem /? Option.
Pdbstr.exe	Dieses Hilfsprogramm wird von den Indizierungsskripts verwendet, um die Versionssteuerungsinformationen in den alternativen Stream "srcsrv" der ZIEL-PDB-Datei einzufügen. Sie kann auch einen beliebigen Datenstrom aus einer PDB-Datei lesen. Mithilfe dieser Informationen können Sie überprüfen, ob die Indizierungsskripts ordnungsgemäß funktionieren. Wenn Sie weitere Informationen wünschen, führen Sie das Hilfsprogramm mit dem /? Option.

 

Abrufen der Quelldatei

Die DbgHelp-API bietet Zugriff auf die Quellserverfunktionalität über die SymGetSourceFile--Funktion. Rufen Sie zum Abrufen des Namens der abzurufenden Quelldatei die SymEnumSourceFiles- oder SymGetLineFromAddr64--Funktion 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 der Debugtools für Windows-Paket (Version 6.3 oder höher) installiert haben. Schließen Sie dann srv* in den Befehl ".srcpath" wie folgt 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, wird der angegebene Pfad durchsucht.

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

Quellserverdatenblöcke

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

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

In der Sprachspezifikation Version 1 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 buchstäblich interpretiert, mit Ausnahme von Text, der in Prozentzeichen (%) eingeschlossen ist. 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 Schrägstriche (\) ersetzt werden.

%fnfile%()

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

Der Ini-Abschnitt enthält Variablen, die die Anforderungen beschreiben. Das Indizierungsskript kann diesem Abschnitt eine beliebige Anzahl von Variablen hinzufügen. Im Folgenden sind Beispiele aufgeführt:

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, die beschreiben, wie eine Datei aus der Quellcodeverwaltung extrahiert wird. Sie kann auch verwendet werden, um häufig verwendeten Text als Variablen zu definieren, um die Größe des Datenblocks zu verringern.

SRCSRVTRG

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

SRCSRVCMD

Beschreibt, wie der Befehl erstellt wird, um die Datei aus der Quellcodeverwaltung zu extrahieren. Dies schließt den Namen der ausführbaren Datei und der zugehörigen 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. Der Inhalt jeder Zeile wird als Variablen mit den Namen VAR1, VAR2, VAR3 usw. interpretiert, bis VAR10. Die Variablen werden durch Sternchen getrennt. VAR1 muss den vollqualifizierten Pfad zur Quelldatei angeben, wie an anderer Stelle in der PDB-Datei aufgeführt. Beispielsweise 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 das Bezeichnen von Dateien so, dass der Quellzustand für einen bestimmten Build wiederhergestellt werden kann. Daher könnten Sie alternativ die Bezeichnung für den Build verwenden. Der Beispieldatenblock kann so geändert werden, dass er eine Variable enthält, z. B. folgendes:

LABEL=BUILD47

Anschließend können Sie die Variable SRCSRVCMD wie folgt ändern, indem Sie das At-Zeichen (@) verwenden, um eine Bezeichnung anzugeben:

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

Funktionsweise des Quellservers

Der Quellserverclient wird in Symsrv.dllimplementiert. Der Client extrahiert keine Informationen direkt aus der PDB-Datei; es verwendet einen Symbolhandler, z. B. die in Dbghelp.dllimplementierte. Es handelt sich im Wesentlichen um ein rekursives Variablenersetzungsmodul, das 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. Er speichert diesen Pfad in der TARG-Variablen.
• Der Client extrahiert den Srcsrv-Datenstrom 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. Es füllt VAR1 bis VARn mit dem Inhalt des Quelldateieintrags. Als Nächstes wird die SRCSRVTRG-Variable mithilfe von VAR1 auf VARnerweitert. 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 benötigt wird, und sie an den Zielspeicherort zu kopieren. Schließlich wird dieser Befehl ausgeführt.

Erstellen eines Anbietermoduls für die Quellcodeverwaltung

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 Modulverwendungsinformationen für STDOUT an.

Parameter: Keine

Rückgabewert: Keine

$module::VerboseUsage()

Zweck: Zeigt detaillierte Modulverwendungsinformationen für STDOUT an.

Parameter: Keine

Rückgabewert: Keine

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

Zweck: Initialisiert eine Instanz 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 es dem Modul, die erforderlichen Quellindizierungsinformationen für das durch den parameter $SourcePath angegebene Verzeichnis zu sammeln. Das Modul sollte nicht davon ausgehen, dass dieser Eintrag nur einmal für jede Objektinstanz 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 diese Variablen für jede Quelldatei zwischenspeichert, die von einer einzelnen Debugdatei verwendet wird, um die Menge der informationen zu reduzieren, die in den Quellindexdatenstrom geschrieben wurden. (2) Der Dateieintrag, der in den Quellindexdatenstrom geschrieben werden soll, damit SrcSrv.dll diese Datei aus der Quellcodeverwaltung extrahieren kann. 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 es dem Quellcodeverwaltungsanbieter, dem Quelldatenstrom für jede Debugdatei bestimmte Variablen hinzuzufügen. 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 Quelldatenstromvariablen.