Versiefoutopsporingsgids

Artikel
02/06/2025

Deze handleiding is bedoeld voor gebruikers die problemen ondervinden met versiebeheer.

Het versiebestand voor een poort controleren

Notitie

Het hieronder beschreven proces is bedoeld voor poorten uit het vcpkg-register. Raadpleeg onze documentatie voor register voor meer informatie over hoe de versiebeheerdatabase wordt geïmplementeerd in aangepaste registers.

De versiesdatabase van een specifieke poort controleren:

Navigeer naar de map vcpkg/versions.
Zoek de map van de poort:
- Zoek de map die overeenkomt met de eerste letter van de poort. Voor fmt bijvoorbeeld de map met de naam f-openen.
Open het versiebestand voor poorten:
- Zoek het JSON-bestand met dezelfde naam van de poort. Bijvoorbeeld, het versiesbestand fmt heet fmt.json.

Het versiebestand van de poort bevat een lijst met beschikbare versies met details zoals versietags en de bijbehorende Git tree-object hash. Deze informatie is vereist door vcpkg om specifieke poortversies op te halen. Alleen versies in deze lijst zijn beschikbaar voor gebruik in uw manifestbestanden.

Raadpleeg onze referentiedocumentatie voor meer informatie over versiebeheer:

Zie manifest voor meer informatie over het gebruik van een manifest

Oorzaak: Een niet-bestaande versie van een pakket aanvragen

Wanneer een versie die is opgegeven in het manifestbestand niet bestaat in de vcpkg-versiedatabase, kan vcpkg de afhankelijkheid niet oplossen en wordt er een foutbericht gegenereerd dat lijkt op het volgende:

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.

Ga als volgende te werk om het probleem op te lossen:

Werk de versiesdatabase bij:
- De gewenste versie bevindt zich mogelijk niet in uw lokale kopie van de versiedatabase. Voer in dat geval de opdracht git pull uit om het vcpkg-register bij te werken naar de meest recente commit.
Controleer de beschikbare versies:
- Kies een van de versies die beschikbaar zijn in de versiesdatabase.
Manifestbestand bijwerken:
- Bewerk het vcpkg.json bestand.
- Wijzig de opgegeven versie in een versie die beschikbaar is in de vcpkg-opslagplaats. Wijzig bijvoorbeeld van "version>=": "100.0.0" in "version>=": "10.1.1.1".
Voer vcpkg-installatie uit:
- Voer de opdracht vcpkg install opnieuw uit in de terminal of opdrachtprompt.

Oorzaak: Versiebeperkingen specificeren over verschillende schema's heen

Er treedt een versieschemaconflict op wanneer de versie die is opgegeven in het vcpkg.json-bestand voor een afhankelijkheid een ander versiebeheerschema gebruikt dan de versie die wordt gebruikt in de basislijnversie van de vcpkg-opslagplaats. Dit resulteert in een fout omdat vcpkg versies in verschillende schema's niet kan vergelijken.

Als een gedeclareerde version>= beperking een ander versieschema gebruikt dan het schema dat in de basislijnversie wordt gebruikt, kan vcpkg niet bepalen welke versie groter of gelijk is aan de andere.

Als u bijvoorbeeld het volgende opgeeft:

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

vcpkg voert het volgende foutbericht uit:

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.

Resoluties:

Gebruik een compatibel versieschema:
- Controleer de versiedatabase in de vcpkg-opslagplaats onder versions/b-/boost-regex.json om een versie van boost-regex te vinden die gebruikmaakt van hetzelfde versiebeheerschema als de basislijn.
- Werk de version>= beperking in uw vcpkg.json bij naar een versie die gebruikmaakt van een compatibel schema.
Overschrijven naar de gewenste versie:
- Als u een specifieke versie van boost-regex nodig hebt die gebruikmaakt van een ander versiebeheerschema, kunt u deze overschrijven in uw manifest.
- Wijzig uw vcpkg.json om een sectie met overschrijvingen op te nemen. Hiermee kunt u de gewenste versie specificeren.
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Oorzaak: Ontoereikende doorvoergeschiedenis in ondiepe kloon

