Guida alla risoluzione dei problemi di controllo delle versioni

Questa guida è destinata agli utenti che riscontrano problemi con la versione di gestione delle versioni.

Controllo del file di versione per una porta

Per esaminare il database delle versioni di una porta specifica:

1. Passare alla directory vcpkg/versions.
2. Individuare la cartella della porta:
   • Trovare la cartella corrispondente alla prima lettera della porta. Ad esempio, per fmt aprire la cartella denominata f-.
3. Aprire il file di versione delle porte:
   • Individuare il file JSON con lo stesso nome della porta. Ad esempio, il file delle versioni di fmt è denominato fmt.json.

Il file della versione della porta contiene un elenco di versioni disponibili con dettagli come i tag di versione e i corrispondenti hash dell'albero di oggetti Git. Queste informazioni sono necessarie da vcpkg per recuperare versioni di porta specifiche. Solo le versioni contenute in questo elenco sono disponibili per l'uso nei file manifesto.

Per altre informazioni sul controllo delle versioni, vedere la documentazione di riferimento:

• concetti di controllo delle versioni
• di controllo delle versioni

Per altre informazioni sull'uso di un manifesto, vedere manifesto

Causa: richiesta di una versione non esistente di un pacchetto

Quando non esiste una versione specificata nel file manifesto nel database della versione vcpkg, vcpkg non riesce a risolvere la dipendenza e genera un messaggio di errore simile al seguente:

error: no version database entry for fmt at 100.0.0
Available versions:
  10.1.1
  10.1.0
  10.0.0
  9.1.0#1
  9.1.0
  9.0.0
  8.1.1#2
  8.1.1#1
  ...
See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

Per risolvere il problema:

1. Aggiornare il database delle versioni:
   • La versione desiderata potrebbe non trovarsi nella copia locale del database delle versioni. In tal caso, eseguire il comando git pull per aggiornare il registro vcpkg al commit più recente.
2. Controllare le versioni disponibili:
   • Scegliere una delle versioni disponibili nel database delle versioni.
3. Aggiornare il file manifesto:
   • Modificare il file vcpkg.json.
   • Modificare la versione specificata in una versione disponibile nel repository vcpkg. Ad esempio, passare da "version>=": "100.0.0" a "version>=": "10.1.1".
4. Eseguire vcpkg install:
   • Eseguire di nuovo il comando vcpkg install nel terminale o nel prompt dei comandi.

Causa: specificazione del vincolo di versione tra schemi diversi

Un conflitto dello schema di versione si verifica quando la versione specificata nel file di vcpkg.json per una dipendenza usa uno schema di controllo delle versioni diverso da quello usato nella versione di base del repository vcpkg. Questo comporta un errore perché vcpkg non può confrontare le versioni tra schemi diversi.

Se un vincolo version>= dichiarato usa uno schema di versione diverso da quello usato nella versione di base, vcpkg non è in grado di determinare quale versione è maggiore o uguale all'altra.

Ad esempio, se si specifica:

{
  "dependencies": [
    {
      "name": "boost-regex",
      "version>=": "1.75.0"
    }
  ]
}

vcpkg restituisce il messaggio di errore seguente:

error: version conflict on boost-regex:x64-windows:  required 1.75.0, which cannot be compared with the baseline version 1.83.0.

The versions have incomparable schemes:
  boost-regex@1.83.0 has scheme relaxed
  boost-regex@1.75.0 has scheme string

This can be resolved by adding an explicit override to the preferred version. For example:

  "overrides": [
    { "name": "boost-regex", "version": "1.83.0" }
  ]

See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

Risoluzioni

1. Usare uno schema di versione compatibile:
   • Esaminare il database delle versioni nel repository vcpkg in versions/b-/boost-regex.json per trovare una versione di boost-regex che usa lo stesso schema di controllo delle versioni della baseline.
   • Aggiornare il vincolo version>= nel vcpkg.json a una versione che usa uno schema compatibile.
2. Sostituire con la versione desiderata:
   • Se è necessaria una versione specifica di boost-regex che usa uno schema di controllo delle versioni diverso, è possibile eseguirne l'override nel manifesto.
   • Modificare il vcpkg.json per includere una sezione override specificando la versione desiderata:

   {
     "dependencies": [
       { "name": "boost-regex" }
     ],
     "overrides": [
       { "name": "boost-regex", "version": "1.75.0" }
     ]
   }
   

Causa: cronologia commit inadeguata nel clone superficiale

