Specifikace jazyka 1

Poznámka:

Toto téma popisuje interní provoz SrcSrv. Obecné informace o tom, jak zdrojové cesty fungují, najdete v tématu Zdrojová cesta. Informace o použití SrcSrv naleznete v tématu Použití SrcSrv. Pokud chcete zjistit aktuální operaci načítání zdroje ve vašem prostředí, povolte hlučné zdrojové načítání, jak je popsáno v souboru .srcnoisy (Noisy Source Loading).

První verze SrcSrv funguje následovně. (Toto chování se může v budoucích verzích změnit.)

Nejprve klient volá SrcSrvInit s cílovou cestou, která se má použít jako základ pro všechny extrakce zdrojových souborů. Tato cesta je uložena ve speciální proměnné TARG.

Když DbgHelp načte soubor .pdb modulu, extrahuje stream SrcSrv ze souboru .pdb a předá tento datový blok SrcSrv voláním SrcSrvLoadModule.

Když dbgHelp potřebuje získat zdrojový soubor, volá SrcSrvGetFile pro načtení zadaného zdrojového souboru ze správy verzí.

SrcSrv zkontroluje všechny položky zdrojového souboru v bloku dat pro položku, která odpovídá přesně požadované specifikaci zdroje. Tato shoda se nachází ve VAR1.

Jakmile SrcSrv najde položku, vyplní speciální proměnné (VAR1, VAR2 atd.) obsahem této položky zdrojového souboru. Potom se proměnná SRCSRVTRG vyřeší pomocí těchto speciálních proměnných.

Následující příklad ukazuje, jak je proměnná SRCSRVTRG vyřešena pomocí speciálních proměnných. Předpokládáme, že zdrojová cesta je stále:

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

Každý řádek zobrazuje rozlišení jedné další speciální proměnné. Vyřešené proměnné jsou tučné.

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

Všimněte si, že tato generovaná cílová cesta je jedinečná a neumožňuje extrahování dvou verzí stejného souboru do stejného umístění.

SrcSrv teď hledá, jestli už soubor existuje. Pokud ano, vrátí SrcSrv volajícímu umístění. Jinak SrcSrv sestaví příkaz ke spuštění pro extrahování souboru vyřešením SRCSRVCMD.

V následujícím příkladu každý řádek zobrazuje rozlišení jedné další speciální proměnné. Vyřešené proměnné jsou tučné.

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 

Teď SrcSrv spustí tento příkaz. Pokud je výsledkem tohoto příkazu soubor v očekávaném umístění, vrátí se tato cesta volajícímu.

Všimněte si, že pokud proměnnou nelze přeložit, pokusí se ji vyhledat jako proměnnou prostředí operačního systému. Pokud se to nezdaří, název proměnné se odstraní z textu, který se zpracovává.

Dva po sobě jdoucí znaky procenta se interpretují jako jeden znak procenta.

Bloky dat zdrojového serveru

SrcSrv spoléhá na dva bloky dat v souboru .pdb, seznam zdrojových souborů a datový blok.

Seznam zdrojových souborů se vytvoří automaticky při vytváření modulu. Tento seznam obsahuje plně kvalifikované cesty ke zdrojovým souborům používaným k sestavení modulu.

Blok dat se vytvoří během indexování zdroje. V tuto chvíli se do souboru .pdb přidá alternativní datový proud s názvem srcsrv. Skript, který vloží tato data, závisí na konkrétním používaném procesu sestavení a systému správy zdrojového kódu.

Datový blok je rozdělený do tří částí: ini, proměnné a zdrojové soubory. Blok dat má následující syntaxi.

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

Veškerý text je interpretován doslova, s výjimkou textu uzavřeného ve znaménka procent (%). Text uzavřený ve znaménka procent se považuje za název proměnné, který se má přeložit rekurzivně, pokud se nejedná o jednu z následujících funkcí:

%fnvar%()
Text parametru by měl být uzavřený ve znaménka procent a považován za proměnnou, která se má vyřešit.

%fnbksl%()
Všechna lomítka (/) v textu parametru by měla být nahrazena zpětnými lomítky ().

%fnfile%()
Všechny informace o cestě v textu parametru by se měly odstranit a ponechat jenom název souboru.

Oddíl [ini] datového bloku obsahuje proměnné, které popisují požadavky. Skript indexování může do této části přidat libovolný počet proměnných. Následují příklady:

VERZE
Verze specifikace jazyka. Tato proměnná je povinná. Pokud vyvíjíte skript založený na specifikaci aktuálního jazyka, nastavte tuto hodnotu na hodnotu 1. Kód klienta SrcSrv se nepokouší spustit žádný skript, který má hodnotu větší než jeho vlastní. Aktuální verze SrcSrv používají hodnotu 2.