Wanneer vcpkg wordt gekloond met een beperkte doorvoergeschiedenis (ondiepe kloon), ontbreekt de benodigde doorvoergeschiedenis om specifieke versiebeperkingen of basislijnen op te lossen. De Git tree-object-hashes die door vcpkg worden gebruikt om specifieke versies van poorten op te halen, zijn alleen beschikbaar wanneer de volledige doorvoergeschiedenis is uitgecheckt. vcpkg detecteert wanneer deze is gekloond in een ondiepe opslagplaats en produceert een foutbericht wanneer een poortversie niet kan worden opgehaald.

Als u bijvoorbeeld een vcpkg.json gebruikt met een specifieke basislijn, zoals hieronder:

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

Dit resulteert in de volgende fout:

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

Deze fout geeft aan dat de commit (4f8427eb0bd40da1856d4e67bde39a4fda689d72) die nodig is voor de specifieke versie van het pakket fmt niet beschikbaar is in de ondiepe kloon.

Resoluties:

Converteren naar een volledige kloon
- De eenvoudigste oplossing voor dit probleem is om te converteren naar een volledige kloon:
```
git fetch --unshallow
```
GitHub Actions gebruiken (standaard ondiepe klonen)
- GitHub Actions is vaak standaard ingesteld op ondiepe klonen. U kunt dit omzeilen door de Werkstroom voor GitHub Actions te wijzigen om een volledige kloon uit te voeren. Voeg de volgende stap toe voordat u vcpkg gebruikt:
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

Oorzaak: Onverwachte opname van standaardfuncties in transitieve afhankelijkheden

Wanneer u afhankelijkheden beheert met vcpkg, is het mogelijk dat transitieve afhankelijkheden zijn geïnstalleerd met hun standaardfuncties, zelfs als u deze functies mogelijk niet voor uw project wilt gebruiken. Bij de uiteindelijke build kan deze situatie leiden tot onverwacht overgewicht of nieuwe functionaliteiten.

Scenario

U hebt een afhankelijkheid van bibliotheek Y, die op zijn beurt afhankelijk is van bibliotheek X. Bibliotheek X heeft standaardfuncties, waaronder foo, die u wilt uitsluiten van uw project. Het manifest op het hoogste niveau voor bibliotheek Y er ongeveer als volgt uitziet:

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

U verwacht dat X zonder de standaardfuncties wordt geïnstalleerd vanwege de "default-features": false-instelling. X wordt echter nog steeds geïnstalleerd met de standaardfunctie foo.

Reden

De eigenschap default-features wordt alleen in het manifest op het hoogste niveau beschouwd. Dit betekent dat standaardfuncties van transitieve afhankelijkheden (zoals X in dit scenario) nog steeds worden opgenomen, tenzij deze expliciet zijn uitgeschakeld op het hoogste niveau. Wanneer bibliotheek Y is opgelost, geeft vcpkg de "default-features": false instelling niet door aan de transitieve afhankelijkheid X, wat resulteert in de installatie van X met de standaardfuncties.

Resolutie

Als u ervoor wilt zorgen dat transitieve afhankelijkheden zoals X worden geïnstalleerd zonder hun standaardfuncties, moet u ze promoveren om afhankelijkheden in uw manifest op het hoogste niveau te leiden en hun standaardfuncties expliciet uit te schakelen. Wijzig uw vcpkg.json om X direct in te voegen met "default-features": false:

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

Deze aanpak zorgt ervoor dat X wordt geïnstalleerd zonder de standaardfuncties, omdat X nu een directe afhankelijkheid is met een expliciete instructie om standaardfuncties uit te sluiten.

Zie het conceptartikel over standaardfuncties artikel voor meer informatie over hoe standaardfuncties werken en hoe u deze kunt beheren.

Het probleem wordt hier niet vermeld

Als uw probleem hier niet wordt vermeld, gaat u naar onze opslagplaats om een nieuw probleem te maken.

Delen via