Condividi tramite

Concetti relativi ai registri

  • Articolo

Panoramica

vcpkg ospita una selezione di librerie confezionate nei porti a https://github.com/Microsoft/vcpkg. Questa raccolta di porte è chiamata registro curato . Tuttavia, vcpkg non è limitato al registro curato. Gli utenti possono estendere la selezione delle porte creando registri personalizzati.

Un registro è una raccolta di porte e file helper disposti in una struttura specifica. Seguendo la struttura del Registro di sistema, le porte contenute in un Registro di sistema possono essere installate con le stesse funzionalità (controllo delle versioni, memorizzazione nella cache binaria) offerte alle porte nel Registro di sistema curato.

Esistono attualmente tre tipi di registri:

È possibile invitare vcpkg a considerare le porte disponibili nei registri personalizzati usando un file vcpkg-configuration.json. Vedere l'articolo Tutorial: Install a dependency from a Git-based registry (Esercitazione sull'installazione di una dipendenza da un registro basato su Git) per un'esercitazione su come usare registri personalizzati nei progetti.

Struttura del Registro di sistema

Affinché vcpkg si interfaccia con un registro, deve essere conforme alla struttura seguente:

  • Una directory denominata ports contiene la raccolta di porte, con ogni sottodirectory contenente una porta specifica corrispondente al nome della sottodirectory. Ad esempio, i file per la porta foo si trovano in ports/foo.
  • Una directory denominata versions contiene i file che comprendono il database delle versioni .

Esempio: struttura del Registro di sistema

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

Database delle versioni

Tutti i registri contengono una directory versions nella radice del Registro di sistema che contiene il database versioni.

Esistono due componenti per il database delle versioni:

  • File di base
  • File di versione

Il file di base è un file JSON denominato baseline.json che si trova nella radice della directory versions.

I file delle versioni sono file JSON con gli stessi nomi delle porte disponibili. Devono esistere in versions/<prefix>/<port name>.json, dove <prefix> è la prima lettera del nome della porta seguita da un trattino. Ad esempio, il file delle versioni per la porta foo deve trovarsi in versions/f-/foo.json.

Lo scopo del file delle versioni è duplice:

  • Elencare tutte le versioni disponibili di ogni porta
  • Indicare le posizioni di recupero di ogni versione.

Il formato del file di versione dipende dal tipo di registro.

File di riferimento

Tutti i registri, indipendentemente dal tipo, devono contenere un file denominato baseline.json che si trova in versions/baseline.json.

Lo scopo del file di base è descrivere il set di versioni considerate più recenti per tutte le porte nel Registro di sistema. È previsto che questo file venga aggiornato ogni volta che viene aggiunta una nuova versione di una porta al Registro di sistema.

Il file è un file JSON composto da un singolo oggetto le cui proprietà sono denominate oggetti baseline. Le proprietà di ogni oggetto di base sono nomi di porta, i cui valori sono voci di versione. L'articolo dei registri descrive più nel dettaglio il layout dei file di base.

Ogni voce della versione di base è un oggetto con le proprietà seguenti:

  • baseline: il valore è la versione della porta corrispondente al file vcpkg.json corrispondente.
  • port-version: il valore è il port-version della porta corrispondente al file di vcpkg.json corrispondente.

File di base di esempio

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

Vedere la documentazione di riferimento per:

File di versioni

Ogni porta nel Registro di sistema ha un file di versioni corrispondente. I file delle versioni vengono archiviati in versions/<prefix>/<port name>.json , dove <prefix> è la prima lettera del nome della porta seguita da un trattino. Ad esempio, il file delle versioni per la porta foo si trova in versions/f-/foo.json.

Lo scopo del file delle versioni è duplice:

  • Elencare tutte le versioni disponibili di ogni porta
  • Indicare le posizioni di recupero di ognuna di queste versioni

Il layout del file delle versioni è un oggetto contenente una matrice di "versions", con ogni voce della matrice che rappresenta un oggetto versione. Un oggetto version deve contenere le proprietà seguenti:

  • Proprietà della versione: la chiave e il valore della proprietà devono corrispondere a quelli usati dalla porta nel relativo file vcpkg.json. La chiave deve essere una delle version, version-semver, version-dateo version-string; il valore deve essere la versione visualizzata nel file manifesto della porta (vcpkg.json).
  • port-version: il valore è il port-version della porta come viene visualizzato nel file di vcpkg.json della porta.
  • git-tree: (solo nei registri Git) il valore è il git-tree SHA corrispondente alla directory della porta. Si tratta di uno SHA calcolato eseguendo l'hashing del contenuto della directory della porta; Questo file GIT-tree SHA può essere usato da Git per recuperare il contenuto della porta corrispondente all'albero Git fornito. Ciò consente a vcpkg di recuperare le versioni precedenti delle porte dalla cronologia Git dei registri. Leggere la sezione registri Git per informazioni su come ottenere questo valore per qualsiasi versione di porta.
  • path: (solo nei registri del file system) il valore è il percorso completo di una directory contenente i file di porta per la versione specifica.

Esempio di file di versione del registro del filesystem

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Vedere la documentazione di riferimento per:

  • Layout dei file delle versioni per i registri Git
  • Layout delle versioni dei file per i registri del filesystem

Registro di sistema predefinito

Il registro integrato è un tipo speciale di registro. È il Registro di sistema predefinito usato in modalità classica. In modalità manifesto, quando un Registro di sistema predefinito non viene specificato, vcpkg utilizza implicitamente il registro integrato.

Il Registro di sistema predefinito fa riferimento alla copia locale del Registro di sistema curato creata quando si git clone il repository vcpkg da https://github.com/Microsoft/vcpkg. Alcune operazioni prevedono che la variabile di ambiente VCPKG_ROOT punti a un registro predefinito.

