Condividi tramite

Creazione di registri

  • Articolo

Per informazioni sull'utilizzo dei registri, vedere Uso di registri.

Panoramica

I registri sono raccolte di porte e le relative versioni. Esistono due opzioni principali di implementazione per i registri, se si vuole creare registri Git personalizzati e registri di file system.

I registri Git sono semplici repository Git e possono essere condivisi pubblicamente o privatamente tramite meccanismi normali per i repository Git. Il repository vcpkg, ad esempio, è un registro Git.

I registri del file system sono progettati come più di un terreno di test. Dato che vivono letteralmente nel file system, l'unico modo per condividerli è tramite directory condivise. Tuttavia, i registri del file system possono essere utili come modo per rappresentare i registri contenuti in sistemi di controllo della versione non Git, presupponendo che sia possibile ottenere il Registro di sistema sul disco.

Ci aspettiamo che il set di tipi di registro cresca nel tempo; se si vuole il supporto per i registri compilati nel sistema di controllo della versione pubblica preferito, non esitare ad aprire una richiesta pull.

La struttura di base di un registro è:

  • Set di versioni considerate "più recenti" in determinati momenti della cronologia, note come "baseline".
  • Set di tutte le versioni di tutte le porte e dove trovare ognuna di queste nel Registro di sistema.

Registri Git

Come si segue insieme a questa documentazione, può essere utile avere un esempio funzionante a cui fare riferimento. Ne abbiamo scritto uno e metterlo qui:

Microsoft/vcpkg-docs: registro vcpkg.

Tutti i registri Git devono avere un versions/baseline.json file. Questo file contiene il set di "versioni più recenti" in un determinato commit. È disposto come oggetto di primo livello contenente solo il "default" campo. Questo campo deve contenere i nomi delle porte di mapping degli oggetti alla versione attualmente più recente.

Di seguito è riportato un esempio di baseline.json valido:

