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 de dentro do arquivo de manifesto. O controle de versão só está disponível para usuários do modo Manifesto.

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 de 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 essa razão, ao declarar a versão de um pacote, deve ser utilizado 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 entendidos por vcpkg são:

Propriedade de manifesto	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.

Observação

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 relaxado, separado por pontos, semelhante ao semver.

A versão é logicamente composta de 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 esse 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 por 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 se comparam 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ântica, 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ântico.

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 para uma data seguindo o formato YYYY-MM-DDISO-8601. Os identificadores de desambiguação são permitidos na forma de números inteiros separados por pontos, positivos, sem zeros à esquerda.

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

O padrão regex para esse 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 por sua parte de data e, em seguida, por 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 # que é usado para indicar 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 <> orange2
• watermelon#0< watermelon#1

port-version

As versões de porta controlam as alterações nos arquivos de empacotamento (vcpkg.json, portfile.cmake, etc.) 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 cada vez que uma alteração específica de vcpkg for feita na porta que não aumenta a versão do pacote,
• e redefina para 0 cada vez que a versão do pacote for atualizada.

Observação

vcpkg segue o formato <version>#<port version>de texto. Por exemplo1.2.0#2, significa versão 1.2.0 da porta .2 Se a versão da porta for 0 o sufixo #0 será omitido (por exemplo, 1.2.0 implica 1.2.0 a versão 0da porta ).

Comportamento de classificação: se duas versões se comparam igualmente, suas versões de porta são comparadas por seu valor numérico, as versões de porta inferior têm 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

Linhas de base

As linhas de base definem um piso de versão global para quais versões serão consideradas. Isso permite que os manifestos de nível superior mantenham todo o gráfico de dependências atualizado sem a necessidade de especificar individualmente restrições diretas "version>=" .

Cada registro configurado tem uma linha de base associada. Para manifestos que não configuram nenhum registro, o "builtin-baseline" campo 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 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 uma inicial "builtin-baseline", 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>= as declarações colocam um limite inferior nas versões que podem ser usadas para satisfazer uma dependência.

Observação

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 1.2.11#9 anterior refere-se à versão 9da porta de versão 1.2.11 .

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 de 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.

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