Referência de controle de versão
O controle de versão permite controlar deterministicamente as revisões precisas das dependências usadas pelo projeto de dentro do arquivo de manifesto. O controle de versão só está disponível para modo manifesto usuários.
Para obter mais informações sobre o algoritmo de controle de versão vcpkg e conceitos de alto nível, consulte conceitos de controle de versão.
Para obter um exemplo com contexto, consulte nosso guia para introdução ao controle de versão.
Esquemas de versão
As portas em vcpkg devem tentar seguir as convenções de controle de versão usadas pelos autores do pacote. Por esse motivo, ao declarar a versão de um pacote, o esquema apropriado deve ser usado.
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 controle de versão compreendidos por vcpkg são:
| Propriedade Manifest | Esquema de controle de versão |
|---|---|
version |
Para versões numéricas separadas por pontos |
version-semver |
Para versões compatíveis com SemVer |
version-date |
Para datas no formato YYYY-MM-DD |
version-string |
Para cadeias de caracteres arbitrárias |
Um manifesto deve conter apenas uma declaração de versão.
Nota
Por design, vcpkg não compara versões que usam esquemas diferentes. Por exemplo, um pacote que tem um version-string: 7.1.3 não pode ser comparado com o mesmo pacote usando version: 7.1.4, mesmo que a conversão pareça óbvia.
version
Aceita cadeias de caracteres de versão que seguem um esquema descontraído, separado por pontos e semver.
A versão é composta logicamente por seções numéricas de ponto separado (.). Cada seção deve conter um número inteiro positivo sem zeros à esquerda.
O padrão regex para este esquema de controle de versão é: (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 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, considerando 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 semânticas de controle de versão, conforme descrito na especificação de controle de versão semântica .
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 em uma data após o formato ISO-8601 YYYY-MM-DD. Identificadores de desambiguação são permitidos na forma de números inteiros separados por pontos separados, positivos e inteiros sem zeros à esquerda.
Esse é o esquema de controle de versão recomendado para bibliotecas "Live at HEAD" que não têm versões de versão estabelecidas.
O padrão regex para este esquema de controle de versão é: \d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*
comportamento de classificação: as cadeias de caracteres são classificadas primeiro pela 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 encaixam em nenhum dos outros esquemas, ele aceita a maioria das cadeias de caracteres arbitrárias. O # usado para denotar versões de porta não é permitido.
comportamento de classificação: nenhuma 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 poderão ser comparadas e classificadas.
Exemplos:
apple<>orange<>orange.2<>orange2watermelon#0<watermelon#1
port-version
As versões de porta acompanham as alterações nos arquivos de empacotamento (vcpkg.json, portfile.cmakeetc) sem alterações 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 sempre que uma alteração específica de vcpkg for feita na porta que não aumenta a versão do pacote,
- e redefinir para 0 sempre que a versão do pacote for atualizada.
Nota
vcpkg segue o formato de texto <version>#<port version>. Por exemplo, 1.2.0#2 significa versão 1.2.0 versão da porta 2. Se a versão da porta estiver 0 o sufixo #0 for omitido (por exemplo, 1.2.0 implicará versão 1.2.0 versão da porta 0).
comportamento de classificação: se duas versões forem comparadas igualmente, suas versões de porta serão comparadas pelo valor numérico, as versões de porta inferiores têm precedência.
Exemplos:
1.2.0<1.2.0#1<1.2.0#2<1.2.0#102021-01-01#20<2021-01-01.1windows#7<windows#8
Restrições de versão
Base
As linhas de base definem um piso de versão global para quais versões serão consideradas (a menos que especificadas em outro lugar, a versão associada a essa linha de base será usada). Isso permite que manifestos de nível superior mantenham todo o grafo de dependências up-to-date sem a necessidade de especificar individualmente restrições "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 funcionará de acordo com o algoritmo de 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 uma dependência. Se uma versão mínima for necessária durante a resolução de versão transitiva, a porta deverá usar "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 linhas de base em um manifesto, use vcpkg x-update-baseline.
version>=
Expressa um requisito mínimo de versão, version>= declarações colocam um limite inferior nas versões que podem ser usadas para satisfazer uma dependência.
Nota
vcpkg seleciona a versão mais baixa que corresponde a todas as restrições, portanto, uma restrição menor que não é necessária.
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 refere-se à versão 1.2.11 versão da porta 9.
overrides
Declarar uma substituição força o 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 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 grafo 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.
Somente 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" }
]
}
