Informazioni di riferimento sul controllo delle versioni

Il controllo delle versioni consente di controllare in modo deterministico le revisioni precise delle dipendenze usate dal progetto dall'interno del file manifesto. Il controllo delle versioni è disponibile solo per gli utenti in modalità manifesto.

Per altre informazioni sull'algoritmo di controllo delle versioni vcpkg e sui concetti generali, vedere Concetti relativi al controllo delle versioni.

Per un esempio di contesto, vedere la guida per iniziare a usare il controllo delle versioni.

Schemi di versione

Le porte in vcpkg devono tentare di seguire le convenzioni di controllo delle versioni usate dagli autori del pacchetto. Per questo motivo, quando si dichiara la versione di un pacchetto, è necessario usare lo schema appropriato.

Ogni schema di controllo delle versioni definisce le proprie regole su ciò che è una stringa di versione valida e, soprattutto, le regole per l'ordinamento delle versioni usando lo stesso schema.

Gli schemi di controllo delle versioni riconosciuti da vcpkg sono:

Proprietà del manifesto	Schema di controllo delle versioni
version	Per le versioni numeriche separate da punti
version-semver	Per le versioni conformi a SemVer
version-date	Per le date nel formato YYYY-MM-DD
version-string	Per stringhe arbitrarie

Un manifesto deve contenere una sola dichiarazione di versione.

Nota

Per impostazione predefinita, vcpkg non confronta le versioni che usano schemi diversi. Ad esempio, un pacchetto con un oggetto version-string: 7.1.3 non può essere confrontato con lo stesso pacchetto usando version: 7.1.4, anche se la conversione sembra ovvia.

version

Accetta stringhe di versione che seguono uno schema rilassato, separato da punto e semver.

La versione è composta logicamente da sezioni numeriche separate da punti (.). Ogni sezione deve contenere un numero intero positivo senza zere iniziali.

Il modello regex per questo schema di controllo delle versioni è: (0|[1-9]\d*)(\.(0|[1-9]\d*))*

Comportamento di ordinamento: quando si confrontano due versioni, ogni sezione viene confrontata da sinistra a destra in base al valore numerico, fino a quando non viene trovata la prima differenza. Una versione con il set più piccolo di sezioni ha la precedenza su un'altra con un set più ampio di sezioni, dato che tutte le sezioni precedenti vengono confrontate equamente.

Esempio:

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

version-semver

Accetta stringhe di versione che seguono convenzioni di controllo delle versioni semantiche, come descritto nella specifica del controllo delle versioni semantica.

Comportamento di ordinamento: le stringhe vengono ordinate seguendo le regole descritte nella specifica del controllo delle versioni semantica.

Esempio:

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

version-date

Accetta stringhe di versione che possono essere analizzate in una data in base al formato YYYY-MM-DDISO-8601 . Gli identificatori di disambiguazione sono consentiti sotto forma di numeri interi separati da punti, positivi, interi senza zeri iniziali.

Si tratta dello schema di controllo delle versioni consigliato per le librerie "Live at HEAD" che non hanno versioni di rilascio stabilite.

Il modello regex per questo schema di controllo delle versioni è: \d{4}-\d{2}-\d{2}(\.(0|[1-9]\d*))*

Comportamento di ordinamento: le stringhe vengono ordinate prima in base alla parte della data, quindi in base al confronto numerico degli identificatori di ambiguità. Gli identificatori di disambiguazione seguono le regole dello schema rilassato (version).

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

version-string

Per i pacchetti che usano stringhe di versione che non rientrano in nessuno degli altri schemi, accetta la maggior parte delle stringhe arbitrarie. L'oggetto # utilizzato per indicare le versioni delle porte non è consentito.

Comportamento di ordinamento: nessun tentativo di ordinamento nella stringa di versione stessa. Tuttavia, se le stringhe corrispondono esattamente, è possibile confrontare e ordinare le versioni delle porte.

Esempi:

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

port-version

Le versioni delle porte tengono traccia delle modifiche nei file di creazione pacchetti (vcpkg.json, portfile.cmakee così via) senza apportare modifiche alla versione della libreria upstream.

Una versione della porta è un valore intero non negativo.

Le regole per le versioni delle porte sono:

• Iniziare da 0 per la versione originale della porta,
• aumentare di 1 ogni volta che viene apportata una modifica specifica di vcpkg alla porta che non aumenta la versione del pacchetto,
• e reimpostare su 0 ogni volta che viene aggiornata la versione del pacchetto.

Nota

vcpkg segue il formato <version>#<port version>di testo . Ad esempio 1.2.0#2 , indica la versione della porta della versione 1.2.02. Se la versione della porta è 0 il suffisso viene omesso ( ad esempio, 1.2.0 implica la versione della porta della versione 1.2.00).#0

Comportamento di ordinamento: se due versioni vengono confrontate equamente, le versioni delle porte vengono confrontate in base al valore numerico, le versioni delle porte inferiori hanno la precedenza.

Esempi:

• 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

Vincoli di versione

Previsioni

Le linee di base definiscono un piano di versione globale per le versioni che verranno considerate. Ciò consente ai manifesti di primo livello di mantenere aggiornato l'intero grafico delle dipendenze senza dover specificare singolarmente vincoli diretti "version>=" .

Ogni registro configurato ha una linea di base associata. Per i manifesti che non configurano registri, il "builtin-baseline" campo definisce la linea di base per il Registro di sistema predefinito. Se un manifesto non configura registri e non dispone di un "builtin-baseline", l'installazione opera in base all'algoritmo in modalità classica e ignora tutte le informazioni sul controllo delle versioni.

Le baseline, come altre impostazioni del Registro di sistema, vengono ignorate dalle porte utilizzate come dipendenza. Se è necessaria una versione minima durante la risoluzione transitiva della versione, la porta deve usare "version>=".

Esempio

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

Per aggiungere un oggetto iniziale "builtin-baseline", usare vcpkg x-update-baseline --add-initial-baseline. Per aggiornare le linee di base in un manifesto, usare vcpkg x-update-baseline.

version>=

Esprime un requisito di versione minima, version>= le dichiarazioni mettono un limite inferiore nelle versioni che possono essere usate per soddisfare una dipendenza.

Nota

vcpkg seleziona la versione più bassa che corrisponde a tutti i vincoli, quindi non è necessario un vincolo minore di.

Esempio:

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

Come parte di una dichiarazione di vincolo di versione, è possibile specificare una versione della porta aggiungendo il suffisso #<port-version>, nell'esempio 1.2.11#9 precedente si riferisce alla versione della porta della versione 1.2.119.

overrides

La dichiarazione di un override forza vcpkg a ignorare tutti gli altri vincoli di versione e usare la versione specificata nell'override. Ciò è utile per l'aggiunta di versioni esatte e per la risoluzione dei conflitti di versione.

Le sostituzioni vengono dichiarate come matrice di dichiarazioni di versione del pacchetto.

Per rendere effettivo un override, il pacchetto sottoposto a override deve far parte del grafico delle dipendenze. Ciò significa che una dipendenza deve essere dichiarata dal manifesto di primo livello o far parte di una dipendenza 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" }
  ]
}