Server di origine

Il server di origine consente a un client di recuperare la versione esatta dei file di origine usati per compilare un'applicazione. Poiché il codice sorgente per un modulo può cambiare tra le versioni e nel corso di anni, è importante esaminare il codice sorgente come esisteva quando è stata compilata la versione del modulo in questione.

Il server di origine recupera i file appropriati dal controllo del codice sorgente. Per usare il server di origine, l'applicazione deve essere stata indicizzata come origine.

Indicizzazione di origine

Il sistema di indicizzazione di origine è una raccolta di file eseguibili e script Perl. Gli script Perl richiedono Perl 5.6 o versione successiva.

In genere, i file binari vengono indicizzati durante il processo di compilazione dopo la compilazione dell'applicazione. Le informazioni necessarie per il server di origine vengono archiviate nei file PDB.

Il server di origine viene attualmente fornito con script che devono funzionare con i sistemi di controllo del codice sorgente seguenti.

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

È anche possibile creare uno script personalizzato per indicizzare il codice per un sistema di controllo del codice sorgente diverso.

Nella tabella seguente sono elencati gli strumenti del server di origine.

Strumento	Descrizione
Srcsrv.ini	Questo file è l'elenco master di tutti i server di controllo del codice sorgente. Ogni voce ha il formato seguente:MY edizione Standard RVER=serverinfo Quando si usa Perforce, le informazioni sul server sono costituite dal percorso di rete completo del server, seguito da due punti, seguito dal numero di porta usato. Ad esempio: MY edizione StandardRVER=machine.corp.company.com:1666 Questo file può essere installato nel computer che esegue il debugger. All'avvio del server di origine, esamina Srcsrv.ini i valori; questi valori sostituiranno le informazioni contenute nel file PDB. In questo modo gli utenti possono configurare un debugger per l'uso di un server di controllo del codice sorgente alternativo in fase di debug. Per altre informazioni, vedere l'esempio Srcsrv.ini installato con gli strumenti del server di origine.
Ssindex.cmd	Questo script compila l'elenco dei file controllati nel controllo del codice sorgente insieme alle informazioni sulla versione di ogni file. Archivia un subset di queste informazioni nei file con estensione pdb generati durante la compilazione dell'applicazione. Lo script usa uno dei moduli Perl seguenti per interfacciarsi con il controllo del codice sorgente: P4.pm (Perforce) o Vss.pm (Visual Source Cassaforte). Per altre informazioni, eseguire lo script con -? O-?? (guida dettagliata) o esaminare lo script.
Srctool.exe	Questa utilità elenca tutti i file indicizzati all'interno di un file con estensione pdb. Per ogni file, elenca il percorso completo, il server di controllo del codice sorgente e il numero di versione del file. È possibile usare queste informazioni per recuperare i file senza usare il server di origine. Per altre informazioni, eseguire l'utilità con /? .
Pdbstr.exe	Questa utilità viene usata dagli script di indicizzazione per inserire le informazioni sul controllo della versione nel flusso alternativo "srcsrv" del file con estensione pdb di destinazione. Può anche leggere qualsiasi flusso da un file con estensione pdb. È possibile usare queste informazioni per verificare che gli script di indicizzazione funzionino correttamente. Per altre informazioni, eseguire l'utilità con /? .

 

Recupero del file di origine

L'API DbgHelp consente di accedere alle funzionalità del server di origine tramite la funzione SymGetSourceFile. Per recuperare il nome del file di origine da recuperare, chiamare la funzione SymEnumSourceFiles o SymGetLineFromAddr64.

Uso del server di origine con un debugger

Per usare il server di origine con WinDbg, KD, NTSD o CDB, assicurarsi di aver installato una versione recente del pacchetto Strumenti di debug per Windows (versione 6.3 o successiva). Includere quindi srv* nel comando .srcpath come indicato di seguito:

.srcpath srv*;c:\mysource

Si noti che questo esempio include anche un percorso di origine tradizionale. Se il debugger non riesce a recuperare il file dal server di origine, cercherà il percorso specificato.