{
  "default": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

La versions directory contiene tutte le informazioni sulle versioni di cui sono contenuti i pacchetti nel Registro di sistema, insieme alla posizione in cui vengono archiviate tali versioni. Il resto del Registro di sistema funge semplicemente da archivio di backup, per quanto riguarda vcpkg: solo gli elementi all'interno della versions directory verranno usati per indirizzare il modo in cui il registro viene visualizzato da vcpkg.

Ogni porta in un registro deve esistere nella directory delle versioni come <first letter of port>-/<name of port>.json; in altre parole, le informazioni sulla kitten porta si trovano in versions/k-/kitten.json. Deve trattarsi di un oggetto di primo livello con un solo campo: "versions". Questo campo deve contenere una matrice di oggetti versione:

  • La versione della porta in questione; deve essere esattamente lo stesso del vcpkg.json file, inclusi i campi della versione e "port-version".
  • Il "git-tree" campo, ovvero un albero Git, ovvero ciò che si ottiene quando si scrive git rev-parse COMMIT-ID:path/to/port.

Il campo della versione per le porte con file deprecati CONTROL è "version-string".

Avviso

Una parte molto importante dei registri è che le versioni non devono mai essere modificate. L'aggiornamento a un riferimento successivo non deve mai rimuovere o modificare una versione esistente. Deve essere sempre sicuro aggiornare un registro.

Di seguito è riportato un esempio di database di versione valido per una kitten porta con una versione:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

In generale, non è importante posizionare le directory delle porte. Tuttavia, il linguaggio in vcpkg consiste nel seguire le operazioni del Registro di sistema vcpkg predefinito: la kitten porta deve essere inserita in ports/kitten.

Avviso

Un altro aspetto da tenere presente è che quando si aggiorna un Registro di sistema, anche tutte le versioni precedenti devono essere accessibili. Poiché l'utente imposta la linea di base su un ID commit, tale ID commit deve sempre esistere ed essere accessibile dal commit HEAD, ovvero ciò che viene effettivamente recuperato. Ciò significa che il commit HEAD deve essere figlio di tutti i commit HEAD precedenti.

Registri predefiniti

I registri predefiniti vengono considerati come registri Git speciali. Anziché recuperare da un URL remoto, i registri compilati consultano la $VCPKG_ROOT/.git directory del clone vcpkg. Usano la directory attualmente estratta $VCPKG_ROOT/versions come origine per le informazioni sul controllo delle versioni.

Aggiunta di una nuova versione

La creazione di una nuova versione di una porta comporta alcune operazioni di trucco git. La prima cosa da fare è apportare alcune modifiche, aggiornare il "port-version" campo della versione regolare e in base alle esigenze e quindi testare con overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten.

Dopo aver completato il test, è necessario assicurarsi che la directory così come si trovi in purview di Git. A tale scopo, si creerà un commit temporaneo:

> git add ports/kitten
> git commit -m 'temporary commit'

Ottenere quindi l'ID albero Git della directory:

> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07

È quindi possibile aggiungere questa versione al database delle versioni. Nella parte superiore di versions/k-/kitten.jsonè possibile aggiungere (presupponendo che si stia aggiungendo la versione 2.6.3#0):

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

Sarà quindi necessario modificare anche versions/baseline.json con la nuova versione:

{
  "default": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

e modificare il commit corrente:

> git commit --amend

poi condividere via!

Registri del file system

Come si segue insieme a questa documentazione, può essere utile avere un esempio funzionante a cui fare riferimento. Ne abbiamo scritto uno e metterlo qui:

Registro di sistema di file system di esempio.

Tutti i registri del file system devono avere un versions/baseline.json file. Questo file contiene il set di "versioni più recenti" per una determinata versione del Registro di sistema. È disposto come oggetto di primo livello contenente una mappa dal nome della versione agli "oggetti di base", che eseguono il mapping dei nomi delle porte alla versione considerata "più recente" per tale versione del Registro di sistema.

I registri del file system devono decidere uno schema di controllo delle versioni. A differenza dei registri Git, che hanno lo schema di controllo delle versioni implicito dei riferimenti, i registri del file system non possono basarsi sul sistema di controllo della versione qui. Una possibile opzione consiste nell'eseguire una versione giornaliera e fare in modo che le "versioni" siano date.

Avviso

Una baseline non deve essere modificata dopo la pubblicazione. Se si desidera modificare o aggiornare le versioni, è necessario creare una nuova baseline nel baseline.json file.

Di seguito è riportato un esempio di , valido baseline.jsonper un registro che ha deciso le date per le versioni:

{
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

La versions directory contiene tutte le informazioni sulle versioni di cui sono contenuti i pacchetti nel Registro di sistema, insieme alla posizione in cui vengono archiviate tali versioni. Il resto del Registro di sistema funge semplicemente da archivio di backup, per quanto riguarda vcpkg: solo gli elementi all'interno della versions directory verranno usati per indirizzare il modo in cui il registro viene visualizzato da vcpkg.

Ogni porta in un registro deve esistere nella directory delle versioni come <first letter of port>-/<name of port>.json; in altre parole, le informazioni sulla kitten porta si trovano in versions/k-/kitten.json. Deve trattarsi di un oggetto di primo livello con un solo campo: "versions". Questo campo deve contenere una matrice di oggetti versione:

  • La versione della porta in questione; deve essere esattamente lo stesso del vcpkg.json file, inclusi i campi della versione e "port-version".
  • Il "path" campo: una directory relativa, rooted alla base del Registro di sistema (in altre parole, la directory in cui versions si trova), nella directory della porta. Dovrebbe essere simile "$/path/to/port/dira "

Il campo della versione per le porte con file deprecati CONTROL è "version-string".

In generale, non è importante posizionare le directory delle porte. Tuttavia, il linguaggio in vcpkg consiste nel seguire da vicino ciò che il registro vcpkg predefinito fa: la kitten porta alla versione x.y.z deve essere inserita in ports/kitten/x.y.z, con le versioni delle porte aggiunte come si può vedere (anche se # non è un buon carattere da usare per i nomi di file, forse usare _).

Avviso

Una parte molto importante dei registri è che le versioni non devono mai essere modificate. Uno non deve mai rimuovere o modificare una versione esistente. Le modifiche apportate al Registro di sistema non devono modificare il comportamento degli utenti downstream.

Di seguito è riportato un esempio di database di versione valido per una kitten porta con una versione:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Aggiungere una nuova versione

A differenza dei registri Git, l'aggiunta di una nuova versione a un registro di file system comporta principalmente molte operazioni di copia. La prima cosa da fare è copiare la versione più recente della porta in una nuova directory della versione, aggiornare la versione e "port-version" i campi necessari e quindi testare con overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten/new-version.

Al termine del test, è possibile aggiungere questa nuova versione all'inizio di versions/k-/kitten.json:

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.3_0"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Si vuole quindi modificare anche versions/baseline.json con la nuova versione (ricordarsi di non modificare le linee di base esistenti):

{
  "2021-04-17": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

L'operazione è così completata.