Compartilhar via

Servidor de origem

  • Artigo

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 um curso de anos, é importante examinar o código-fonte como ele existia quando a versão do módulo em questão foi criada.

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 pela origem.

Indexação de origem

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

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

Atualmente, o servidor de origem fornece scripts que devem funcionar com os seguintes sistemas de controle do código-fonte.

  • Team Foundation Server
  • Forçosamente
  • Visual SourceSafe
  • CVS
  • Subversão

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

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

Ferramenta Descrição
Srcsrv.ini Esse arquivo é a lista mestra de todos os servidores de controle do código-fonte. Cada entrada tem o seguinte formato:=serverinfo
Ao usar o Perforce, as informações do servidor consistem no caminho de rede completo para o servidor, seguido por dois-pontos, seguido pelo número da porta que ele usa. Por exemplo:
MYSERVER=machine.corp.company.com:1666
Esse arquivo pode ser instalado no computador que executa o depurador. Quando o servidor de origem é iniciado, ele examina Srcsrv.ini para obter valores; esses valores substituirão as informações contidas no arquivo PDB. Isso permite que os usuários configurem um depurador para usar um servidor de controle do código-fonte alternativo no momento da depuração.
Para obter mais informações, consulte o exemplo Srcsrv.ini instalado com as ferramentas do servidor de origem.
Ssindex.cmd Esse script cria a lista de arquivos verificados no controle do código-fonte, juntamente com as informações de versão de cada arquivo. Ele armazena um subconjunto dessas informações nos arquivos .pdb gerados quando você criou o aplicativo. O script usa um dos seguintes módulos Perl para interface com o controle do código-fonte: P4.pm (Perforce) ou Vss.pm (Visual Source Safe). Para obter mais informações, execute o script com o -? ou-?? (ajuda detalhada) ou examine o script.
Srctool.exe Esse utilitário lista todos os arquivos indexados em um arquivo .pdb. Para cada arquivo, ele lista o caminho completo, o servidor de controle do código-fonte e o número de versão do arquivo. Você pode usar essas informações para recuperar arquivos sem usar o servidor de origem. Para obter mais informações, execute o utilitário com o /? opção.
Pdbstr.exe Esse utilitário é usado pelos scripts de indexação para inserir as informações de controle de versão no fluxo alternativo "srcsrv" do arquivo .pdb de destino. Ele também pode ler qualquer fluxo de um arquivo .pdb. Você pode usar essas informações para verificar se os scripts de indexação estão funcionando corretamente. Para obter mais informações, execute o utilitário com o /? opção.

 

Recuperando o arquivo de origem

A API DbgHelp fornece acesso à funcionalidade do servidor de origem por meio da funçãoSymGetSourceFile. 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:\mysource

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 fim 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. Indexar a origem conforme descrito anteriormente adiciona um fluxo alternativo ao arquivo PDB chamado "srcsrv". O script que insere esses dados depende do processo de build 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 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 percentuais (%). O texto entre sinais percentuais é 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 em sinais percentuais e tratado como uma variável a ser expandida.

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

VERSÃO

A versão de especificação do idioma. Essa variável é necessária.

VERCTL

Uma cadeia de caracteres que descreve o produto de controle do código-fonte. 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 contém variáveis que descrevem como extrair um arquivo do controle do código-fonte. Ele também pode ser usado para definir o 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 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. Essa é uma variável necessária.

SRCSRVENV

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

A seção 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 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 versã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ê poderia, como alternativa, 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 usa o sinal de acesso (@) para indicar um rótulo, você pode modificar a variável SRCSRVCMD da seguinte maneira:

sd.exe -p %fnvar%(%var2%) imprime -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 em 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 chamar Symsrv.dll diretamente. Para integrar sua funcionalidade ao seu aplicativo, use a funçãoSymGetSourceFile.

A primeira versão do servidor de origem funciona da seguinte maneira. Esse comportamento pode mudar 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 de arquivo de origem. Ele armazena esse caminho na variável TARG.
  • O cliente extrai o fluxo Srcsrv do PDB quando o PDB do módulo é 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 pesquisa as entradas de arquivo de origem no bloco de dados em busca de uma entrada que corresponda ao arquivo solicitado. Ele preenche VAR1 para VARn com o conteúdo da entrada do arquivo de origem. Em seguida, ele 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. Por fim, ele executa este comando.

Criando um módulo do provedor de controle do 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 retornado: Nenhum

$module::VerboseUsage()

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

Parâmetros: Nenhum

Valor retornado: Nenhum

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

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

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

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

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

Finalidade: permite que o módulo colete 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 origem a ser indexada. (2) Uma referência a um hash que contém todas as entradas do arquivo de Srcsrv.ini especificado.

Valor retornado: Nenhum

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

Finalidade: 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 essas variáveis em cache 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 do código-fonte. O formato exato dessa 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 do código-fonte para o usuário final.

Parâmetros: Nenhum

Valor de retorno: o nome descritivo do sistema de controle do código-fonte.

@StreamVariableLines = $objref->SourceStreamVariables()

Finalidade: permite que o provedor de controle do código-fonte adicione variáveis específicas de 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 escrever as variáveis de 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.