Průvodce odstraňováním potíží s verzováním

Článek
02/06/2025

Tato příručka je určená pro uživatele, kteří mají problémy s verzováním.

Kontrola souboru verze pro port

Poznámka

Níže popsaný postup je určený pro porty z registru vcpkg. Informace o implementaci databáze správy verzí ve vlastních registrech najdete v naší dokumentaci k registru.

Kontrola verze databáze konkrétního portu:

Přejděte do adresáře vcpkg/versions.
Vyhledejte složku portu:
- Najděte složku odpovídající prvnímu písmenu portu. Například pro fmt otevřít složku s názvem f-.
Otevřete soubor verze portů:
- Vyhledejte soubor JSON se stejným názvem portu. Například soubor fmt verze má název fmt.json.

Soubor verze portu obsahuje seznam dostupných verzí s podrobnostmi, jako jsou značky verzí a jejich odpovídající hash objektu stromové struktury Git. Tyto informace vyžaduje vcpkg k načtení konkrétních verzí portů. V souborech manifestu jsou k dispozici pouze verze obsažené v tomto seznamu.

Další podrobnosti o správě verzí najdete v referenční dokumentaci:

koncepty správy verzí
verzování

Další podrobnosti o použití manifestu najdete viz manifest

Příčina: Vyžádání neexistující verze balíčku

Pokud verze zadaná v souboru manifestu v databázi verze vcpkg neexistuje, vcpkg nevyřeší závislost a vytvoří chybovou zprávu, která bude podobná následujícímu:

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.

Řešení tohoto problému:

Aktualizujte databázi verzí:
- Požadovaná verze nemusí být v místní kopii databáze verzí. V takovém případě spuštěním příkazu git pull aktualizujte registr vcpkg na nejnovější potvrzení.
Zkontrolujte dostupné verze:
- Zvolte jednu z verzí dostupných v databázi verzí.
Aktualizovat soubor manifestu:
- Upravte soubor vcpkg.json.
- Změňte zadanou verzi na verzi dostupnou v úložišti vcpkg. Například změňte z "version>=": "100.0.0" na "version>=": "10.1.1".
Spusťte příkaz vcpkg install:
- V terminálu nebo příkazovém řádku spusťte příkaz vcpkg install znovu.

Příčina: Určení omezení verze napříč různými schématy

Ke konfliktu schématu verzí dochází v případě, že verze zadaná v souboru vcpkg.json pro závislost používá jiné schéma správy verzí než schéma používané v základní verzi úložiště vcpkg. Výsledkem je chyba, protože vcpkg nemůže porovnat verze v různých schématech.

Pokud deklarované omezení version>= používá jiné schéma verzí než schéma použité v základní verzi, vcpkg nemůže určit, která verze je větší nebo rovna druhé.

Pokud například zadáte:

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

vcpkg zobrazí následující chybovou zprávu:

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.

Rezoluce:

Použijte kompatibilní schéma verzí:
- Zkontrolujte databázi verzí v úložišti vcpkg v versions/b-/boost-regex.json a vyhledejte verzi boost-regex, která používá stejné schéma správy verzí jako základní hodnoty.
- Aktualizujte omezení version>= ve vašem vcpkg.json na verzi, která používá kompatibilní schéma.
Přepsat na požadovanou verzi:
- Pokud potřebujete konkrétní verzi boost-regex, která používá jiné schéma správy verzí, můžete ji v manifestu přepsat.
- Upravte vcpkg.json tak, aby obsahoval oddíl přepsání určující požadovanou verzi:
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Příčina: Nedostatečná historie potvrzení v mělkém klonu

Při klonování vcpkg s omezenou historií příkazů (mělký klon), chybí nezbytná historie příkazů k vyřešení konkrétních verzních omezení nebo základních linek. Hodnoty hash stromového objektu Gitu používané nástrojem vcpkg k načtení konkrétních verzí portů jsou k dispozici pouze v případech, kdy je rezervována úplná historie potvrzení. Vcpkg zjistí, kdy byla naklonována do mělkého úložiště, a vygeneruje chybovou zprávu, když se nepodaří načíst verzi portu.

Například použití vcpkg.json s konkrétní referenční úrovní, jako je následující:

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

Výsledkem bude následující chyba:

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

Tato chyba značí, že potvrzení (4f8427eb0bd40da1856d4e67bde39a4fda689d72) vyžadované pro konkrétní verzi balíčku fmt není k dispozici v mělkém klonu.

Rezoluce:

Převod na úplný klon
- Nejjednodušším řešením tohoto problému je převést na úplný klon:
```
git fetch --unshallow
```
Použití GitHub Actions (výchozí mělké klony)
- GitHub Actions často standardně používá mělké klony. Tento problém můžete obejít tak, že pracovní postup GitHub Actions upravíte tak, aby se provedl úplný klon. Před použitím nástroje vcpkg přidejte následující krok:
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

Příčina: Neočekávané zahrnutí výchozích funkcí do přechodných závislostí

Při správě závislostí pomocí nástroje vcpkg můžete zjistit, že se přechodné závislosti instalují s jejich výchozími funkcemi, i když tyto funkce pro váš projekt nechcete. Tato situace může vést k neočekávanému nafouknutí nebo funkčnosti v konečném buildu.

Scénář

Máte závislost na knihovně Y, která zase závisí na knihovně X. Knihovna X má výchozí funkce, včetně foo, které chcete z projektu vyloučit. Manifest nejvyšší úrovně pro knihovnu Y může vypadat nějak takto:

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

Očekáváte, že X bude nainstalován bez výchozích funkcí kvůli nastavení "default-features": false. Nicméně, X je stále nainstalován s výchozí funkcí foo.

Důvod

Vlastnost default-features se považuje pouze v manifestu nejvyšší úrovně. To znamená, že výchozí funkce tranzitivních závislostí (například X v tomto scénáři) jsou stále zahrnuté, pokud nejsou explicitně zakázány na nejvyšší úrovni. Když se knihovna Y vyřeší, vcpkg nepřenáší nastavení "default-features": false na přechodnou závislost X, což vede k instalaci X s výchozími funkcemi.

Usnesení

Abyste měli jistotu, že jsou přenášené závislosti, jako je X, nainstalované bez výchozích funkcí, musíte je povýšit na přímé závislosti v manifestu nejvyšší úrovně a explicitně zakázat jejich výchozí funkce. Upravte vcpkg.json tak, aby zahrnovaly X přímo s "default-features": false:

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

Tento přístup zajišťuje, že X bude nainstalován bez výchozích funkcí, protože X je přímá závislost s explicitním pokynem k vyloučení výchozích funkcí.

Podrobnější informace o tom, jak fungují výchozí funkce a jak je spravovat, najdete v článku o konceptu výchozích funkcí.

Problém tu není uvedený

Pokud tady váš problém není uvedený, navštivte naše úložiště pro vytvoření nového problému.

Sdílet prostřednictvím