Forráskiszolgáló

A forráskiszolgáló lehetővé teszi, hogy az ügyfél lekérje az alkalmazás létrehozásához használt forrásfájlok pontos verzióját. Mivel egy modul forráskódja változhat a verziók és az évek során, fontos, hogy a forráskódot úgy tekintse meg, ahogyan az a szóban forgó modul verziójának létrehozásakor létezett.

A forráskiszolgáló lekéri a megfelelő fájlokat a forrásvezérlőből. A forráskiszolgáló használatához az alkalmazásnak forrásindexeltnek kell lennie.

Forrásindexelés

A forrásindexelő rendszer végrehajtható fájlok és Perl-szkriptek gyűjteménye. A Perl-szkriptekhez perl 5.6-os vagy újabb verzió szükséges.

A bináris fájlok általában a buildelési folyamat során indexelhetők az alkalmazás létrehozása után. A forráskiszolgáló által szükséges információk a PDB-fájlokban lesznek tárolva.

A forráskiszolgáló jelenleg olyan szkripteket használ, amelyeknek az alábbi forrásvezérlő rendszerekkel kell működnie.

• Team Foundation Server
• Szükségképpen
• Visual SourceSafe
• CVS
• Felforgatás

Létrehozhat egy egyéni szkriptet is, amely egy másik forrásvezérlő rendszerhez indexeli a kódot.

Az alábbi táblázat a forráskiszolgáló eszközeit sorolja fel.

Eszköz	Leírás
Srcsrv.ini	Ez a fájl az összes forrásvezérlő kiszolgáló fő listája. Minden bejegyzés formátuma a következő:MYSERVER=serverinfo A Perforce használatakor a kiszolgáló adatai a kiszolgáló teljes hálózati elérési útját, majd egy kettőspontot, majd az általa használt portszámot alkotják. Például: MYSERVER=machine.corp.company.com:1666 Ez a fájl telepíthető a hibakeresőt futtató számítógépre. A forráskiszolgáló indításakor az értékek Srcsrv.ini; ezek az értékek felülbírálják a PDB-fájlban található információkat. Így a felhasználók úgy konfigurálhatják a hibakeresőt, hogy hibakereséskor alternatív forrásvezérlő kiszolgálót használjanak. További információt a forráskiszolgáló eszközeivel telepített Srcsrv.ini példában talál.
Ssindex.cmd	Ez a szkript létrehozza a forrásvezérlőbe beadott fájlok listáját, valamint az egyes fájlok verzióadatait. Ezen információk egy részét az alkalmazás létrehozásakor létrehozott .pdb fájlokban tárolja. A szkript a következő Perl-modulok egyikét használja a forrásvezérléshez: P4.pm (Perforce) vagy Vss.pm (Visual Source Safe). További információkért futtassa a szkriptet a -? vagy-?? (részletes súgó) lehetőség, vagy vizsgálja meg a szkriptet.
Srctool.exe	Ez a segédprogram felsorolja a .pdb fájlban indexelt összes fájlt. Minden fájl esetében felsorolja a fájl teljes elérési útját, forrásvezérlő kiszolgálóját és verziószámát. Ezekkel az információkkal a forráskiszolgáló használata nélkül is lekérheti a fájlokat. További információkért futtassa a segédprogramot a /? opció.
Pdbstr.exe	Ezt a segédprogramot az indexelő szkriptek használják a verziókövetési információk beszúrására a cél .pdb fájl "srcsrv" alternatív adatfolyamába. A .pdb fájlból bármilyen streamet beolvashat. Ezekkel az információkkal ellenőrizheti, hogy az indexelési szkriptek megfelelően működnek-e. További információkért futtassa a segédprogramot a /? opció.

 

A forrásfájl beolvasása

A DbgHelp API hozzáférést biztosít a forráskiszolgáló funkcióihoz a SymGetSourceFile függvényen keresztül. A lekérendő forrásfájl nevének lekéréséhez hívja meg a SymEnumSourceFiles vagy SymGetLineFromAddr64 függvényt.

Forráskiszolgáló használata hibakeresővel

Ha a forráskiszolgálót WinDbg, KD, NTSD vagy CDB használatával szeretné használni, győződjön meg arról, hogy telepítette a Hibakereső eszközök windowsos csomagjának legújabb verzióját (6.3-es vagy újabb verzió). Ezután a .srcpath parancsba írja be az srv* parancsot az alábbiak szerint:

.srcpath srv*;c:\mysource

Vegye figyelembe, hogy ez a példa egy hagyományos forrásútvonalat is tartalmaz. Ha a hibakereső nem tudja lekérni a fájlt a forráskiszolgálóról, akkor a megadott elérési úton fog keresni.

