Conceitos de registos

Visão geral

VCPKG hospeda uma seleção de bibliotecas empacotadas em portas em https://github.com/Microsoft/vcpkg. Essa coleção de portas é chamada de de registro com curadoria. No entanto, o vcpkg não se limita ao registo selecionado. 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 registo, os portos contidos num registo podem ser instalados com os mesmos recursos (versão, cache binário) oferecidos aos portos no registo selecionado.

Existem atualmente três tipos de registos:

• O registo incorporado,
• repositórios Git, e
• registros do sistema de arquivos.

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

Estrutura do registo

Para que o vcpkg interaja com um registo, tem de 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 correspondente ao nome do subdiretório. Por exemplo, os arquivos para a 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 registo

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

Base de dados de versões

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

Há dois componentes para o banco de dados de versões:

• O ficheiro 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 das portas disponíveis. Eles devem existir em versions/<prefix>/<port name>.json, onde <prefix> é a primeira letra do nome da porta seguida de um hífen. Por exemplo, o ficheiro de versões para a porta foo deve estar em versions/f-/foo.json.

O objetivo do arquivo de versões é duplo:

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

O formato do ficheiro de versão depende do tipo de registo.

Arquivo de Referência

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

O objetivo do arquivo de linha de base é descrever o conjunto de versões que são consideradas as mais recentes para todas as portas no registro. Espera-se que este ficheiro seja atualizado sempre que uma nova versão de uma porta é adicionada ao registo.

O arquivo é um arquivo JSON composto por um único objeto cujas propriedades são nomeadas 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 de 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 ficheiro vcpkg.json.
• port-version: o valor é o port-version da porta que corresponde ao 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:

• Layout de arquivo de linha de base para registros Git
• Layout de arquivo de linha de base para registros de sistema de arquivos

Arquivos de versões

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

O objetivo do arquivo de versões é duplo:

• 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 version deve conter as seguintes propriedades:

• Uma propriedade de versão: a chave e o valor da propriedade devem corresponder aos usados pela porta no seu arquivo vcpkg.json. A chave deve ser uma das version, version-semver, version-dateou version-string; O valor deve ser a versão tal como aparece no ficheiro de manifesto da porta (vcpkg.json).
• port-version: o valor é o port-version da porta como aparece no ficheiro vcpkg.json da porta.
• git-tree: (somente nos registros Git) o valor é o SHA git-tree correspondente ao diretório da porta. Este é um SHA calculado ao aplicar uma função de hash no conteúdo do diretório do porto; este SHA de Git-tree pode ser usado pelo Git para recuperar o conteúdo do porto que corresponde à Git-tree fornecida. Isso possibilita que o vcpkg recupere versões antigas de portas dos registros do histórico do Git. Leia a secção de registos git para saber como obter este valor para qualquer versão do porto.
• path: (somente em registros do 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:

• Layout de arquivo de versões para registros Git
• Layout de arquivo de versões para registros de sistemas de ficheiros

Registro integrado

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

O registro interno refere-se à cópia local do registro curado criado quando você git clone o repositório 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 o vcpkg for adquirido através da linha de comando "one liner" ou do instalador do Visual Studio, o registro interno torna-se equivalente a um registro Git apontando para o repositório https://github.com/Microsoft/vcpkg.

Repositórios Git

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

Os registros Git podem ser hospedados em qualquer provedor de repositório Git, permitindo que você use seu serviço de hospedagem Git escolhido para controlar o acesso ao seu registro personalizado e, ao mesmo tempo, tornar seu registro fácil de compartilhar.

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 selecionado, os registros Git podem usar o x-add-version para gerenciar seus arquivos de banco de dados de versão.

Consulte a referência de registos para obter detalhes de implementação de registos Git.

Adicionando 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 este comando, há algumas coisas a ter em mente:

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 porta 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 seu registro, respectivamente.

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

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

Registos do sistema de ficheiros

Registros de sistema de arquivos são uma implementação de um registro que vive em um sistema de arquivos. Eles seguem a estrutura de registro comum, 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 testes para suas portas ou para fornecer uma alternativa para um registro em um sistema de controle de versão não-Git. Registros de sistema de arquivos não são recomendados para grandes coleções de portas e nenhuma ferramenta é fornecida para manipular os arquivos de banco de dados de versão para esse tipo de registro.

Consulte as referências de registos para obter detalhes sobre como implementar um registo de sistema de arquivos.

Consumir os registos

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 seu projeto (vcpkg.json).

Registro padrão

Quando resolver nomes de porta, o registro padrão funciona como 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, vcpkg adiciona implicitamente o de registro interno como o registro padrão. Para alterar esse comportamento, o registro padrão pode ser definido para qualquer registro ou desativado completamente usando o default-registry propriedade.

Exemplo: Definir um registo personalizado como predefinido

vcpkg-configuration.json

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

Exemplo: Desativar o registo predefinido

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

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" ]
    }
  ]
}

Práticas recomendadas para registos

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

Depois que uma versão tiver sido publicada nos arquivos de versões, não altere o seu git-tree associado num repositório git ou numa pasta num gestor de ficheiros.

Um dos princípios de design do vcpkg é que as versões das dependências instaladas não mudam sem a intervenção do usuário. Reescrever o histórico do arquivo 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

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

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

Próximos passos

Aqui estão algumas tarefas para tentar a seguir:

• Crie seu próprio registro baseado em Git
• Instalar pacotes a partir de um repositório personalizado
• Leia a documentação de referência dos registos