Specifica del linguaggio 1
Nota
Questo argomento descrive l'operazione interna di SrcSrv. Per informazioni generali sul funzionamento dei percorsi di origine, vedere Percorso di origine. Per informazioni sull'uso di SrcSrv, vedere Uso di SrcSrv. Per determinare l'operazione corrente del caricamento dell'origine nell'ambiente, abilitare il caricamento di origine rumoroso come descritto in .srcnoisy (Caricamento di origine rumorosa)
La prima versione di SrcSrv funziona come indicato di seguito. Questo comportamento può cambiare nelle versioni future.
Prima di tutto, il client chiama SrcSrvInit con il percorso di destinazione da usare come base per tutte le estrazione di file di origine. Questo percorso viene archiviato nella variabile speciale TARG.
Quando DbgHelp carica il file pdb di un modulo, estrae il flusso SrcSrv dal file pdb e passa questo blocco di dati a SrcSrv chiamando SrcSrvLoadModule.
Quando DbgHelp deve ottenere un file di origine, quindi chiama SrcSrvGetFile per recuperare un file di origine specificato dal controllo della versione.
SrcSrv esamina tutte le voci di file di origine nel blocco dati per una voce corrispondente esattamente alla specifica di origine richiesta. Questa corrispondenza viene trovata in VAR1.
Dopo che SrcSrv trova la voce, compila le variabili speciali (VAR1, VAR2 e così via) con il contenuto di questa voce di file di origine. La variabile SRCSRVTRG viene quindi risolta usando queste variabili speciali.
Di seguito viene illustrato come viene risolta la variabile SRCSRVTRG usando le variabili speciali. Si presuppone che il percorso di origine sia ancora:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
Ogni riga mostra la risoluzione di una variabile più speciale. Le variabili risolte sono grassetto.
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
Si noti come questo percorso di destinazione generato è univoco e non consente l'estrazione di due versioni dello stesso file nella stessa posizione.
SrcSrv ora cerca se il file è già presente. In caso contrario, SrcSrv restituisce la posizione al chiamante. In caso contrario, SrcSrv compila il comando di esecuzione per estrarre il file risolvendo SRCSRVCMD.
Nell'esempio seguente ogni riga mostra la risoluzione di una variabile speciale. Le variabili risolte sono grassetto.
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
Ora SrcSrv esegue questo comando. Se il risultato di questo comando è un file nel percorso previsto, questo percorso viene restituito al chiamante.
Si noti che se una variabile non può essere risolta, viene eseguito un tentativo di cercarlo come variabile di ambiente del sistema operativo. In caso contrario, il nome della variabile viene eliminato dal testo elaborato.
Due caratteri di segno consecutivi vengono interpretati come un singolo segno percentuale.
Blocchi di dati del server di origine
SrcSrv si basa su due blocchi di dati all'interno del file con estensione pdb, l'elenco di file di origine e il blocco di dati.
L'elenco di file di origine viene creato automaticamente quando viene compilato un modulo. Questo elenco contiene percorsi completi per i file di origine usati per compilare il modulo.
Il blocco di dati viene creato durante l'indicizzazione di origine. A questo punto, viene aggiunto un flusso alternativo denominato "srcsrv" al file con estensione pdb. Lo script che inserisce questi dati dipende dal processo di compilazione e dal sistema di controllo del codice sorgente specifico in uso.
Il blocco di dati è suddiviso in tre sezioni: ini, variabili e file di origine. Il blocco di dati 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 nei segni di percentuale (%). Il testo racchiuso nei segni di percentuale viene considerato come 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 risolvere.
%fnbksl%()
Tutte le barre in avanti (/) 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] del blocco dati contiene variabili che descrivono i requisiti. Lo script di indicizzazione può aggiungere qualsiasi numero di variabili a questa sezione. Alcuni esempi:
VERSIONE
Versione della specifica del linguaggio. Questa variabile è obbligatoria. Se si sviluppa uno script in base alla specifica del linguaggio corrente, impostare questo valore su 1. Il codice client SrcSrv non tenta di eseguire uno script con valore maggiore del proprio. Le versioni correnti di SrcSrv usano un valore pari a 2.
VERCTRL
Stringa che descrive il sistema di controllo della versione del codice sorgente. Questa variabile è facoltativa.
DATETIME
Stringa che indica la data e l'ora in cui è stato elaborato il file con estensione pdb. Questa variabile è facoltativa.
La sezione [variabili] del blocco dati contiene variabili che descrivono come estrarre un file dal controllo del codice sorgente. Può essere usato anche 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
Descrive come compilare il comando per estrarre il file dal controllo del codice sorgente. Include il nome del file eseguibile e i relativi parametri della riga di comando. Questa operazione è necessaria se è necessario eseguire qualsiasi comando di estrazione.
SRCSRVENV
Elenca le variabili di ambiente da creare durante l'estrazione di file. Si tratta di una stringa. Separare più voci con un carattere backspace (\b). Si tratta di una variabile facoltativa.
SRCSRVVERCTRL
Specifica il sistema di controllo della versione in uso. Per Perforce, questa è perforce. Per Team Foundation Server, si tratta di tfs. Questa variabile viene usata per rendere persistenti gli errori del server. Si tratta di una variabile facoltativa.
SRCSRVVERRDESC
Specifica il testo da visualizzare quando il client di controllo della versione non è in grado di contattare il server che contiene i file di origine da estrarre. SrcSrv usa questo valore per verificare la presenza di problemi di connessione. Si tratta di una variabile facoltativa.
SRCSRVERRVAR
Indica quale variabile in una voce di file corrisponde a un server di controllo della versione. Viene usato da SrcSrv per identificare i comandi che non funzionano, in base agli errori precedenti. Il formato del testo è varX dove X è il numero della variabile indicata. Si tratta di una variabile facoltativa.
La sezione [file di origine] del blocco dati 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:
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 revisione. Tuttavia, la maggior parte dei sistemi di controllo del codice sorgente supporta i file di etichettatura in modo che lo stato di origine per una determinata compilazione possa essere ripristinato. È quindi possibile usare l'etichetta per la compilazione. Il blocco di dati di esempio può essere modificato per contenere una variabile, ad esempio quanto segue:
LABEL=BUILD47
Quindi, presupponendo che il sistema di controllo del codice sorgente usi il segno (@) per indicare un'etichetta, è possibile modificare la variabile SRCSRVCMD come indicato di seguito:
sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%
Gestione degli errori del server
A volte un client non è in grado di estrarre tutti i file da un singolo server di controllo della versione. Ciò può essere dovuto al fatto che il server è inattivo e fuori rete o perché l'utente non dispone di privilegi appropriati per accedere all'origine. Tuttavia, il tempo utilizzato per ottenere questa origine può rallentare significativamente le cose. In questa situazione, è consigliabile disabilitare qualsiasi tentativo di estrazione da un'origine che è stata provata a non essere disponibile.
Ogni volta che SrcSrv non riesce a estrarre un file, esamina il testo di output prodotto dal comando. Se una parte di questo comando contiene una corrispondenza esatta per il contenuto di SRCSRVERRDESC, tutti i comandi futuri dello stesso server di controllo della versione vengono ignorati. Si noti che è possibile definire più stringhe di errore aggiungendo numeri o testo arbitrario alla fine del nome della variabile SRCSRVERRDESC. Esempio:
SRCSRVERRDESC=lime: server not found
SRCSRVERRDESC_2=pineapple: network error
L'identità del server viene acquisita da SRCSRVERRVAR. Quindi, se SRCSRVERRVAR contiene "var2" e la voce del file nel file pdb ha un aspetto simile al seguente:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
tutti i tentativi futuri di ottenere l'origine usando una voce di file contenente "TOOLS_PRJ" nella variabile 2 vengono ignorati.
È anche possibile aggiungere indicatori di errore nel client del debugger modificando Srcsrv.ini. Per informazioni dettagliate, vedere la versione di esempio inclusa di srcsrv.ini.