Ha a forráskiszolgáló lekéri a forrásfájlt, az a hibakeresési munkamenet befejezése után a merevlemezen marad. A forrásfájlok helyileg vannak tárolva a Windows hibakeresési eszközeinek telepítési könyvtárának src alkönyvtárában.

Forráskiszolgálói adatblokkok

A forráskiszolgáló két adatblokkra támaszkodik a PDB-fájlban.

• Forrásfájllista. A modul létrehozása automatikusan létrehozza a modul létrehozásához használt forrásfájlok teljes elérési útjainak listáját.
• Adatblokk. A forrás korábban ismertetett indexelése egy másik streamet ad hozzá az "srcsrv" nevű PDB-fájlhoz. Az adatokat beszúró szkript az adott buildelési folyamattól és a használt forrásvezérlő rendszertől függ.

Az 1. nyelvi specifikációs verzióban az adatblokk három részre oszlik: ini, változók és forrásfájlok. Az alábbi szintaxist tartalmazza.

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

Az összes szöveg szó szerint értelmezve van, kivéve a százalékjelek közé zárt szöveget (%). A százalékjelek közé zárt szöveget a rendszer rekurzív módon feloldandó változónévként kezeli, kivéve, ha az a következő függvények egyike:

%fnvar%()

A paraméter szövegét százalékjelek közé kell tenni, és kiterjesztendő változóként kell kezelni.

%fnbksl%()

A paraméterszövegben szereplő összes perjelet (/) visszafelé fordított perjelekre (\) kell cserélni.

%fnfile%()

A paraméter szövegében lévő összes elérési útinformációt ki kell venni, és csak a fájl nevét kell hagyni.

Az ini szakasz olyan változókat tartalmaz, amelyek a követelményeket írják le. Az indexelő szkript tetszőleges számú változót adhat hozzá ehhez a szakaszhoz. Az alábbiakban példákat láthat:

VERZIÓ

A nyelvi specifikáció verziója. Ez a változó kötelező.

VERCTL

A forrásvezérlő terméket leíró sztring. Ez a változó nem kötelező.

DATETIME

Egy sztring, amely a PDB-fájl feldolgozásának dátumát és időpontját jelzi. Ez a változó nem kötelező.

A változók szakasz olyan változókat tartalmaz, amelyek ismertetik, hogyan lehet kinyerni egy fájlt a forrásvezérlőből. A gyakran használt szöveg változóként való definiálására is használható az adatblokk méretének csökkentése érdekében.

SRCSRVTRG

Ismerteti, hogyan hozhatja létre a kinyert fájl célútvonalát. Ez egy kötelező változó.

SRCSRVCMD

Ismerteti, hogyan hozhatja létre a parancsot a fájl forrásvezérlőből való kinyeréséhez. Ez magában foglalja a végrehajtható fájl nevét és parancssori paramétereit. Ez egy kötelező változó.

SRCSRVENV

A fájlkinyerés során létrehozandó környezeti változókat felsoroló sztring. Több bejegyzés elkülönítése háttérkarakterjellel (\b). Ez egy nem kötelező változó.

A forrásfájlok szakasz minden indexelt forrásfájlhoz tartalmaz bejegyzést. Az egyes sorok tartalmát változóként értelmezzük VAR1, VAR2, VAR3 és így tovább, amíg a VAR10 nem lesz. A változókat csillag választja el egymástól. A VAR1-nek meg kell adnia a forrásfájl teljes elérési útját a PDB-fájl más részein felsoroltak szerint. Például a következő sor:

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

értelmezése a következő:

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

Ebben a példában a VAR4 egy verziószám. A legtöbb forrásvezérlő rendszer azonban támogatja a fájlok címkézését oly módon, hogy az adott build forrásállapota visszaállítható legyen. Ezért alternatív megoldásként használhatja a címkét a buildhez. A mintaadatblokk módosítható úgy, hogy tartalmazzon egy változót, például a következőket:

LABEL=BUILD47

Ezt követően a forrásvezérlő rendszer feltételezve az at (@) jellel jelzi a címkét, az SRCSRVCMD változót az alábbiak szerint módosíthatja:

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

A forráskiszolgáló működése

A forráskiszolgáló-ügyfél a Symsrv.dll. Az ügyfél nem nyer ki adatokat közvetlenül a PDB-fájlból; olyan szimbólumkezelőt használ, mint a Dbghelp.dll. Ez lényegében egy rekurzív változóhelyettesítő motor, amely létrehoz egy parancssort, amellyel kinyerhető a megfelelő forrásfájl a forrásvezérlő rendszerből. A kód nem hívhatja meg közvetlenül Symsrv.dll. A funkció alkalmazásba való integrálásához használja a SymGetSourceFile függvényt.

