Especificação da 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 o 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 forma. (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 arquivos de origem. Esse caminho é armazenado na variável especial TARG.

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

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

O SrcSrv analisa todas as entradas do arquivo de origem no bloco de dados em busca de uma entrada que corresponda exatamente à especificação de origem solicitada. Esta correspondência encontra-se em VAR1.

Depois que o SrcSrv encontra 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. Assumimos que o caminho de origem ainda é:

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

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.

SrcSrv agora olha para ver se o arquivo já está lá. Se estiver, o SrcSrv devolve a localização ao chamador. Caso contrário, o SrcSrv cria o comando execution 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 negritadas.

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 procurá-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 consecutivos são interpretados como um único sinal de porcentagem.

Blocos de dados do servidor de origem

O SrcSrv depende de dois blocos de dados dentro do arquivo .pdb, a lista de arquivos de origem e o bloco de dados.

A lista de arquivos de origem é criada automaticamente quando um módulo é construído. Esta lista contém caminhos totalmente qualificados para os arquivos de origem usados para construir 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 compilação 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 seguinte sintaxe.

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 o texto incluído em sinais de porcentagem (%). O texto incluído em 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 incluído em sinais de porcentagem e tratado como uma variável a ser resolvida.

%fnbksl%()
Todas as barras para a frente (/) no texto do parâmetro devem ser substituídas por barras para trás ().

%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. Seguem-se alguns exemplos:

VERSÃO
A versão de especificação de idioma. Esta variável é necessária. Se você desenvolver um script com base na especificação de linguagem 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 seu. 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. Esta variável é opcional.

DATETIME
Uma cadeia de caracteres que indica a data e a hora em que o arquivo .pdb foi processado. Esta 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. Ele também pode ser usado 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. Esta é uma variável necessá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 é necessário se qualquer comando de extração deve ser executado.

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

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

SRCSRVVERRDESC
Especifica o texto a ser exibido quando o cliente de controle de versão não conseguir entrar em contato com o servidor que contém os arquivos de origem a serem extraídos. O SrcSrv usa esse valor para verificar se há problemas de conexão. Esta é 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 , onde X é o número da variável que está sendo indicada. Esta é 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 do seguinte modo:

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 de origem suporta a rotulagem de arquivos de tal forma que o estado de origem de uma determinada compilação pode ser restaurado. Portanto, pode utilizar a etiqueta para a compilação. O bloco de dados de exemplo pode ser modificado para conter uma variável como a seguinte:

LABEL=BUILD47 

Em seguida, supondo que o sistema de controle do código-fonte use o sinal de 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%

Manipulando erros do servidor

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

Sempre que o SrcSrv não consegue extrair um arquivo, ele examina o texto de saída produzido pelo comando. Se qualquer parte deste 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. Aqui está um exemplo:

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

A identidade do servidor é adquirida do SRCSRVERRVAR. Portanto, se o SRCSRVERRVAR contiver "var2" e a entrada do arquivo no arquivo .pdb tiver esta aparência:

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

Todas as tentativas futuras de obter o código-fonte usando uma entrada de arquivo que contenha "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.