Partilhar 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 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 de origem.

Indexação de fontes

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 na origem durante o processo de compilação após a criação do aplicativo. As informações necessárias para o 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.

  • Servidor Team Foundation
  • Perforce
  • Visual SourceSafe
  • CVS
  • Subversão

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.

Ferramenta Descrição
Srcsrv.ini Este arquivo é a lista mestra de todos os servidores de controle do código-fonte. Cada entrada tem o seguinte formato:MYSERVER=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 em busca de 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 de origem 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 interagir 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 Este 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 da 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 Este 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 o SymEnumSourceFiles ou função de 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 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 construir 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 versão 1 da especificação de idioma, o bloco de dados é dividido em três seções: ini, variáveis e arquivos de origem. 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 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 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.

VERCTL

Uma cadeia de caracteres que descreve o produto de controle do código-fonte. 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 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

é 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 versã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, 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 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%) impressão -o %srcsrvtrg% -q %depot%/%var3%@%label%

Como funciona o servidor de origem

O cliente do servidor de origem é implementado em Symsrv.dll. O cliente não extrai informações diretamente do ficheiro APO; 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 chamáSymsrv.dll diretamente. Para integrar sua funcionalidade em seu aplicativo, use a funçãoSymGetSourceFile.

A primeira versão do servidor de origem funciona da seguinte forma. 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 arquivos 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 o 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 do arquivo de origem no bloco de dados em busca de uma entrada que corresponda ao arquivo solicitado. Ele preenche VAR1 para VARn n 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 este comando.

Criando um módulo de 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 de retorno: Nenhum

$module::VerboseUsage()

Finalidade: Exibe informações detalhadas sobre o 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 que contém todas as entradas do ficheiro Srcsrv.ini especificado.

Valor de retorno: 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 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 do código-fonte. 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 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 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 escrever 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.