Sprachspezifikation 1
Hinweis
In diesem Thema wird der interne Betrieb von SrcSrv beschrieben. Allgemeine Informationen zur Funktionsweise von Quellpfaden finden Sie unter Quellpfad. Informationen zur Verwendung von SrcSrv finden Sie unter Verwenden von SrcSrv. Um den aktuellen Vorgang des Ladens von Quellen in Ihrer Umgebung zu bestimmen, aktivieren Sie das laden von quellen lauten Quellen, wie unter .srcnoisy (Noisy Source Loading) beschrieben.
Die erste Version von SrcSrv funktioniert wie folgt. (Dieses Verhalten kann sich in zukünftigen Versionen ändern.)
Zunächst ruft der Client SrcSrvInit mit dem Zielpfad auf, der als Basis für alle Quelldateiextraktionen verwendet werden soll. Dieser Pfad wird in der speziellen Variablen TARG gespeichert.
Wenn DbgHelp die PDB-Datei eines Moduls lädt, extrahiert es den SrcSrv-Stream aus der PDB-Datei und übergibt diesen Datenblock an SrcSrv, indem SrcSrvLoadModule aufgerufen wird.
Wenn DbgHelp dann eine Quelldatei abrufen muss, ruft es SrcSrvGetFile auf, um eine angegebene Quelldatei aus der Versionskontrolle abzurufen.
SrcSrv überprüft alle Quelldateieinträge im Datenblock auf einen Eintrag, der genau der angeforderten Quellspezifikation entspricht. Diese Übereinstimmung befindet sich in VAR1.
Nachdem SrcSrv den Eintrag gefunden hat, füllt es die speziellen Variablen (VAR1, VAR2 usw.) mit dem Inhalt dieses Quelldateieintrags aus. Anschließend wird die SRCSRVTRG-Variable mithilfe dieser speziellen Variablen aufgelöst.
Im Folgenden wird gezeigt, wie die Variable SRCSRVTRG mithilfe der speziellen Variablen aufgelöst wird. Wir gehen davon aus, dass der Quellpfad weiterhin lautet:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
Jede Zeile zeigt die Auflösung einer weiteren speziellen Variablen an. Die aufgelösten Variablen sind fett formatiert.
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
Beachten Sie, dass dieser generierte Zielpfad eindeutig ist und nicht zulässt, dass zwei Versionen derselben Datei an denselben Speicherort extrahiert werden.
SrcSrv sucht nun, ob die Datei bereits vorhanden ist. Wenn dies der Grund ist, gibt SrcSrv den Speicherort an den Aufrufer zurück. Andernfalls erstellt SrcSrv den Ausführungsbefehl, um die Datei zu extrahieren, indem SRCSRVCMD aufgelöst wird.
Im folgenden Beispiel zeigt jede Zeile die Auflösung einer weiteren speziellen Variablen an. Die aufgelösten Variablen sind fett formatiert.
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
Jetzt führt SrcSrv diesen Befehl aus. Wenn das Ergebnis dieses Befehls eine Datei am erwarteten Speicherort ist, wird dieser Pfad an den Aufrufer zurückgegeben.
Wenn eine Variable nicht aufgelöst werden kann, wird versucht, sie als Betriebssystemumgebungsvariable nachzuschlagen. Wenn dies fehlschlägt, wird der Variablenname aus dem zu verarbeitenden Text gelöscht.
Zwei aufeinander folgende Prozentzeichen werden als einzelnes Prozentzeichen interpretiert.
Quellserverdatenblöcke
SrcSrv basiert auf zwei Datenblöcken in der PDB-Datei, der Quelldateiliste und dem Datenblock.
Die Quelldateiliste wird automatisch erstellt, wenn ein Modul erstellt wird. Diese Liste enthält vollqualifizierte Pfade zu den Quelldateien, die zum Erstellen des Moduls verwendet werden.
Der Datenblock wird während der Quellindizierung erstellt. Zu diesem Zeitpunkt wird der PDB-Datei ein alternativer Stream namens "srcsrv" hinzugefügt. Welches Skript diese Daten einfügt, hängt vom jeweiligen Buildprozess und dem verwendeten Quellcodeverwaltungssystem ab.
Der Datenblock ist in drei Abschnitte unterteilt: ini, variablen und Quelldateien. Der Datenblock 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 (%) eingeschlossen ist. In Prozentzeichen eingeschlossener Text 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 zu auflösende Variable behandelt werden.
%fnbksl%()
Alle Schrägstriche (/) im Parametertext sollten durch rückwärts gerichtete Schrägstriche () ersetzt werden.
%fnfile%()
Alle Pfadinformationen im Parametertext sollten entfernt werden, sodass nur der Dateiname übrig bleibt.
Der Abschnitt [ini] des Datenblocks 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. Wenn Sie ein Skript basierend auf der aktuellen Sprachspezifikation entwickeln, legen Sie diesen Wert auf 1 fest. Der SrcSrv-Clientcode versucht nicht, ein Skript auszuführen, das über einen wert größer als sein eigenes verfügt. Aktuelle Versionen von SrcSrv verwenden den Wert 2.
VERCTRL
Eine Zeichenfolge, die das Quellcodeversionskontrollsystem 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 [variables] des Datenblocks enthält Variablen, die beschreiben, wie eine Datei aus der Quellcodeverwaltung extrahiert wird. Er 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 erforderlich, wenn ein Extraktionsbefehl ausgeführt werden muss.
SRCSRVENV
Listet Umgebungsvariablen auf, die während der Dateiextraktion erstellt werden sollen. Dies ist eine Zeichenfolge. Trennen Sie mehrere Einträge mit einem Rücktastenzeichen (\b). Dies ist eine optionale Variable.
SRCSRVVERCTRL
Gibt das verwendete Versionskontrollsystem an. Für Perforce ist dies perforce. Für Team Foundation Server ist dies tfs. Diese Variable wird verwendet, um Serverfehler beizubehalten. Dies ist eine optionale Variable.
SRCSRVVERRDESC
Gibt den Text an, der angezeigt werden soll, wenn der Versionskontrolle-Client den Server, der die zu extrahierenden Quelldateien enthält, nicht kontaktieren kann. SrcSrv verwendet diesen Wert, um auf Verbindungsprobleme zu überprüfen. Dies ist eine optionale Variable.
SRCSRVERRVAR
Gibt an, welche Variable in einem Dateieintrag einem Versionskontrollserver entspricht. Es wird von SrcSrv verwendet, um Befehle zu identifizieren, die nicht funktionieren, basierend auf vorherigen Fehlern. Das Format des Texts ist varX , wobei X die Nummer der angegebenen Variablen ist. Dies ist eine optionale Variable.
Der Abschnitt [Quelldateien] des Datenblocks 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:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
folgendermaßen interpretiert:
VAR1=c:\proj\src\file.cpp
VAR2=TOOLS_PRJ
VAR3=tools/mytool/src/file.cpp
VAR4=3
In diesem Beispiel ist VAR4 eine Revisionsnummer. 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 stattdessen die Bezeichnung für den Build verwenden. Der Beispieldatenblock könnte so geändert werden, dass er eine Variable wie die folgende enthält:
LABEL=BUILD47
Wenn das Quellcodeverwaltungssystem z. B. das At-Zeichen (@) verwendet, um eine Bezeichnung anzugeben, könnten Sie die SRCSRVCMD-Variable wie folgt ändern:
sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%
Behandeln von Serverfehlern
Manchmal kann ein Client überhaupt keine Dateien von einem einzelnen Versionskontrollserver extrahieren. Dies kann darauf zurückzuführen sein, dass der Server ausgefallen und nicht im Netzwerk ist, oder weil der Benutzer nicht über die entsprechenden Berechtigungen für den Zugriff auf die Quelle verfügt. Die Zeit, die beim Abrufen dieser Quelle verbraucht wird, kann dies jedoch erheblich verlangsamen. In diesem Fall empfiehlt es sich, jeden Versuch zu deaktivieren, aus einer Quelle zu extrahieren, die nachweislich nicht verfügbar ist.
Wenn SrcSrv eine Datei nicht extrahieren kann, wird der vom Befehl erzeugte Ausgabetext untersucht. Wenn ein Teil dieses Befehls eine genaue Übereinstimmung mit dem Inhalt des SRCSRVERRDESC enthält, werden alle zukünftigen Befehle an denselben Versionskontrollserver übersprungen. Beachten Sie, dass Sie mehrere Fehlerzeichenfolgen definieren können, indem Sie Zahlen oder beliebigen Text am Ende des SRCSRVERRDESC-Variablennamens hinzufügen. Beispiel:
SRCSRVERRDESC=lime: server not found
SRCSRVERRDESC_2=pineapple: network error
Die Identität des Servers wird von SRCSRVERRVAR abgerufen. Wenn SRCSRVERRVAR also "var2" enthält und der Dateieintrag in der PDB-Datei wie folgt aussieht:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
alle zukünftigen Versuche, die Quelle mithilfe eines Dateieintrags abzurufen, der "TOOLS_PRJ" in Variable 2 enthält, werden umgangen.
Sie können auch Fehlerindikatoren auf dem Debuggerclient hinzufügen, indem Sie Srcsrv.inibearbeiten. Weitere Informationen finden Sie in der enthaltenen Beispielversion von srcsrv.ini.