Se vcpkg viene acquisito tramite il programma di installazione "one liner" o Visual Studio, il Registro di sistema predefinito diventa equivalente a un registro Git che punta al repository https://github.com/Microsoft/vcpkg.

Registri Git

Un registro Git è un repository che segue la struttura del Registro di sistema e sfrutta le funzionalità di Git per fornire il controllo delle versioni per le porte nel Registro di sistema. Il Registro di sistema curato in https://github.com/Microsoft/vcpkg è un'implementazione di un registro Git.

I registri Git possono essere ospitati in qualsiasi provider di repository Git, consentendo di usare il servizio di hosting Git scelto per controllare l'accesso al registro personalizzato, semplificando al contempo la condivisione del registro.

I registri Git sono il metodo consigliato per l'implementazione di un registro personalizzato. Poiché il meccanismo di controllo delle versioni è lo stesso usato dal Registro di sistema curato, i registri Git possono usare il x-add-version per gestire i file di database delle versioni.

Vedere il riferimento per i registri Git per i dettagli sull'implementazione dei registri.

Aggiunta di una nuova versione a un registro Git

Il comando x-add-version può essere usato per aggiungere una nuova porta o una nuova versione al Registro di sistema. Quando si aggiungono versioni usando questo comando, è necessario tenere presenti alcuni aspetti:

Importante

Quando si aggiunge una nuova versione, ricordarsi sempre di aggiornare la versione dichiarata della porta a una non già pubblicata, per evitare di riscrivere la cronologia delle versioni.

Quando si apportano modifiche a una porta, il primo passaggio consiste nell'aumentare la versione nel file di vcpkg.json. Se le modifiche includono un aggiornamento alla versione di upstream del pacchetto, ricordarsi di impostare il port-version su 0; in caso contrario, ricordarsi di aumentare il port-version di uno.

Il comando x-add-version richiede il commit di tutte le modifiche alla porta nel repository prima di aggiornare il database della versione.

Esempio: aggiunta di una nuova versione della porta a un registro Git

git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json

Le opzioni di reindirizzamento --x-builtin-ports-root e --x-builtin-registry-versions-dir devono puntare rispettivamente alle directory ports e versions del Registro di sistema.

Dopo l'esecuzione del comando x-add-version, modificare l'ultimo commit in modo da includere le modifiche apportate ai file delle versioni.

git commit --amend -m "Update foo to new version"

Registri del file system

I registri del file system sono un'implementazione di un registro che si trova in un file system. Seguono la struttura comune del Registro di sistema, ma non usano Git per offrire funzionalità di controllo delle versioni. Usano invece una forma primitiva di controllo della versione usando un percorso distinto per ogni versione delle porte.

Questo tipo di registro è adatto come ambiente di prova per le port o per fornire un'alternativa a un registro in un sistema di controllo delle versioni non Git. I registri del file system non sono consigliati per una raccolta di porte di grandi dimensioni e non viene fornito alcuno strumento per modificare i file di database di versione per questo tipo di registro.

Per informazioni dettagliate su come implementare un registro di file system, vedere le informazioni di riferimento sui registri .

Utilizzare registri

Per utilizzare un registro personalizzato nel progetto, è necessario creare un file di configurazione (vcpkg-configuration.json) accanto al file manifesto del progetto (vcpkg.json).

Registro predefinito

Quando risoluzione dei nomi delle porte, il Registro di sistema predefinito funziona come fallback quando il nome di una porta non corrisponde ad alcuno dei modelli di pacchetto dichiarati da altri registri nella matrice registries.

Per praticità per gli utenti che non interagiscono con registri personalizzati, vcpkg aggiunge in modo implicito il registro predefinito come registro predefinito. Per modificare questo comportamento, il Registro di sistema predefinito può essere impostato su qualsiasi registro o disabilitato completamente usando il La proprietà default-registry.

Esempio: Impostare un registro personalizzato come predefinito

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

Esempio: Disabilitare il Registro di sistema predefinito

vcpkg-configuration.json

{
  "default-registry": null
}

Matrice registri

Per estendere la selezione delle porte disponibili per l'installazione con vcpkg, è possibile specificare registri aggiuntivi usando la matrice registries.

Esempio: Aggiungere registri personalizzati alla configurazione

Nota

A seconda del tipo di Registro di sistema, potrebbe essere necessario fornire informazioni diverse nella matrice di registries. Consulta il riferimento vcpkg-configurtion.json per sapere quali proprietà sono necessarie per ogni tipo di registro.

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://my.privateregistry.git",
      "baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
      "packages": [ "foo" ]
    },
    {
      "kind": "filesystem",
      "path": "C:/path/to/registry",
      "baseline": "baseline1",
      "packages": [ "bar" ]
    }
  ]
}

Non riscrivere la cronologia delle versioni

Dopo che una versione è stata pubblicata nei file delle versioni, non modificare il git-tree associato in un registro Git o in una directory in un registro di file system.

Uno dei principi di progettazione di vcpkg è che le versioni delle dipendenze installate non cambiano senza l'intervento dell'utente. La riscrittura della cronologia dei file delle versioni modificando una voce git-tree viola questo principio.

Se la versione esistente presenta problemi, preferisci creare un nuovo port-version.

Non eliminare i file delle versioni

Nota

Questa sezione si applica solo ai registri Git

Quando si rimuove una porta dal Registro di sistema, rimuovere il contenuto dalla directory ports e la relativa voce nel file di base. Ma non rimuovere il file delle versioni associate.

Anche se una porta non esiste più nel Registro di sistema, purché rimanga il file delle versioni, gli utenti della porta possono installare le versioni precedenti usando versione overrides.

Passaggi successivi

Ecco alcune attività da provare: