Referência dos registos

Visão geral

Este artigo descreve os detalhes de implementação para cada tipo de registo. Especificamente, este arquivo se preocupa com o layout recomendado para cada tipo de registro e o conteúdo esperado de suas respetivas versões banco de dados.

Registos Git

Layout de arquivo de linha de base em registros Git

Campos de nível superior

O objeto de nível superior em um arquivo de baseline.json é um dicionário, cada chave neste dicionário é uma chamada linha de base. Devido aos detalhes de implementação dos registros Git, é necessário que exista um de linha de base nomeado com o nome "padrão" e que ele contenha um mapeamento de todas as portas no registro para sua versão de linha de base.

BaselineObject

O objeto de linha de base é um dicionário, com cada chave correspondendo a um nome de porta no registro e seu valor sendo a versão mais recente da porta.

BaselineVersionObject

Exemplo de um arquivo baseline.json em um registro Git

Em um registro que contém uma única porta chamada foo na versão 1.0.0#1, o conteúdo do arquivo baseline.json deve ser:

{
  "default": {
    "foo": { 
      "baseline": "1.0.0", 
      "port-version": 1
    }
  }
}

Layout do arquivo de versão em registros Git

O diretório versions contém todas as informações sobre quais versões de pacotes estão contidas no registro, juntamente com o método para recuperar essas versões do histórico do repositório.

O ficheiro de versão de cada pacote é um ficheiro JSON com o mesmo nome base do pacote, colocado num subdiretório do diretório de versões que é a primeira letra do pacote, seguida de um traço. Por exemplo, o ficheiro de versão do pcre2 pacote é versions\p-\pcre2.json.

Campos de nível superior

VersionObject

Exemplo de um arquivo de versões do registro Git

{
  "versions": [
    {
      "git-tree": "963060040c3ca463d17136e39c7317efb15eb6a5",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "git-tree": "548c90710d59c174aa9ab10a24deb69f1d75ff8f",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Obtenção de uma git-tree SHA

O vcpkg usa os recursos do Git para recuperar versões específicas de uma porta contida em seu histórico de confirmação. O método usado é recuperar o objeto git-tree do repositório, conforme especificado no arquivo de versões de uma porta.

Cada diretório de porta em um registro Git tem um SHA exclusivo associado a ele (referido como git-tree nos arquivos de versões). O SHA é calculado usando o conteúdo do diretório; cada vez que uma alteração é confirmada no repositório que modifica um diretório, seu SHA é recalculado.

O Git permite que você recupere o conteúdo de um determinado diretório a qualquer momento de seu histórico, desde que você conheça seu SHA específico. Ao fazer uso desse recurso, o vcpkg pode indexar versões de porta específicas com seus respetivos SHA (git-tree).

Para obter o SHA de um diretório de porta em qualquer revisão, o seguinte comando Git pode ser usado:

git -C <path/to/ports> ls-tree --format='%(objectname)' <commit sha> -- <portname>

Exemplo:

git -C %VCPKG_ROOT%/ports ls-tree --format='%(objectname)' HEAD -- curl
6ef1763f3cbe570d6378632c9b5793479c37fb07

O comando retorna o SHA do diretório que contém a porta curl na revisão atual (HEAD).

É possível mostrar o conteúdo do git-tree usando o comando git show <git-tree>:

git show 6ef1763f3cbe570d6378632c9b5793479c37fb07
tree 6ef1763f3cbe570d6378632c9b5793479c37fb07

0005_remove_imp_suffix.patch
0020-fix-pc-file.patch
0022-deduplicate-libs.patch
cmake-config.patch
cmake-project-include.cmake
dependencies.patch
export-components.patch
portfile.cmake
redact-input-vars.diff
usage
vcpkg-cmake-wrapper.cmake
vcpkg.json

Ou o conteúdo de um arquivo específico com git show <git-tree>:<file>:

git show 6ef1763f3cbe570d6378632c9b5793479c37fb07:usage
curl is compatible with built-in CMake targets:

    find_package(CURL REQUIRED)
    target_link_libraries(main PRIVATE CURL::libcurl)

Manter os arquivos de banco de dados atualizados usando esses comandos Git em um processo manual pode ser uma tarefa difícil. Por esse motivo, recomendamos o uso do comando x-add-version, que automatiza o processo, desde que o repositório siga a estrutura de registro recomendada. Consulte o artigo Tutorial: Publicar pacotes em um registro vcpkg privado usando o Git para obter um exemplo de como publicar uma porta em um registro Git.

Registos do sistema de ficheiros

Layout de arquivo de linha de base em registros de sistema de arquivos

Campos de nível superior

O objeto de nível superior em um arquivo de baseline.json é um dicionário, cada chave neste dicionário é uma chamada linha de base. As linhas de base devem conter mapeamentos de todas as portas do Registro para sua versão de linha de base.

BaselineObject

O objeto de linha de base é um dicionário, com cada chave correspondendo a um nome de porta no registro e seu valor sendo a versão mais recente da porta.

BaselineVersionObject

O layout do arquivo de linha de base em um registro do sistema de arquivos é o mesmo que para registros Git. A única diferença é que os sistemas de arquivos não exigem uma linha de base default.

Exemplo de um baseline.json ficheiro num registo de sistema de ficheiros

{
  "2024-12-01": {
    "foo": {
      "baseline": "1.0.0",
      "port-version": 1
    }
  }
}

Layout de ficheiros de versão nos registos do sistema de ficheiros

O diretório versions contém todas as informações sobre quais versões de pacotes estão contidas no registro, juntamente com o método para recuperar essas versões de um local do sistema de arquivos.

O ficheiro de versão de cada pacote é um ficheiro JSON com o mesmo nome base do pacote, colocado num subdiretório do diretório de versões que é a primeira letra do pacote, seguida de um traço. Por exemplo, o ficheiro de versão do fmt pacote é versions\f-\fmt.json.

Campos de nível superior

VersionObject

Ao especificar a path de um registro, o caractere $ pode ser usado para fazer referência à raiz do registro. Caso contrário, caminhos absolutos podem ser usados.

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

Próximos passos

Aqui estão algumas tarefas para tentar a seguir:

• Leia a documentação conceitual dos registros
• Crie seu próprio registro baseado em Git
• Instalar pacotes a partir de um de registo personalizado