Se un file di origine viene recuperato dal server di origine, rimarrà sul disco rigido dopo che la sessione di debug è finita. I file di origine vengono archiviati localmente nella sottodirectory src della directory di installazione degli strumenti di debug per Windows.

Blocchi di dati del server di origine

Il server di origine si basa su due blocchi di dati all'interno del file PDB.

• Elenco di file di origine. La compilazione di un modulo crea automaticamente un elenco di percorsi completi per i file di origine usati per compilare il modulo.
• Blocco di dati. L'indicizzazione dell'origine come descritto in precedenza aggiunge un flusso alternativo al file PDB denominato "srcsrv". Lo script che inserisce questi dati dipende dal processo di compilazione specifico e dal sistema di controllo del codice sorgente in uso.

Nella specifica del linguaggio versione 1, il blocco di dati è suddiviso in tre sezioni: ini, variabili e file di origine. Ha la sintassi seguente.

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

Tutto il testo viene interpretato letteralmente, ad eccezione del testo racchiuso tra segni di percentuale (%). Il testo racchiuso nei segni di percentuale viene considerato come un nome di variabile da risolvere in modo ricorsivo, a meno che non sia una delle funzioni seguenti:

%fnvar%()

Il testo del parametro deve essere racchiuso tra segni di percentuale e considerato come variabile da espandere.

%fnbksl%()

Tutte le barre (/) nel testo del parametro devono essere sostituite con barre indietro (\).

%fnfile%()

Tutte le informazioni sul percorso nel testo del parametro devono essere rimosse, lasciando solo il nome del file.

La sezione ini contiene variabili che descrivono i requisiti. Lo script di indicizzazione può aggiungere un numero qualsiasi di variabili a questa sezione. Di seguito sono riportati alcuni esempi:

VERSIONE

Versione della specifica del linguaggio. Questa variabile è obbligatoria.

VERCTL

Stringa che descrive il prodotto del controllo del codice sorgente. Questa variabile è facoltativa.

DATETIME

Stringa che indica la data e l'ora di elaborazione del file PDB. Questa variabile è facoltativa.

La sezione variables contiene variabili che descrivono come estrarre un file dal controllo del codice sorgente. Può anche essere usato per definire il testo comunemente usato come variabili per ridurre le dimensioni del blocco di dati.

SRCSRVTRG

Viene descritto come compilare il percorso di destinazione per il file estratto. Si tratta di una variabile obbligatoria.

SRCSRVCMD

Viene descritto come compilare il comando per estrarre il file dal controllo del codice sorgente. Sono inclusi il nome del file eseguibile e i relativi parametri della riga di comando. Si tratta di una variabile obbligatoria.

SRCSRVENV

Stringa che elenca le variabili di ambiente da creare durante l'estrazione di file. Separare più voci con un carattere backspace (\b). Si tratta di una variabile facoltativa.

La sezione file di origine contiene una voce per ogni file di origine indicizzato. Il contenuto di ogni riga viene interpretato come variabili con i nomi VAR1, VAR2, VAR3 e così via fino a VAR10. Le variabili sono separate da asterischi. VAR1 deve specificare il percorso completo del file di origine come elencato altrove nel file PDB. Ad esempio, la riga seguente:

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

viene interpretato come segue:

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

In questo esempio VAR4 è un numero di versione. Tuttavia, la maggior parte dei sistemi di controllo del codice sorgente supporta l'etichettatura dei file in modo che lo stato di origine per una determinata compilazione possa essere ripristinato. Pertanto, è possibile usare in alternativa l'etichetta per la compilazione. È possibile modificare il blocco di dati di esempio per contenere una variabile, ad esempio:

LABEL=BUILD47

Quindi, presupponendo che il sistema di controllo del codice sorgente usi il simbolo (@) per indicare un'etichetta, è possibile modificare la variabile SRCSRVCMD come indicato di seguito:

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

Funzionamento del server di origine

Il client del server di origine viene implementato in Symsrv.dll. Il client non estrae informazioni direttamente dal file PDB; usa un gestore di simboli, ad esempio quello implementato in Dbghelp.dll. Si tratta essenzialmente di un motore di sostituzione di variabili ricorsive che crea una riga di comando che può essere usata per estrarre il file di origine appropriato dal sistema di controllo del codice sorgente. Il codice non deve chiamare direttamente Symsrv.dll. Per integrarne le funzionalità nell'applicazione, usare la funzione SymGetSourceFile.

