Zdrojový server

Zdrojový server umožňuje klientovi načíst přesnou verzi zdrojových souborů, které byly použity k sestavení aplikace. Vzhledem k tomu, že se zdrojový kód modulu může mezi verzemi a v průběhu let měnit, je důležité se podívat na zdrojový kód, jak existoval, když byla vytvořená verze daného modulu.

Zdrojový server načte příslušné soubory ze správy zdrojového kódu. Aby bylo možné použít zdrojový server, musí být aplikace indexovaná.

Indexování zdrojového kódu

Zdrojový systém indexování je kolekce spustitelných souborů a skriptů Perl. Skripty Perl vyžadují Perl 5,6 nebo vyšší.

Binární soubory se obvykle indexují během procesu sestavení po sestavení aplikace. Informace potřebné zdrojovým serverem jsou uloženy v souborech PDB.

Zdrojový server se aktuálně dodává se skripty, které by měly fungovat s následujícími systémy správy zdrojového kódu.

• Team Foundation Server
• Chtě nechtě
• Visual SourceSafe
• CVS
• Svrhnutí

Můžete také vytvořit vlastní skript pro indexování kódu pro jiný systém správy zdrojového kódu.

Následující tabulka uvádí nástroje zdrojového serveru.

Nástroj	Popis
Srcsrv.ini	Tento soubor je hlavním seznamem všech serverů správy zdrojového kódu. Každá položka má následující formát:MYSERVER=serverinfo Při použití Perforce se informace o serveru skládají z celé síťové cesty k serveru a za ní dvojtečku následovanou číslem portu, které používá. Například: MYSERVER=machine.corp.company.com:1666 Tento soubor lze nainstalovat do počítače, na kterém běží ladicí program. Při spuštění zdrojového serveru se podívá na Srcsrv.ini hodnot; tyto hodnoty přepíší informace obsažené v souboru PDB. To umožňuje uživatelům nakonfigurovat ladicí program tak, aby používal alternativní server správy zdrojového kódu v době ladění. Další informace najdete v příkladu Srcsrv.ini nainstalované pomocí nástrojů zdrojového serveru.
Ssindex.cmd	Tento skript sestaví seznam souborů vrácených do správy zdrojového kódu spolu s informacemi o verzi každého souboru. Ukládá podmnožinu těchto informací do souborů .pdb vygenerovaných při vytváření aplikace. Skript používá pro rozhraní se správou zdrojového kódu jeden z následujících modulů Perl: P4.pm (Perforce) nebo Vss.pm (Visual Source Safe). Další informace potřebujete spustit pomocí příkazu -? nebo-?? (podrobná nápověda) nebo prozkoumejte skript.
Srctool.exe	Tento nástroj zobrazí seznam všech souborů indexovaných v souboru .pdb. Pro každý soubor obsahuje úplnou cestu, server správy zdrojového kódu a číslo verze souboru. Tyto informace můžete použít k načtení souborů bez použití zdrojového serveru. Další informace potřebujete spuštěním nástroje /? možnost.
Pdbstr.exe	Tento nástroj používá indexovací skripty k vložení informací o správě verzí do alternativního datového proudu srcsrv cílového souboru .pdb. Může také číst jakýkoli datový proud ze souboru .pdb. Tyto informace můžete použít k ověření správného fungování skriptů indexování. Další informace potřebujete spuštěním nástroje /? možnost.

 

Načítání zdrojového souboru

Rozhraní DBgHelp API poskytuje přístup k funkcím zdrojového serveru prostřednictvím funkce SymGetSourceFile. Chcete-li načíst název zdrojového souboru, zavolejte SymEnumSourceFiles nebo SymGetLineFromAddr64 funkce.

Použití zdrojového serveru s ladicím programem

Pokud chcete použít zdrojový server s WinDbg, KD, NTSD nebo CDB, ujistěte se, že máte nainstalovanou nejnovější verzi balíčku Nástroje ladění pro Windows (verze 6.3 nebo novější). Potom do příkazu .srcpath zahrňte srv* následujícím způsobem:

.srcpath srv*;c:\mysource

Všimněte si, že tento příklad obsahuje také tradiční zdrojovou cestu. Pokud ladicí program nemůže načíst soubor ze zdrojového serveru, vyhledá zadanou cestu.

Pokud zdrojový soubor načte zdrojový server, zůstane na pevném disku i po ukončení ladicí relace. Zdrojové soubory jsou uloženy místně v podadresáři src instalačního adresáře Nástroje ladění pro Systém Windows.

Bloky dat zdrojového serveru

Zdrojový server spoléhá na dva bloky dat v souboru PDB.

• Seznam zdrojových souborů Vytvoření modulu automaticky vytvoří seznam plně kvalifikovaných cest ke zdrojovým souborům používaným k sestavení modulu.
• Blok dat Indexování zdroje, jak je popsáno výše, přidá do souboru PDB 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.

Ve specifikaci jazyka verze 1 je datový blok rozdělen do tří částí: ini, proměnné a zdrojové soubory. 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á rozbalit.

%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 obsahuje proměnné, které popisují požadavky. Skript indexování může do této části přidat libovolný počet proměnných. Tady jsou příklady:

verze

Verze specifikace jazyka. Tato proměnná je povinná.

VERCTL

Řetězec, který popisuje produkt správy 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á.

Oddíl proměnných 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. Jedná se o požadovanou proměnnou.

SRCSRVENV

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

Oddíl zdrojových souborů 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 následující řádek:

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 verze. 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 můžete alternativně 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%) -o %srcsrvtrg% -q %depot%/%var3%@%label%

Jak funguje zdrojový server

Zdrojový server klient je implementován v Symsrv.dll. Klient neextrahuje informace přímo ze souboru PDB; používá obslužnou rutinu symbolu, například obslužnou rutinu implementovanou v Dbghelp.dll. Jedná se v podstatě o rekurzivní modul nahrazení proměnných, který vytvoří příkazový řádek, který lze použít k extrahování správného zdrojového souboru ze systému správy zdrojového kódu. Kód by neměl volat Symsrv.dll přímo. K integraci jeho funkcí do vaší aplikace použijte funkci SymGetSourceFile.

První verze zdrojového serveru funguje následovně. Toto chování se může v budoucích verzích změnit.

• Klient volá funkci SrcSrvInit s cílovou cestou, která se má použít jako základ pro všechny extrakce zdrojových souborů. Uloží tuto cestu do proměnné TARG.
• Klient extrahuje datový proud Srcsrv z PDB při načtení modulu PDB a zavolá SrcSrvLoadModule funkce předat blok dat zdrojovému serveru.
• Když Dbghelp načte zdrojový soubor, klient zavolá funkci SrcSrvGetFile k načtení zdrojových souborů ze správy zdrojového kódu.
• Zdrojový server vyhledá položky zdrojového souboru v bloku dat pro položku, která odpovídá požadovanému souboru. Vyplní var1 až VARn obsahem položky zdrojového souboru. Dále rozbalí proměnnou SRCSRVTRG pomocí var1 na varn. Pokud je soubor již v tomto umístění, vrátí umístění volajícímu. V opačném případě rozbalí proměnnou SRCSRVCMD, aby se vytvořil příkaz potřebný k načtení souboru ze správy zdrojového kódu a jeho zkopírování do cílového umístění. Nakonec spustí tento příkaz.

Vytvoření modulu zprostředkovatele správy zdrojového kódu

Zdrojový server obsahuje moduly poskytovatele pro Perforce (p4.pm) a Visual Source Safe (vss.pm). Pokud chcete vytvořit vlastní modul poskytovatele, musíte implementovat následující sadu rozhraní.

$module::SimpleUsage()

Účel: Zobrazí informace o použití jednoduchého modulu do STDOUT.

Parametry: Žádné

Návratová hodnota: None

$module::VerboseUsage()

Účel: Zobrazí podrobné informace o využití modulu stDOUT.

Parametry: Žádné

Návratová hodnota: None

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

Účel: Inicializuje instanci modulu zprostředkovatele.

Parametry: Všechny @ARGV argumenty, které SSIndex.cmd nerozpoznaly jako obecné argumenty.

Návratová hodnota: Odkaz, který lze použít v pozdějších operacích.

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

Účel: Umožňuje modulu shromáždit požadované informace o indexování zdroje pro adresář určený parametrem $SourcePath. Modul by neměl předpokládat, že tato položka bude volána pouze jednou pro každou instanci objektu, protože SSIndex.cmd ji může volat vícekrát pro různé cesty.

Parametry: (1) Místní adresář obsahující zdroj, který se má indexovat. (2) Odkaz na hodnotu hash obsahující všechny položky ze zadaného souboru Srcsrv.ini.

Návratová hodnota: None

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

Účel: Poskytuje potřebné informace k extrakci jednoho konkrétního souboru ze systému správy zdrojového kódu.

Parametry: Plně kvalifikovaný název souboru

Návratová hodnota: (1) Odkaz na hodnotu hash proměnných nezbytných k interpretaci vrácených $FileEntry. SSIndex.cmd tyto proměnné ukládá do mezipaměti pro každý zdrojový soubor používaný jedním ladicím souborem, aby se snížilo množství informací zapsaných do streamu zdrojového indexu. (2) Položka souboru, která má být zapsána do streamu zdrojového indexu, aby SrcSrv.dll extrahovat tento soubor ze správy zdrojového kódu. Přesný formát tohoto řádku je specifický pro systém správy zdrojového kódu.

$TextString = $objref->LongName()

Účel: Poskytuje popisný řetězec pro identifikaci zprostředkovatele správy zdrojového kódu koncovému uživateli.

Parametry: Žádné

Návratová hodnota: Popisný název systému správy zdrojového kódu.

@StreamVariableLines = $objref->SourceStreamVariables()

Účel: Umožňuje poskytovateli správy zdrojového kódu přidat proměnné specifické pro správu zdrojového kódu do zdrojového streamu pro každý ladicí soubor. Ukázkové moduly používají tuto metodu pro psaní požadovaných EXTRACT_CMD a EXTRACT_TARGET proměnných.

Parametry: Žádné

Návratová hodnota: Seznam položek pro proměnné zdrojového datového proudu.