Especificação de Linguagem 1

Observação

Este tópico descreve a operação interna do SrcSrv. Para obter informações gerais sobre como os caminhos de origem funcionam, consulte Caminho de origem. Para obter informações sobre como usar o SrcSrv, consulte Usando SrcSrv. Para determinar a operação atual do carregamento de origem em seu ambiente, habilite o carregamento de origem barulhento conforme descrito em .srcnoisy (Carregamento de origem barulhento)

A primeira versão do SrcSrv funciona da seguinte maneira. (Esse comportamento pode mudar em versões futuras.)

Primeiro, o cliente chama SrcSrvInit com o caminho de destino a ser usado como base para todas as extrações de arquivo de origem. Esse caminho é armazenado na variável especial TARG.

Quando DbgHelp carrega o arquivo .pdb de um módulo, ele extrai o fluxo SrcSrv do arquivo .pdb e passa esse bloco de dados para SrcSrv chamando SrcSrvLoadModule.

Em seguida, quando DbgHelp precisa obter um arquivo de origem, ele chama SrcSrvGetFile para recuperar um arquivo de origem especificado do controle de versão.

O SrcSrv examina todas as entradas de arquivo de origem no bloco de dados para uma entrada que corresponde exatamente à especificação de origem solicitada. Essa correspondência é encontrada em VAR1.

Depois que o SrcSrv localiza a entrada, ele preenche as variáveis especiais (VAR1, VAR2 etc.) com o conteúdo dessa entrada de arquivo de origem. Em seguida, a variável SRCSRVTRG é resolvida usando essas variáveis especiais.

A seguir, mostra como a variável SRCSRVTRG é resolvida usando as variáveis especiais. Presumimos que o caminho de origem ainda seja:

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

Cada linha mostra a resolução de mais uma variável especial. As variáveis resolvidas são em negrito.

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

Observe como esse caminho de destino gerado é exclusivo e não permite que duas versões do mesmo arquivo sejam extraídas para o mesmo local.

O SrcSrv agora procura ver se o arquivo já está lá. Se for, o SrcSrv retornará o local para o chamador. Caso contrário, o SrcSrv compila o comando de execução para extrair o arquivo resolvendo SRCSRVCMD.

No exemplo a seguir, cada linha mostra a resolução de mais uma variável especial. As variáveis resolvidas são em negrito.

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 

Agora, o SrcSrv executa esse comando. Se o resultado desse comando for um arquivo no local esperado, esse caminho será retornado ao chamador.

Observe que, se uma variável não puder ser resolvida, será feita uma tentativa de pesquisá-la como uma variável de ambiente do sistema operacional. Se isso falhar, o nome da variável será excluído do texto que está sendo processado.

Dois caracteres de sinal de porcentagem consecutiva são interpretados como um único sinal de porcentagem.

Blocos de dados do servidor de origem

O SrcSrv depende de dois blocos de dados no arquivo .pdb, na lista de arquivos de origem e no bloco de dados.

A lista de arquivos de origem é criada automaticamente quando um módulo é criado. Esta lista contém caminhos totalmente qualificados para os arquivos de origem usados para compilar o módulo.

O bloco de dados é criado durante a indexação de origem. Neste momento, um fluxo alternativo chamado "srcsrv" é adicionado ao arquivo .pdb. O script que insere esses dados depende do processo de build específico e do sistema de controle do código-fonte em uso.

O bloco de dados é dividido em três seções: ini, variáveis e arquivos de origem. O bloco de dados tem a sintaxe a seguir.

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

Todo o texto é interpretado literalmente, exceto pelo texto entre sinais de porcentagem (%). O texto entre sinais de porcentagem é tratado como um nome de variável a ser resolvido recursivamente, a menos que seja uma das seguintes funções:

%fnvar%()
O texto do parâmetro deve ser colocado entre sinais de porcentagem e tratado como uma variável a ser resolvida.

%fnbksl%()
Todas as barras (/) no texto do parâmetro devem ser substituídas por barras anteriores ().

%fnfile%()
Todas as informações de caminho no texto do parâmetro devem ser removidas, deixando apenas o nome do arquivo.

A seção [ini] do bloco de dados contém variáveis que descrevem os requisitos. O script de indexação pode adicionar qualquer número de variáveis a esta seção. Os exemplos são os seguintes:

VERSÃO
A versão da especificação de idioma. Esta variável é obrigatória. Se você desenvolver um script com base na especificação de idioma atual, defina esse valor como 1. O código do cliente SrcSrv não tenta executar nenhum script que tenha um valor maior que o próprio. As versões atuais do SrcSrv usam um valor de 2.

