Guida alla risoluzione dei problemi di controllo delle versioni

Questa guida è destinata agli utenti che riscontrano problemi con il controllo 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 fmt file delle versioni è denominato fmt.json.

Il file di versione della porta contiene un elenco di versioni disponibili con dettagli come i tag di versione e l'hash dell'oggetto albero Git corrispondente. 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 relativi al controllo delle versioni
• Versioning

Per altri dettagli sull'uso di un manifesto, vedere manifest

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 git pull comando 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 vcpkg.json file.
   • 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 vcpkg install comando nel terminale o nel prompt dei comandi.

Causa: specifica del vincolo di versione tra schemi diversi

Un conflitto dello schema di versione si verifica quando la versione specificata nel vcpkg.json file 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 dichiarato version>= 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 versions/b-/boost-regex.json vcpkg in per trovare una versione di che usa lo stesso schema di boost-regex controllo delle versioni della baseline.
   • Aggiornare il version>= vincolo in vcpkg.json una versione che usa uno schema compatibile.
2. Eseguire l'override alla 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.
   • vcpkg.json Modificare per includere una sezione delle sostituzioni 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 oggetto con una linea di base 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 è spesso usato per impostazione predefinita per 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à foopredefinita .

Motivo

La default-features proprietà viene considerata solo nel manifesto di primo livello. Ciò significa che le funzionalità predefinite delle dipendenze transitive (come 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 "default-features": false alla dipendenza Xtransitiva, con conseguente installazione di X con le funzionalità predefinite.

Risoluzione

Per assicurarsi che le dipendenze transitive come X siano installate senza le relative funzionalità predefinite, è necessario promuoverle in modo da indirizzare le dipendenze nel manifesto di primo livello e disabilitare in modo esplicito le funzionalità predefinite. Modificare in vcpkg.json 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 l'installazione X senza le funzionalità predefinite, come 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 relativo al concetto di funzionalità predefinito.

Il problema non è elencato qui

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