Servidor de Origem

O servidor de origem permite que um cliente recupere a versão exata dos arquivos de origem que foram usados para criar um aplicativo. Como o código-fonte de um módulo pode mudar entre versões e ao longo de anos, é importante olhar para o código-fonte como ele existia quando a versão do módulo em questão foi construída.

O servidor de origem recupera os arquivos apropriados do controle do código-fonte. Para usar o servidor de origem, o aplicativo deve ter sido indexado na origem.

Indexação de código-fonte

O sistema de indexação de origem é uma coleção de arquivos executáveis e scripts Perl. Os scripts Perl requerem Perl 5.6 ou superior.

Geralmente, os binários são indexados durante o processo de compilação após a criação do aplicativo. As informações necessárias pelo servidor de origem são armazenadas nos arquivos PDB.

O servidor de origem atualmente é fornecido com scripts que devem funcionar com os seguintes sistemas de controle de origem.

• O Team Foundation Server
• Forçosamente
• Visual SourceSafe
• CVS
• Subversion

Você também pode criar um script personalizado para indexar seu código para um sistema de controle de origem diferente.

A tabela a seguir lista as ferramentas do servidor de origem.

Recuperando o arquivo de origem

A API DbgHelp fornece acesso à funcionalidade do servidor de origem por meio da função SymGetSourceFile. Para recuperar o nome do arquivo de origem a ser recuperado, chame a função SymEnumSourceFiles ou SymGetLineFromAddr64.

Usando o servidor de origem com um depurador

Para usar o servidor de origem com WinDbg, KD, NTSD ou CDB, verifique se você instalou uma versão recente do pacote Ferramentas de Depuração para Windows (versão 6.3 ou posterior). Em seguida, inclua srv* no comando .srcpath da seguinte maneira:

.srcpath srv*;c:\meufonte

Observe que este exemplo também inclui um caminho de origem tradicional. Se o depurador não puder recuperar o arquivo do servidor de origem, ele pesquisará o caminho especificado.

Se um arquivo de origem for recuperado pelo servidor de origem, ele permanecerá no disco rígido após o término da sessão de depuração. Os arquivos de origem são armazenados localmente no subdiretório src do diretório de instalação das Ferramentas de Depuração para Windows.

Blocos de dados do servidor de origem

O servidor de origem depende de dois blocos de dados dentro do arquivo PDB.

• Lista de arquivos de origem. A criação de um módulo cria automaticamente uma lista de caminhos totalmente qualificados para os arquivos de origem usados para compilar o módulo.
• Bloco de dados. A indexação da fonte conforme descrito anteriormente adiciona um fluxo alternativo ao arquivo PDB chamado "srcsrv". 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.

Na especificação de idioma versão 1, o bloco de dados é dividido em três seções: ini, variáveis e arquivos de origem. Ele 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 expandida.

%fnbksl%()

Todas as barras (/) no texto do parâmetro devem ser substituídas por barras invertidas (\).

%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 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. Veja os exemplos a seguir:

VERSÃO

A versão de especificação de idioma. Esta variável é obrigatória.

VERCTL

Uma cadeia de caracteres que descreve o produto de controle do código-fonte. Essa variável é opcional.

DATA/HORA

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 de variáveis 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. Esta é uma variável necessária.

SRCSRVENV

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

A seção de arquivos de origem 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, a seguinte linha:

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

é interpretado 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 versão. No entanto, a maioria dos sistemas de controle de origem oferece suporte a arquivos de rotulagem de tal forma que o estado de origem de uma determinada compilação pode ser restaurado. Portanto, você pode usar alternadamente o rótulo 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 de origem 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%

Como funciona o servidor de origem

O cliente do servidor de origem é implementado no Symsrv.dll. O cliente não extrai informações diretamente do arquivo PDB; ele usa um manipulador de símbolos como o implementado no Dbghelp.dll. É essencialmente um mecanismo de substituição de variável recursiva que cria uma linha de comando que pode ser usada para extrair o arquivo de origem adequado do sistema de controle do código-fonte. Seu código não deve chamá Symsrv.dll diretamente. Para integrar sua funcionalidade em seu aplicativo, use a função SymGetSourceFile.

A primeira versão do servidor de origem funciona da seguinte maneira. Esse comportamento pode ser alterado em versões futuras.

• O cliente chama a função SrcSrvInit com o caminho de destino a ser usado como base para todas as extrações do arquivo de origem. Ele armazena esse caminho na variável TARG.
• O cliente extrai o fluxo Srcsrv do PDB quando o módulo PDB é carregado e chama a função SrcSrvLoadModule para passar o bloco de dados para o servidor de origem.
• Quando Dbghelp recupera um arquivo de origem, o cliente chama a função SrcSrvGetFile para recuperar os arquivos de origem do controle do código-fonte.
• O servidor de origem procura nas entradas do arquivo de origem no bloco de dados uma entrada que corresponda ao arquivo solicitado. Ele preenche VAR1 para VARn com o conteúdo da entrada do arquivo de origem. Em seguida, expande a variável SRCSRVTRG usando VAR1 para VARn. Se o arquivo já estiver nesse local, ele retornará o local para o chamador. Caso contrário, ele expande a variável SRCSRVCMD para criar o comando necessário para recuperar o arquivo do controle do código-fonte e copiá-lo para o local de destino. Finalmente, ele executa esse comando.

Criando um módulo de provedor de controle de código-fonte

O servidor de origem inclui módulos de provedor para Perforce (p4.pm) e Visual Source Safe (vss.pm). Para criar seu próprio módulo de provedor, você deve implementar o seguinte conjunto de interfaces.

$module::SimpleUsage()

Finalidade: Exibe informações simples de uso do módulo para STDOUT.

Parâmetros: nenhum

Valor de retorno: Nenhum

$module::VerboseUsage()

Finalidade: Exibe informações detalhadas de uso do módulo para STDOUT.

Parâmetros: nenhum

Valor de retorno: Nenhum

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

Finalidade: Inicializa uma instância do módulo do provedor.

Parâmetros: Todos os @ARGV argumentos que não foram reconhecidos por SSIndex.cmd como sendo argumentos gerais.

Valor de retorno: uma referência que pode ser usada em operações posteriores.

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

Finalidade: Permite que o módulo reúna as informações de indexação de origem necessárias para o diretório especificado pelo parâmetro $SourcePath. O módulo não deve assumir que essa entrada será chamada apenas uma vez para cada instância de objeto, pois SSIndex.cmd pode chamá-la várias vezes para caminhos diferentes.

Parâmetros: (1) O diretório local que contém a fonte a ser indexada. (2) Uma referência a um hash contendo todas as entradas do arquivo Srcsrv.ini especificado.

Valor de retorno: Nenhum

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

Objetivo: Fornece as informações necessárias para extrair um único arquivo específico do sistema de controle do código-fonte.

Parâmetros: Um nome de arquivo totalmente qualificado

Valor de retorno: (1) Uma referência de hash das variáveis necessárias para interpretar o $FileEntry retornado. SSIndex.cmd armazena em cache essas variáveis para cada arquivo de origem usado por um único arquivo de depuração para reduzir a quantidade de informações gravadas no fluxo de índice de origem. (2) A entrada de arquivo a ser gravada no fluxo de índice de origem para permitir que SrcSrv.dll extraia esse arquivo do controle de origem. O formato exato desta linha é específico para o sistema de controle do código-fonte.

$TextString = $objref-LongName>()

Finalidade: Fornece uma cadeia de caracteres descritiva para identificar o provedor de controle de origem para o usuário final.

Parâmetros: nenhum

Valor de retorno: O nome descritivo do sistema de controle de origem.

@StreamVariableLines = $objref-SourceStreamVariables>()

Finalidade: Permite que o provedor de controle do código-fonte adicione variáveis específicas do controle do código-fonte ao fluxo de origem para cada arquivo de depuração. Os módulos de exemplo usam esse método para gravar as variáveis EXTRACT_CMD e EXTRACT_TARGET necessárias.

Parâmetros: nenhum

Valor de retorno: a lista de entradas para as variáveis de fluxo de origem.