A forráskiszolgáló első verziója a következőképpen működik. Ez a viselkedés a jövőbeli verziókban változhat.

• Az ügyfél meghívja a SrcSrvInit függvényt a célútvonallal, amelyet az összes forrásfájl-kinyerés alapjaként kell használni. Ezt az elérési utat a TARG változóban tárolja.
• Az ügyfél kinyeri az Srcsrv-adatfolyamot a PDB-ből a modul PDB betöltésekor, és meghívja a SrcSrvLoadModule függvényt, hogy átadja az adatblokkot a forráskiszolgálónak.
• Amikor a Dbghelp lekéri a forrásfájlt, az ügyfél meghívja a SrcSrvGetFile függvényt a forrásfájlok forrásvezérlőből való lekéréséhez.
• A forráskiszolgáló az adatblokk forrásfájl-bejegyzéseiben keres egy olyan bejegyzést, amely megfelel a kért fájlnak. Kitölti a VAR1-et a VARn a forrásfájl-bejegyzés tartalmával. Ezután kibontja az SRCSRVTRG változót VAR1 használatával a VARn. Ha a fájl már ezen a helyen van, visszaadja a helyet a hívónak. Ellenkező esetben kibontja az SRCSRVCMD változót a fájl forrásvezérlőből való lekéréséhez és a célhelyre másolásához szükséges parancs létrehozásához. Végül végrehajtja ezt a parancsot.

Forrásvezérlő-szolgáltatói modul létrehozása

A forráskiszolgáló tartalmazza a Perforce (p4.pm) és a Visual Source Safe (vss.pm) szolgáltatói moduljait. Saját szolgáltatói modul létrehozásához a következő interfészkészletet kell implementálnia.

$module::SimpleUsage()

Cél: Egyszerű modulhasználati információkat jelenít meg az STDOUT-nak.

Paraméterek: Nincs

Visszatérési érték: Nincs

$module::VerboseUsage()

Cél: Részletes modulhasználati információkat jelenít meg az STDOUT-nak.

Paraméterek: Nincs

Visszatérési érték: Nincs

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

Cél: Inicializálja a szolgáltatói modul egy példányát.

Paraméterek: Minden olyan @ARGV argumentum, amelyet a SSIndex.cmd nem ismert fel általános argumentumként.

Visszatérési érték: A későbbi műveletekben használható hivatkozás.

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

Cél: Lehetővé teszi a modul számára, hogy összegyűjtse a szükséges forrásindexelési információkat a $SourcePath paraméter által megadott könyvtárhoz. A modul nem feltételezheti, hogy ez a bejegyzés csak egyszer lesz meghívva minden objektumpéldányhoz, mivel SSIndex.cmd többször is meghívhatja a különböző elérési utakhoz.

Paraméterek: (1) Az indexelendő forrást tartalmazó helyi könyvtár. (2) Hivatkozás a megadott Srcsrv.ini fájl összes bejegyzését tartalmazó kivonatra.

Visszatérési érték: Nincs

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

Cél: A forrásvezérlő rendszer egyetlen, adott fájljának kinyeréséhez szükséges információkat tartalmazza.

Paraméterek: Teljes fájlnév

Visszatérési érték: (1) A visszaadott $FileEntry értelmezéséhez szükséges változók kivonathivatkozása. SSIndex.cmd gyorsítótárazza ezeket a változókat minden olyan forrásfájlhoz, amelyet egyetlen hibakeresési fájl használ a forrásindex-adatfolyamba írt információk mennyiségének csökkentése érdekében. (2) A forrásindexfolyamba írandó fájlbejegyzés, amely lehetővé teszi, hogy SrcSrv.dll kinyerje ezt a fájlt a forrásvezérlőből. A sor pontos formátuma a forrásvezérlő rendszerre jellemző.

$TextString = $objref->LongName()

Cél: Leíró sztringet biztosít a forrásvezérlő szolgáltatójának a végfelhasználó számára történő azonosításához.

Paraméterek: Nincs

Visszatérési érték: A forrásvezérlő rendszer leíró neve.

@StreamVariableLines = $objref–>SourceStreamVariables()

Cél: Lehetővé teszi a forrásvezérlő szolgáltató számára, hogy forrásvezérlő-specifikus változókat adjon hozzá a forrásstreamhez minden hibakeresési fájlhoz. A mintamodulok ezt a módszert használják a szükséges EXTRACT_CMD és EXTRACT_TARGET változók írásához.

Paraméterek: Nincs

Visszatérési érték: A forrásfolyam változóinak bejegyzéseinek listája.