VERCTRL
Uma cadeia de caracteres que descreve o sistema de controle de versão de origem. Essa variável é opcional.

DATETIME
Uma cadeia de caracteres que indica a data e a hora em que o arquivo .pdb foi processado. Essa variável é opcional.

A seção [variáveis] do bloco de dados contém variáveis que descrevem como extrair um arquivo do controle do código-fonte. Ela também pode ser usada para definir texto comumente usado como variáveis para reduzir o tamanho do bloco de dados.

SRCSRVTRG
Descreve como criar o caminho de destino para o arquivo extraído. Essa é uma variável obrigatória.

SRCSRVCMD
Descreve como criar o comando para extrair o arquivo do controle do código-fonte. Isso inclui o nome do arquivo executável e seus parâmetros de linha de comando. Isso será necessário se qualquer comando de extração precisar ser executado.

SRCSRVENV
Lista as variáveis de ambiente a serem criadas durante a extração de arquivos. Essa é uma cadeia de caracteres. Separe várias entradas com um caractere de backspace (\b). Essa é uma variável opcional.

SRCSRVVERCTRL
Especifica o sistema de controle de versão em uso. Para o Perforce, isso é perforce. Para o Team Foundation Server, isso é tfs. Essa variável é usada para persistir erros de servidor. Essa é uma variável opcional.

SRCSRVVERRDESC
Especifica o texto a ser exibido quando o cliente de controle de versão não consegue contatar o servidor que contém os arquivos de origem a serem extraídos. O SrcSrv usa esse valor para marcar para problemas de conexão. Essa é uma variável opcional.

SRCSRVERRVAR
Indica qual variável em uma entrada de arquivo corresponde a um servidor de controle de versão. Ele é usado pelo SrcSrv para identificar comandos que não funcionam, com base em falhas anteriores. O formato do texto é varX , em que X é o número da variável que está sendo indicada. Essa é uma variável opcional.

A seção [arquivos de origem] do bloco de dados contém uma entrada para cada arquivo de origem que foi indexado. O conteúdo de cada linha é interpretado como variáveis com os nomes VAR1, VAR2, VAR3 e assim por diante até VAR10. As variáveis são separadas por asteriscos. VAR1 deve especificar o caminho totalmente qualificado para o arquivo de origem, conforme listado em outro lugar no arquivo .pdb. Por exemplo:

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

é interpretada da seguinte maneira:

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

Neste exemplo, VAR4 é um número de revisão. No entanto, a maioria dos sistemas de controle do código-fonte dá suporte à rotulagem de arquivos de forma que o estado de origem de um determinado build possa ser restaurado. Portanto, você pode usar o rótulo para o build. O bloco de dados de exemplo pode ser modificado para conter uma variável como a seguinte:

LABEL=BUILD47 

Em seguida, presumindo que o sistema de controle do código-fonte use a arroba (@) para indicar um rótulo, você pode modificar a variável SRCSRVCMD da seguinte maneira:

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

Tratamento de erros do servidor

Às vezes, um cliente não consegue extrair nenhum arquivo de um único servidor de controle de versão. Isso pode ocorrer porque o servidor está inativo e fora da rede ou porque o usuário não tem privilégios apropriados para acessar a origem. No entanto, a tentativa demorada de obter essa fonte pode retardar significativamente as coisas. Nessa situação, é melhor desabilitar qualquer tentativa de extração de uma fonte que tenha sido comprovadamente indisponível.

Sempre que o SrcSrv falha ao extrair um arquivo, ele examina o texto de saída produzido pelo comando . Se qualquer parte desse comando contiver uma correspondência exata para o conteúdo do SRCSRVERRDESC, todos os comandos futuros para o mesmo servidor de controle de versão serão ignorados. Observe que você pode definir várias cadeias de caracteres de erro adicionando números ou texto arbitrário ao final do nome da variável SRCSRVERRDESC. Veja um exemplo:

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

A identidade do servidor é adquirida de SRCSRVERRVAR. Portanto, se SRCSRVERRVAR contiver "var2" e a entrada de arquivo no arquivo .pdb for semelhante a esta:

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

todas as tentativas futuras de obter a origem usando uma entrada de arquivo que contém "TOOLS_PRJ" na variável 2 são ignoradas.

Você também pode adicionar indicadores de erro no cliente do depurador editando Srcsrv.ini. Consulte a versão de exemplo incluída do srcsrv.ini para obter detalhes.