Referência de controle de versão

O controle de versão permite que você controle deterministicamente as revisões precisas das dependências usadas pelo seu projeto a partir do seu arquivo de manifesto. O controle de versão só está disponível para modo de manifesto usuários.

Para obter mais informações sobre o algoritmo de versionamento vcpkg e conceitos de alto nível, consulte Versioning Concepts.

Para obter um exemplo com contexto, consulte nosso guia para introdução ao controle de versão.

Esquemas de versões

As portas no vcpkg devem tentar seguir as convenções de versionamento usadas pelos autores do pacote. Por esse motivo, ao declarar a versão de um pacote, deve ser usado o esquema adequado.

Cada esquema de controle de versão define suas próprias regras sobre o que é uma cadeia de caracteres de versão válida e, mais importante, as regras de como classificar versões usando o mesmo esquema.

Os esquemas de versionamento compreendidos pelo vcpkg são:

Um manifesto deve conter apenas uma declaração de versão.

version

Aceita cadeias de caracteres de versão que seguem um esquema descontraído, separado por pontos e semver.

A versão é logicamente composta por seções numéricas separadas por pontos (.). Cada seção deve conter um número inteiro positivo sem zeros à esquerda.

O padrão regex para este esquema de versionamento é: (0|[1-9]\d*)(\.(0|[1-9]\d*))*

Comportamento de classificação: Ao comparar duas versões, cada seção é comparada da esquerda para a direita pelo seu valor numérico, até que a primeira diferença seja encontrada. Uma versão com o menor conjunto de seções tem precedência sobre outra com um conjunto maior de seções, dado que todas as seções anteriores são comparadas igualmente.

Exemplo:

0 < 0.1 < 0.1.0 < 1 < 1.0.0 < 1.0.1 < 1.1< 2.0.0

version-semver

Aceita cadeias de caracteres de versão que seguem convenções de controle de versão semânticas, conforme descrito na especificação de controle de versão semântico .

Comportamento de classificação: As cadeias de caracteres são classificadas seguindo as regras descritas na especificação de controle de versão semântica.

Exemplo:

1.0.0-1 < 1.0.0-alpha < 1.0.0-beta < 1.0.0 < 1.0.1 < 1.1.0

version-date

Aceita cadeias de caracteres de versão que podem ser analisadas até uma data seguindo o formato ISO-8601 YYYY-MM-DD. Os identificadores de desambiguação são permitidos na forma de números inteiros separados por pontos, positivos e inteiros sem zeros à esquerda.

Este é o esquema de versionamento recomendado para bibliotecas "Live at HEAD" que não têm versões de lançamento estabelecidas.

O padrão regex para este esquema de versionamento é: \d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*

Comportamento de classificação: As cadeias de caracteres são classificadas primeiro por sua parte de data e, em seguida, pela comparação numérica de seus identificadores de desambiguação. Os identificadores de desambiguação seguem as regras do esquema relaxado (version).

Exemplos: 2021-01-01<2021-01-01.1<2021-02-01.1.2<2021-02-01.1.3<2021-02-01

version-string

Para pacotes que usam cadeias de caracteres de versão que não se ajustam a nenhum dos outros esquemas, ele aceita a maioria das cadeias de caracteres arbitrárias. O # que é usado para indicar versões de porta não é permitido.

Comportamento de classificação: Nenhuma tentativa de classificação é tentada na própria cadeia de caracteres de versão. No entanto, se as cadeias de caracteres corresponderem exatamente, suas versões de porta podem ser comparadas e classificadas.

Exemplos:

• apple <> orange <> orange.2 <> orange2
• watermelon#0< watermelon#1

port-version

As versões portuárias controlam as alterações nos arquivos de empacotamento (vcpkg.json, portfile.cmake, etc.) sem nenhuma alteração na versão da biblioteca upstream.

Uma versão de porta é um valor inteiro não negativo.

As regras para versões de porta são:

• Comece em 0 para a versão original da porta,
• aumentar em 1 cada vez que uma alteração específica do vcpkg é feita na porta que não aumenta a versão do pacote,
• e redefinir para 0 cada vez que a versão do pacote é atualizada.

Comportamento de classificação: Se duas versões forem comparadas igualmente, suas versões de porta serão comparadas por seu valor numérico, as versões de porta inferior terão precedência.

Exemplos:

• 1.2.0 < 1.2.0#1 < 1.2.0#2 < 1.2.0#10
• 2021-01-01#20 < 2021-01-01.1
• windows#7 < windows#8

Restrições de versão

Bases de referência

As linhas de base definem um piso de versão global para quais versões serão consideradas (a menos que especificado em outro lugar, a versão associada a essa linha de base será usada). Isso permite que os manifestos de nível superior mantenham todo o gráfico de dependências up-toatualizado sem a necessidade de especificar individualmente restrições de "version>=" diretas.

Cada registro configurado tem uma linha de base associada. Para manifestos que não configuram nenhum registro, o campo "builtin-baseline" define a linha de base para o registro interno. Se um manifesto não configurar nenhum registro e não tiver um "builtin-baseline", a instalação operará de acordo com o algoritmo do modo Clássico e ignorará todas as informações de controle de versão.

As linhas de base, como outras configurações do Registro, são ignoradas das portas consumidas como dependência. Se for necessária uma versão mínima durante a resolução da versão transitiva, a porta deverá utilizar "version>=".

Exemplo

{
  "name": "project",
  "version": "1.0.0",
  "dependencies": ["zlib", "fmt"],
  "builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
}

Para adicionar um "builtin-baseline"inicial , use vcpkg x-update-baseline --add-initial-baseline. Para atualizar as linhas de base em um manifesto, use vcpkg x-update-baseline.

version>=

Expressa um requisito de versão mínima, version>= declarações colocam um limite inferior nas versões que podem ser usadas para satisfazer uma dependência.

Exemplo:

{
  "name": "project",
  "version-semver": "1.0.0",
  "dependencies": [
    { "name": "zlib", "version>=": "1.2.11#9" },
    { "name": "fmt", "version>=": "7.1.3#1" }
  ],
  "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc"
}

Como parte de uma declaração de restrição de versão, uma versão de porta pode ser especificada adicionando o sufixo #<port-version>, no exemplo anterior 1.2.11#9 se refere à versão 1.2.11 à versão da porta 9.

overrides

Declarar uma substituição força vcpkg a ignorar todas as outras restrições de versão e usar a versão especificada na substituição. Isso é útil para fixar versões exatas e para resolver conflitos de versão.

As substituições são declaradas como uma matriz de declarações de versão do pacote.

Para que uma substituição entre em vigor, o pacote substituído deve fazer parte do gráfico de dependência. Isso significa que uma dependência deve ser declarada pelo manifesto de nível superior ou fazer parte de uma dependência transitiva.

Apenas uma substituição pode ser declarada para um determinado nome.

{
  "name": "project",
  "version-semver": "1.0.0",
  "dependencies": [
    "curl",
    { "name": "zlib", "version>=": "1.2.11#9" },
    "fmt"
  ],
  "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc",
  "overrides": [
    { "name": "fmt", "version": "6.0.0" },
    { "name": "openssl", "version": "1.1.1h#3" }
  ]
}