Compartilhar via

Criando registros

  • Artigo

Para obter informações sobre como consumir registros, consulte Usando registros.

Visão geral

Registros são coleções de portas e suas versões. Há duas opções principais de implementação para registros, se você quiser criar seus próprios: registros git e registros de sistema de arquivos.

Os registros Git são repositórios git simples e podem ser compartilhados pública ou privadamente por meio de mecanismos normais para repositórios git. O repositório vcpkg, por exemplo, é um registro git.

Os registros do sistema de arquivos são projetados como mais um campo de testes. Dado que eles literalmente vivem em seu sistema de arquivos, a única maneira de compartilhá-los é através de diretórios compartilhados. No entanto, os registros do sistema de arquivos podem ser úteis como uma maneira de representar registros mantidos em sistemas de controle de versão não-git, supondo que se tenha alguma maneira de obter o registro no disco.

Esperamos que o conjunto de tipos de registro cresça ao longo do tempo; Se você gostaria de suporte para registros construídos em seu sistema de controle de versão público favorito, não hesite em abrir um PR.

A estrutura básica de um registro é:

  • O conjunto de versões que são consideradas "mais recentes" em determinados momentos da história, conhecido como "linha de base".
  • O conjunto de todas as versões de todas as portas e onde encontrar cada uma delas no registro.

Registros do Git

Como você está acompanhando esta documentação, pode ser útil ter um exemplo funcional para consultar. Escrevemos um e colocamos aqui:

Northwind Traders: registro vcpkg.

Todos os registros git devem ter um versions/baseline.json arquivo. Esse arquivo contém o conjunto de "versões mais recentes" em uma determinada confirmação. Ele é disposto como um objeto de nível superior contendo apenas o "default" campo. Esse campo deve conter um objeto mapeando nomes de porta para a versão que é atualmente a mais recente.

Aqui está um exemplo de um baseline.json válido:

{
  "default": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

O versions diretório contém todas as informações sobre quais versões de quais pacotes estão contidos no registro, juntamente com onde essas versões são armazenadas. O resto do registro atua apenas como um armazenamento de apoio, no que diz respeito ao vcpkg: apenas as coisas dentro do versions diretório serão usadas para direcionar como seu registro é visto pelo vcpkg.

Cada porta em um registro deve existir no diretório versions como <first letter of port>-/<name of port>.json; em outras palavras, as informações sobre a kitten porta estariam localizadas em versions/k-/kitten.json. Este deve ser um objeto de nível superior com apenas um único campo: "versions". Este campo deve conter uma matriz de objetos de versão:

  • A versão do porto em questão; deve ser exatamente igual ao vcpkg.json arquivo, incluindo os campos version e "port-version".
  • O "git-tree" campo, que é uma árvore git, ou seja, o que você obtém quando escreve git rev-parse COMMIT-ID:path/to/port.

O campo de versão para portas com arquivos preteridos CONTROL é "version-string".

Aviso

Uma parte muito importante dos registros é que as versões nunca devem ser alteradas. A atualização para uma ref posterior nunca deve remover ou alterar uma versão existente. Deve ser sempre seguro atualizar um registro.

Aqui está um exemplo de um banco de dados de versão válido para uma kitten porta com uma versão:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

Em geral, não é importante onde você coloca diretórios de porta. No entanto, o idioma em vcpkg é seguir o que o registro vcpkg embutido faz: sua kitten porta deve ser colocada em ports/kitten.

Aviso

Outra coisa a ter em mente é que, quando você atualiza um registro, todas as versões anteriores também devem estar acessíveis. Como o usuário definirá sua linha de base como uma ID de confirmação, essa ID de confirmação sempre deve existir e estar acessível a partir da confirmação HEAD, que é o que é realmente buscado. Isso significa que seu compromisso HEAD deve ser filho de todos os commits HEAD anteriores.

Registros internos

Os registros internos são tratados como registros Git especiais. Em vez de buscar em uma URL remota, os registros internos consultam o $VCPKG_ROOT/.git diretório do clone vcpkg. Eles usam o diretório atualmente com check-out $VCPKG_ROOT/versions como a fonte para informações de controle de versão.

Adicionando uma nova versão

Há alguns truques git envolvidos na criação de uma nova versão de um port. A primeira coisa a fazer é fazer algumas alterações, atualizar o "port-version" campo de versão regular conforme necessário e, em seguida, testar com overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten.

Depois de concluir o teste, você precisará se certificar de que o diretório como está está sob a alçada do git. Você fará isso criando uma confirmação temporária:

> git add ports/kitten
> git commit -m 'temporary commit'

Em seguida, obtenha o ID da árvore git do diretório:

> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07

Em seguida, você pode adicionar essa versão ao banco de dados de versões. Na parte superior do , versions/k-/kitten.jsonvocê pode adicionar (supondo que esteja adicionando versão 2.6.3#0):

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

Em seguida, você vai querer modificar o seu versions/baseline.json com sua nova versão também:

{
  "default": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

e altere seu compromisso atual:

> git commit --amend

Então compartilhe!

Registros do sistema de arquivos

Como você está acompanhando esta documentação, pode ser útil ter um exemplo funcional para consultar. Escrevemos um e colocamos aqui:

Exemplo de registro do sistema de arquivos.

Todos os registros do sistema de arquivos devem ter um versions/baseline.json arquivo. Esse arquivo contém o conjunto de "versões mais recentes" para uma determinada versão do registro. Ele é apresentado como um objeto de nível superior contendo um mapa do nome da versão para "objetos de linha de base", que mapeiam nomes de porta para a versão que é considerada "mais recente" para essa versão do registro.

Os registros do sistema de arquivos precisam decidir sobre um esquema de controle de versão. Ao contrário dos registros git, que têm o esquema de controle de versão implícito de refs, os registros do sistema de arquivos não podem confiar no sistema de controle de versão aqui. Uma opção possível é fazer um lançamento diário, e fazer com que suas "versões" sejam datas.

Aviso

Uma linha de base não deve ser modificada depois de publicada. Se você quiser alterar ou atualizar versões, será necessário criar uma nova linha de base no baseline.json arquivo.

Aqui está um exemplo de um , válido baseline.jsonpara um registro que decidiu datas para suas versões:

{
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

O versions diretório contém todas as informações sobre quais versões de quais pacotes estão contidos no registro, juntamente com onde essas versões são armazenadas. O resto do registro atua apenas como um armazenamento de apoio, no que diz respeito ao vcpkg: apenas as coisas dentro do versions diretório serão usadas para direcionar como seu registro é visto pelo vcpkg.

Cada porta em um registro deve existir no diretório versions como <first letter of port>-/<name of port>.json; em outras palavras, as informações sobre a kitten porta estariam localizadas em versions/k-/kitten.json. Este deve ser um objeto de nível superior com apenas um único campo: "versions". Este campo deve conter uma matriz de objetos de versão:

  • A versão do porto em questão; deve ser exatamente igual ao vcpkg.json arquivo, incluindo os campos version e "port-version".
  • O "path" campo: um diretório relativo, enraizado na base do registro (em outras palavras, o diretório onde versions está localizado), para o diretório de porta. Deve ser algo como "$/path/to/port/dir"

O campo de versão para portas com arquivos preteridos CONTROL é "version-string".

Em geral, não é importante onde você coloca diretórios de porta. No entanto, o idioma em vcpkg é seguir um pouco de perto o que o registro vcpkg construído faz: sua kitten porta na versão x.y.z deve ser colocada em ports/kitten/x.y.z, com versões de porta anexadas como você achar melhor (embora desde # que não seja um bom caractere para usar para nomes de arquivos, talvez use _).

Aviso

Uma parte muito importante dos registros é que as versões nunca devem ser alteradas. Nunca se deve remover ou alterar uma versão existente. Suas alterações no registro não devem alterar o comportamento dos usuários downstream.

Aqui está um exemplo de um banco de dados de versão válido para uma kitten porta com uma versão:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Adicionar uma nova versão

Ao contrário dos registros git, adicionar uma nova versão a um registro do sistema de arquivos envolve principalmente muita cópia. A primeira coisa a fazer é copiar a versão mais recente da sua porta para um novo diretório de versão, atualizar a versão e "port-version" os campos conforme necessário e, em seguida, testar com overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten/new-version.

Depois de concluir o teste, você pode adicionar esta nova versão à parte superior do :versions/k-/kitten.json

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.3_0"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Em seguida, você também desejará modificar sua versions/baseline.json nova versão (lembre-se de não modificar as linhas de base existentes):

{
  "2021-04-17": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

E pronto!