La prima versione del server di origine funziona come indicato di seguito. Questo comportamento può cambiare nelle versioni future.

• Il client chiama la funzione SrcSrvInit con il percorso di destinazione da usare come base per tutte le estrazioni di file di origine. Archivia questo percorso nella variabile TARG.
• Il client estrae il flusso Srcsrv dal PDB quando il modulo PDB viene caricato e chiama la funzione SrcSrvLoadModule per passare il blocco di dati al server di origine.
• Quando Dbghelp recupera un file di origine, il client chiama la funzione SrcSrvGetFile per recuperare i file di origine dal controllo del codice sorgente.
• Il server di origine cerca nelle voci del file di origine nel blocco di dati una voce corrispondente al file richiesto. Riempie VAR1 a VARn con il contenuto della voce del file di origine. Espande quindi la variabile SRCSRVTRG usando VAR1 a VARn. Se il file è già presente in questo percorso, restituisce il percorso al chiamante. In caso contrario, espande la variabile SRCSRVCMD per compilare il comando necessario per recuperare il file dal controllo del codice sorgente e copiarlo nel percorso di destinazione. Infine, esegue questo comando.

Creazione di un modulo provider di controllo del codice sorgente

Il server di origine include moduli provider per Perforce (p4.pm) e visual source Cassaforte (vss.pm). Per creare un modulo provider personalizzato, è necessario implementare il set di interfacce seguente.

$module::SimpleUsage()

Scopo: visualizza informazioni sull'utilizzo di moduli semplici per STDOUT.

Parametri: nessuno

Valore restituito: Nessuno

$module::VerboseUsage()

Scopo: visualizza informazioni dettagliate sull'utilizzo dei moduli in STDOUT.

Parametri: nessuno

Valore restituito: Nessuno

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

Scopo: inizializza un'istanza del modulo del provider.

Parametri: tutti gli @ARGV argomenti non riconosciuti da SSIndex.cmd come argomenti generali.

Valore restituito: riferimento che può essere usato nelle operazioni successive.

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

Scopo: consente al modulo di raccogliere le informazioni di indicizzazione di origine necessarie per la directory specificata dal parametro $SourcePath. Il modulo non deve presupporre che questa voce venga chiamata una sola volta per ogni istanza dell'oggetto, perché SSIndex.cmd può chiamarla più volte per percorsi diversi.

Parametri: (1) Directory locale contenente l'origine da indicizzare. (2) Riferimento a un hash contenente tutte le voci del file di Srcsrv.ini specificato.

Valore restituito: Nessuno

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

Scopo: fornisce le informazioni necessarie per estrarre un singolo file specifico dal sistema di controllo del codice sorgente.

Parametri: un nome di file completo

Valore restituito: (1) Riferimento hash delle variabili necessarie per interpretare il $FileEntry restituito. SSIndex.cmd memorizza nella cache queste variabili per ogni file di origine usato da un singolo file di debug per ridurre la quantità di informazioni scritte nel flusso di indice di origine. (2) Voce di file da scrivere nel flusso dell'indice di origine per consentire SrcSrv.dll di estrarre il file dal controllo del codice sorgente. Il formato esatto di questa riga è specifico del sistema di controllo del codice sorgente.

$TextString = $objref-LongName>()

Scopo: fornisce una stringa descrittiva per identificare il provider del controllo del codice sorgente all'utente finale.

Parametri: nessuno

Valore restituito: nome descrittivo del sistema di controllo del codice sorgente.

@StreamVariableLines = $objref-SourceStreamVariables>()

Scopo: consente al provider di controllo del codice sorgente di aggiungere variabili specifiche del controllo del codice sorgente al flusso di origine per ogni file di debug. I moduli di esempio usano questo metodo per scrivere le variabili di EXTRACT_CMD e EXTRACT_TARGET necessarie.

Parametri: nessuno

Valore restituito: elenco di voci per le variabili del flusso di origine.