Quando vcpkg viene clonato con una cronologia di commit limitata (clone superficiale), manca la cronologia di commit necessaria per risolvere specifici vincoli di versione o linee di base. Gli hash dell'oggetto albero Git usati da vcpkg per recuperare versioni specifiche delle porte sono disponibili solo quando viene estratta la cronologia completa del commit. vcpkg rileva quando è stato clonato in un repository superficiale e genera un messaggio di errore quando non riesce a recuperare una versione della porta.

Ad esempio, usando un vcpkg.json con una baseline specifica simile alla seguente:

{
  "dependencies": [
    {
      "name": "fmt"
    }
  ],
  "overrides": [
    {
      "name": "fmt",
      "version": "7.1.3#1"
    }
  ],
  "builtin-baseline": "bb588985e37484d543fc849d0d79434e0d45bb3c"
}

Verrà generato l'errore seguente:

error: failed to execute: "C:\Program Files\Git\cmd\git.exe" "--git-dir=C:\dev\demo\vcpkg\.git" "--work-tree=C:\dev\demo\vcpkg\buildtrees\versioning_\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72_26648.tmp" -c core.autocrlf=false read-tree -m -u 4f8427eb0bd40da1856d4e67bde39a4fda689d72
vcpkg was cloned as a shallow repository in: C:\dev\demo\vcpkg\.git
Try again with a full vcpkg clone.
error: git failed with exit code: (128).
fatal: failed to unpack tree object 4f8427eb0bd40da1856d4e67bde39a4fda689d72
note: while checking out port fmt with git tree 4f8427eb0bd40da1856d4e67bde39a4fda689d72

Questo errore indica che il commit (4f8427eb0bd40da1856d4e67bde39a4fda689d72) necessario per la versione specifica del pacchetto fmt non è disponibile nel clone superficiale.

Risoluzioni:

1. Convertire in un clone completo

   • La soluzione più semplice a questo problema consiste nel convertire in clone completo:

   git fetch --unshallow
   

2. Uso di GitHub Actions (cloni superficiali predefiniti)

   • GitHub Actions predefinisce spesso cloni superficiali. Per risolvere questo problema, è possibile modificare il flusso di lavoro di GitHub Actions per eseguire un clone completo. Aggiungere il passaggio seguente prima di usare vcpkg:

   - name: Convert to Full Clone
     run: git fetch --unshallow
   

Causa: inclusione imprevista delle funzionalità predefinite nelle dipendenze transitive

Quando si gestiscono le dipendenze con vcpkg, è possibile che le dipendenze transitive siano installate con le relative funzionalità predefinite, anche quando potrebbero non essere necessarie per tali funzionalità per il progetto. Questa situazione può causare un bloat o una funzionalità imprevista nella compilazione finale.

Scenario

Si ha una dipendenza dalla libreria Y, che a sua volta dipende dalla libreria X. La libreria X include funzionalità predefinite, tra cui foo, che si vuole escludere dal progetto. Il manifesto di primo livello per la libreria Y potrebbe essere simile al seguente:

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"],
      "default-features": false
    }
  ]
}

Si prevede che X verrà installato senza le relative funzionalità predefinite a causa dell'impostazione "default-features": false. Tuttavia, X è ancora installato con la funzionalità predefinita foo.

Ragione

La proprietà default-features viene considerata solo nel manifesto di livello superiore. Ciò significa che le funzionalità predefinite delle dipendenze transitive (ad esempio X in questo scenario) sono ancora incluse a meno che non siano disabilitate in modo esplicito al livello superiore. Quando la libreria Y viene risolta, vcpkg non propaga l'impostazione di "default-features": false alla dipendenza transitiva X, con conseguente installazione di X con le relative funzionalità predefinite.

Risoluzione

Per assicurarsi che le dipendenze transitive come X siano installate senza le relative funzionalità predefinite, è necessario alzarle di livello in modo da indirizzare le dipendenze nel manifesto di primo livello e disabilitare in modo esplicito le funzionalità predefinite. Modificare il vcpkg.json in modo da includere X direttamente con "default-features": false:

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"]
    },
    {
      "name": "X",
      "default-features": false
    }
  ]
}

Questo approccio garantisce che X sia installato senza le funzionalità predefinite, perché ora X è una dipendenza diretta con un'istruzione esplicita per escludere le funzionalità predefinite.

Per informazioni più dettagliate sul funzionamento delle funzionalità predefinite e su come gestirle, vedere l'articolo concetto di funzionalità predefinite.For more detailed information on how default features work and how to manage them, see the default features concept article article.

Il problema non è elencato qui

Se il problema non è elencato qui, visitare repository per creare un nuovo problema.