Compartilhar via

Conceitos de registros

  • Artigo

Visão geral

O vcpkg hospeda uma seleção de bibliotecas empacotadas em portas em https://github.com/Microsoft/vcpkg. Essa coleção de portas é chamada de registro coletado. No entanto, o vcpkg não se limita ao registro coletado. Os usuários podem estender a seleção de portas criando registros personalizados.

Um registro é uma coleção de portas e arquivos auxiliares organizados em uma estrutura específica. Seguindo a estrutura do registro, as portas contidas em um registro podem ser instaladas com os mesmos recursos (controle de versão, cache binário ) oferecidos às portas no registro coletado.

Atualmente, há três tipos de registros:

vcpkg pode ser instruído a considerar portas disponíveis em registros personalizados usando um arquivo vcpkg-configuration.json. Consulte o artigo do tutorial : Instalar uma dependência de um registro baseado em Git para saber como usar registros personalizados em seus projetos.

Estrutura do Registro

Para que o vcpkg seja adaptado a um registro, ele deve estar em conformidade com a seguinte estrutura:

  • Um diretório chamado ports contém a coleção de portas, com cada subdiretório contendo uma porta específica que corresponde ao nome do subdiretório. Por exemplo, os arquivos da porta foo estão localizados em ports/foo.
  • Um diretório chamado versions contém os arquivos que compõem o banco de dados de versões .

Exemplo: estrutura do registro

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

Banco de dados de versões

Todos os registros contêm um diretório versions na raiz, que contém o banco de dados de versões .

Há dois componentes no banco de dados de versões:

  • O arquivo de linha de base
  • Os arquivos de versão

O arquivo de linha de base é um arquivo JSON chamado baseline.json localizado na raiz do diretório versions.

Os arquivos de versões são arquivos JSON com os mesmos nomes que as portas disponíveis. Eles devem existir em versions/<prefix>/<port name>.json, onde <prefix> é a primeira letra do nome da porta seguida por um hífen. Por exemplo, o arquivo de versões para a porta foo deve estar em versions/f-/foo.json.

A finalidade do arquivo de versões é dupla:

  • Listar todas as versões disponíveis de cada porta
  • Indique os locais de recuperação de cada versão.

O formato do arquivo de versão depende do tipo do registro.

Arquivo da linha de base

Todos os registros, independentemente do tipo, devem conter um arquivo chamado baseline.json localizado em versions/baseline.json.

A finalidade do arquivo de linha de base é descrever o conjunto de versões consideradas mais recentes para todas as portas no registro. Espera-se que esse arquivo seja atualizado sempre que uma nova versão de uma porta for adicionada ao registro.

O arquivo é um arquivo JSON composto por um único objeto cujas propriedades são denominadas objetos de linha de base. As propriedades de cada objeto de linha de base são nomes de porta, cujos valores são entradas de versão. O artigo de referência dos registros descreve o layout dos arquivos de linha de base com mais detalhes.

Cada entrada de versão de linha de base é um objeto com as seguintes propriedades:

  • baseline: o valor é a versão da porta que corresponde ao arquivo vcpkg.json.
  • port-version: o valor é a port-version correspondente da porta de seu arquivo vcpkg.json correspondente.

Exemplo de arquivo de linha de base

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

Consulte a documentação de referência para:

Arquivos de versões

Cada porta no Registro tem um arquivo de versões correspondente. Os arquivos de versões são armazenados em versions/<prefix>/<port name>.json, em que <prefix> é a primeira letra do nome da porta seguida por um hífen. Por exemplo, o arquivo de versões para a porta foo está em versions/f-/foo.json.

A finalidade do arquivo de versões é dupla:

  • Listar todas as versões disponíveis de cada porta
  • Aponte para os locais de recuperação de cada uma dessas versões

O layout do arquivo de versões é um objeto que contém uma matriz "versions", com cada entrada nessa matriz sendo um objeto de versão. Um objeto de versão deve conter as seguintes propriedades:

  • Uma propriedade de versão: a chave e o valor da propriedade devem corresponder exatamente aos utilizados pela porta em seu arquivo vcpkg.json. A chave deve ser uma das version, version-semver, version-dateou version-string; o valor deve ser a versão como aparece no arquivo de manifesto da porta (vcpkg.json).
  • port-version: o valor é a port-version da porta, como aparece no arquivo vcpkg.json da porta.
  • git-tree: (somente em registros Git) o valor é o SHA da árvore git correspondente ao diretório da porta. Esse é um SHA calculado com hash do conteúdo do diretório da porta; essa SHA de árvore do Git pode ser usada pelo Git para recuperar o conteúdo da porta que corresponde à árvore do Git fornecida. Isso possibilita que o vcpkg recupere versões antigas de portas do histórico do Git de registros. Leia a seção de registros git para saber como obter esse valor para qualquer versão específica da porta.
  • path: (somente em registros de sistema de arquivos) o valor é o caminho completo para um diretório que contém os arquivos de porta para a versão específica.

Exemplo de um arquivo de versão do registro do sistema de arquivos

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Consulte a documentação de referência para:

Registro interno

O registro integrado é um tipo especial de registro. É o registro padrão usado no modo clássico . No modo de manifesto, quando um registro padrão não é especificado, o vcpkg usa implicitamente o registro interno.

O registro interno refere-se à cópia local do registro coletado criado quando você git clone o repositório do vcpkg de https://github.com/Microsoft/vcpkg. Algumas operações esperam que a variável de ambiente VCPKG_ROOT aponte para um registro interno.

