Criando registros

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

Visão geral

Registries são conjuntos de ports e suas versões. Existem duas opções principais de implementação para registros, se você quiser criar seus próprios: registros git e registros do 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 mais como um campo de testes. Dado que eles literalmente residem em seu sistema de arquivos, a única maneira de compartilhá-los é por meio de diretórios compartilhados. No entanto, os registros do sistema de arquivos podem ser úteis como uma forma de representar registros mantidos em sistemas de controle de versão não-git, supondo que se tenha alguma maneira de colocar o registro no disco.

Esperamos que o conjunto de tipos de registro cresça ao longo do tempo; se você quiser suporte para registros criados 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 de trabalho para consultar. Nós escrevemos um e colocamos aqui:

Microsoft/vcpkg-docs: registro vcpkg.

Todos os registros git devem ter um versions/baseline.json arquivo. Este arquivo contém o conjunto de "versões mais recentes" em um determinado commit. Ele é disposto como um objeto de nível superior contendo apenas o "default" campo. Este 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 contidas no registro, juntamente com onde essas versões são armazenadas. O resto do registro atua apenas como um armazenamento de backup, 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 port em questão; deve ser exatamente igual ao vcpkg.json arquivo, incluindo os campos de versão e "port-version".
• O "git-tree" campo, que é uma árvore git; em outras palavras, o que você obtém quando escreve git rev-parse COMMIT-ID:path/to/port.

O campo version para ports com arquivos obsoletos 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álida 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 os diretórios de porta. No entanto, o idioma no 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 um ID de confirmação, esse ID de confirmação sempre deve existir e ser acessível a partir do commit HEAD, que é o que é realmente buscado. Isso significa que seu commit 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 de uma url remota, os registros integrados consultam o $VCPKG_ROOT/.git diretório do clone vcpkg. Eles usam o diretório atualmente verificado $VCPKG_ROOT/versions como fonte de informações de controle de versão.

Adicionando uma nova versão

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

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

Depois de terminar o teste, você precisará certificar-se de que o diretório como está está sob a alçada do git. Você fará isso criando um commit temporário:

> 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 seu versions/k-/kitten.json, você pode adicionar (supondo que esteja adicionando a 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ê também desejará modificar sua versions/baseline.json nova versão:

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

e altere seu commit 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 de trabalho para consultar. Nós 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. Este 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 que contém um mapa do nome da versão para "objetos de linha de base", que mapeiam nomes de porta para a versão 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 contar com o sistema de controle de versão aqui. Uma opção possível é fazer um lançamento diário e ter suas "versões" como datas.

Aviso

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

Aqui está um exemplo de um , válido baseline.jsonpara um registro que decidiu sobre as datas de 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 contidas no registro, juntamente com onde essas versões são armazenadas. O resto do registro atua apenas como um armazenamento de backup, 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 port em questão; deve ser exatamente igual ao vcpkg.json arquivo, incluindo os campos de versão 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 da porta. Deve ser algo como "$/path/to/port/dir"

O campo version para ports com arquivos obsoletos CONTROL é "version-string".

Em geral, não é importante onde você coloca os diretórios de porta. No entanto, o idioma em vcpkg é seguir um pouco de perto o que o registro vcpkg embutido faz: sua kitten versão x.y.z port at deve ser colocada em ports/kitten/x.y.z, com versões de port anexadas como você achar melhor (embora, como # 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 para usuários downstream.

Aqui está um exemplo de um banco de dados de versão válida 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 muitas cópias. A primeira coisa a fazer é copiar a versão mais recente do seu port 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 terminar o teste, você pode adicionar esta nova versão à parte superior do seu 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!