VERCTRL
Řetězec, který popisuje systém správy verzí zdrojového kódu. Tato proměnná je volitelná.

DATETIME
Řetězec, který označuje datum a čas zpracování souboru .pdb. Tato proměnná je volitelná.

Část [proměnné] datového bloku obsahuje proměnné, které popisují, jak extrahovat soubor ze správy zdrojového kódu. Dá se také použít k definování běžně používaného textu jako proměnných, aby se zmenšila velikost datového bloku.

SRCSRVTRG
Popisuje, jak vytvořit cílovou cestu pro extrahovaný soubor. Jedná se o požadovanou proměnnou.

SRCSRVCMD
Popisuje, jak sestavit příkaz pro extrahování souboru ze správy zdrojového kódu. To zahrnuje název spustitelného souboru a jeho parametrů příkazového řádku. To se vyžaduje, pokud se musí provést jakýkoli příkaz pro extrakci.

SRCSRVENV
Zobrazí seznam proměnných prostředí, které se mají vytvořit během extrahování souborů. Jedná se o řetězec. Oddělte více položek znakem backspace (\b). Jedná se o volitelnou proměnnou.

SRCSRVVERCTRL
Určuje systém správy verzí, který se používá. Pro Perforce je to samozřejmé. Pro Team Foundation Server je to tfs. Tato proměnná se používá k zachování chyb serveru. Jedná se o volitelnou proměnnou.

SRCSRVVERRDESC
Určuje text, který se má zobrazit, když klient správy verzí nemůže kontaktovat server, který obsahuje zdrojové soubory k extrakci. SrcSrv používá tuto hodnotu ke kontrole problémů s připojením. Jedná se o volitelnou proměnnou.

SRCSRVERRVAR
Určuje, která proměnná v položce souboru odpovídá serveru správy verzí. Nástroj SrcSrv ho používá k identifikaci příkazů, které nefungují na základě předchozích selhání. Formát textu je varX , kde X je číslo proměnné, která je označena. Jedná se o volitelnou proměnnou.

Oddíl [zdrojové soubory] bloku dat obsahuje položku pro každý zdrojový soubor, který byl indexován. Obsah každého řádku se interpretuje jako proměnné s názvy VAR1, VAR2, VAR3 atd. do var10. Proměnné jsou oddělené hvězdičkami. Var1 musí zadat plně kvalifikovanou cestu ke zdrojovému souboru, jak je uvedeno jinde v souboru .pdb. Například:

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

interpretuje se takto:

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

V tomto příkladu je var4 číslo revize. Většina systémů správy zdrojového kódu ale podporuje soubory popisování tak, aby bylo možné obnovit zdrojový stav daného sestavení. Proto byste místo toho mohli použít popisek pro sestavení. Ukázkový datový blok lze upravit tak, aby obsahoval proměnnou, například následující:

LABEL=BUILD47 

Potom předpokládejme, že systém správy zdrojového kódu používá znak at (@) k označení popisku, můžete proměnnou SRCSRVCMD upravit následujícím způsobem:

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

Zpracování chyb serveru

Klient někdy nemůže extrahovat žádné soubory z jednoho serveru správy verzí. Důvodem může být to, že server je mimo síť nebo protože uživatel nemá příslušná oprávnění pro přístup ke zdroji. Čas strávený pokusy o získání tohoto zdroje však může věci výrazně zpomalit. V této situaci je nejlepší zakázat všechny pokusy o extrakci ze zdroje, který byl prokázáno, že není k dispozici.

Pokaždé, když SrcSrv selže při extrahování souboru, zkontroluje výstupní text vytvořený příkazem. Pokud některá část tohoto příkazu obsahuje přesnou shodu s obsahem SRCSRVERRDESC, všechny budoucí příkazy na stejný server správy verzí se přeskočí. Všimněte si, že můžete definovat více chybových řetězců přidáním čísel nebo libovolného textu na konec názvu proměnné SRCSRVERRDESC. Tady je příklad:

SRCSRVERRDESC=lime: server not found
SRCSRVERRDESC_2=pineapple: network error

Identita serveru je získána ze služby SRCSRVERRVAR. Takže pokud SRCSRVERRVAR obsahuje "var2" a položka souboru v souboru .pdb vypadá takto:

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

Všechny budoucí pokusy o získání zdroje pomocí položky souboru, která obsahuje "TOOLS_PRJ" v proměnné 2, jsou vynechány.

Indikátory chyb můžete také přidat v klientovi ladicího programu úpravou Srcsrv.ini. Podrobnosti najdete v zahrnuté ukázkové verzi srcsrv.ini.