Se vcpkg for adquirido por meio do "one liner" ou do instalador do Visual Studio, o registro interno se tornará equivalente a um registro git apontando para o repositório https://github.com/Microsoft/vcpkg.

Registros do Git

Um registro do Git é um repositório que segue a estrutura do registro e aproveita os recursos do Git para fornecer controle de versão para os ports no registro. O registro coletado em https://github.com/Microsoft/vcpkg é uma implementação de um registro do Git.

Os registros git podem ser hospedados em qualquer provedor de repositório Git, permitindo que você use o serviço de hospedagem Git escolhido para controlar o acesso ao registro personalizado e, ao mesmo tempo, facilitar o compartilhamento do registro.

Os registros git são o método recomendado para implementar um registro personalizado. Como o mecanismo de controle de versão é o mesmo usado pelo registro curado, os registros do Git podem utilizar o x-add-version para gerenciar seus arquivos de banco de dados de versão.

Consulte a referência aos registros para obter detalhes de implementação dos registros do Git.

Adicionar uma nova versão a um registro git

O comando x-add-version pode ser usado para adicionar uma nova porta ou uma nova versão ao Registro. Ao adicionar versões usando esse comando, há algumas coisas para ter em mente:

Importante

Ao adicionar uma nova versão, lembre-se sempre de atualizar a versão declarada da porta para uma ainda não publicada, para evitar reescrever o histórico de versões.

Quando você estiver fazendo alterações em uma porta, a primeira etapa deve ser aumentar sua versão no arquivo vcpkg.json. Se as alterações incluírem uma atualização para a versão upstream do pacote, lembre-se de definir o port-version como 0; caso contrário, lembre-se de aumentar o port-version em um.

O comando x-add-version requer que todas as alterações de porta sejam confirmadas no repositório antes de atualizar o banco de dados de versão.

Exemplo: adicionar uma nova versão de port a um registro Git

git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json

As opções de redirecionamento --x-builtin-ports-root e --x-builtin-registry-versions-dir devem apontar para os diretórios ports e versions do registro, respectivamente.

Uma vez, o comando x-add-version é executado com êxito, altere a última confirmação para incluir as alterações de arquivo de versões.

git commit --amend -m "Update foo to new version"

Registros do sistema de arquivos

Os registros do sistema de arquivos são uma implementação de um registro que reside em um sistema de arquivos. Eles seguem a estrutura comum do Registro, mas não usam o Git para oferecer recursos de controle de versão. Em vez disso, eles usam uma forma primitiva de controle de versão usando um caminho distinto para cada versão de suas portas.

Esse tipo de registro é adequado para ser um campo de teste para suas portas ou para fornecer uma alternativa para um registro em um sistema de controle de versão não Git. Os registros do sistema de arquivos não são recomendados para uma grande coleção de portas e nenhuma ferramenta é fornecida para manipular os arquivos de banco de dados de versão para esse tipo de registro.

Consulte a referência dos registros para obter detalhes sobre como implementar um registro de sistema de arquivos.

Consumir registros

Para consumir um registro personalizado em seu projeto, você precisa criar um arquivo de configuração (vcpkg-configuration.json) ao lado do arquivo de manifesto do projeto (vcpkg.json).

Registro padrão

Ao resolver nomes de porta, o registro padrão funciona como o fallback quando o nome de uma porta não corresponde a nenhum dos padrões de pacote declarados por outros registros na matriz registries.

Como uma conveniência para os usuários que não estão se envolvendo com registros personalizados, o vcpkg adiciona implicitamente o registro interno como o registro padrão. Para alterar esse comportamento, o registro padrão pode ser definido como qualquer registro ou desabilitado completamente usando o Propriedade default-registry.

Exemplo: definir um registro personalizado como padrão

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

Exemplo: Desabilitar o registro padrão

vcpkg-configuration.json

{
  "default-registry": null
}

Matriz de registros

Para estender a seleção de portas disponíveis para instalação com vcpkg, você pode especificar registros adicionais usando a matriz registries.

Exemplo: adicionar registros personalizados à configuração

Nota

Dependendo do tipo de registro, talvez seja necessário fornecer informações diferentes na matriz registries. Consulte a referência vcpkg-configurtion.json para saber quais propriedades são necessárias para cada tipo de registro.

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://my.privateregistry.git",
      "baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
      "packages": [ "foo" ]
    },
    {
      "kind": "filesystem",
      "path": "C:/path/to/registry",
      "baseline": "baseline1",
      "packages": [ "bar" ]
    }
  ]
}

Não reescreva o histórico de versões

Depois que uma versão for publicada nos arquivos de versões, não altere sua git-tree associada em um registro do Git ou em um diretório do sistema de arquivos.

Um dos princípios de design do vcpkg é que as versões das dependências instaladas não são alteradas sem intervenção do usuário. Reescrever o histórico de arquivos de versões alterando uma entrada de git-tree viola esse princípio.

Se a versão existente tiver problemas, prefira criar um novo port-version.

Não exclua arquivos de versões

Nota

Esta seção se aplica apenas a registros do Git

Ao remover uma porta do registro, remova seu conteúdo do diretório de portas e sua entrada no arquivo de linha de base. Mas não remova o arquivo de versões associado.

Mesmo que uma porta não exista mais no registro, desde que o arquivo de versões permaneça, os usuários da porta poderão instalar versões antigas usando versão overrides.

Próximas etapas

Aqui estão algumas tarefas para tentar a seguir: