Przewodnik rozwiązywania problemów z wersjonowaniem

Artykuł
02/06/2025

Ten przewodnik jest przeznaczony dla użytkowników, którzy napotykają problemy z wersjonowaniem.

Sprawdzanie pliku wersji dla portu

Notatka

Opisany poniżej proces jest przeznaczony do obsługi portów z rejestru vcpkg . Zapoznaj się z naszą dokumentacją rejestru , aby dowiedzieć się, jak baza danych przechowywania wersji jest implementowana w rejestrach niestandardowych.

Aby sprawdzić wersje bazy danych określonego portu:

Przejdź do katalogu vcpkg/versions.
Znajdź folder portu:
- Znajdź folder odpowiadający pierwszej literze portu. Na przykład w przypadku fmt otwórz folder o nazwie f-.
Otwórz plik wersji portów:
- Znajdź plik JSON o tej samej nazwie portu. Na przykład plik wersji fmt nosi nazwę fmt.json.

Plik wersji portu zawiera listę dostępnych wersji ze szczegółowymi informacjami, takimi jak tagi wersji i odpowiednie skrót obiektu drzewa usługi Git. Te informacje są wymagane przez program vcpkg w celu pobrania określonych wersji portów. Tylko wersje zawarte na tej liście są dostępne do użycia w plikach manifestu.

Aby uzyskać więcej informacji na temat przechowywania wersji, zobacz dokumentację referencyjną:

Aby uzyskać więcej informacji na temat korzystania z manifestu, zobacz manifest

Przyczyna: Żądanie nieistniejącej wersji pakietu

Jeśli wersja określona w pliku manifestu nie istnieje w bazie danych wersji programu vcpkg, program vcpkg nie może rozpoznać zależności i generuje komunikat o błędzie podobny do następującego:

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.

Aby rozwiązać ten problem:

Zaktualizuj bazę danych wersji:
- Wybrana wersja może nie znajdować się w lokalnej kopii bazy danych wersji. W takim przypadku uruchom polecenie git pull, aby zaktualizować rejestr vcpkg do najnowszego zatwierdzenia.
Sprawdź dostępne wersje:
- Wybierz jedną z wersji dostępnych w bazie danych wersji.
Aktualizuj plik manifestu:
- Edytuj plik vcpkg.json.
- Zmień określoną wersję na wersję dostępną w repozytorium vcpkg. Na przykład zmień wartość z "version>=": "100.0.0" na "version>=": "10.1.1".
Uruchom instalację narzędzia vcpkg:
- Ponownie wykonaj polecenie vcpkg install w terminalu lub wierszu polecenia.

Przyczyna: Określanie ograniczenia wersji w różnych schematach

Konflikt schematu wersji występuje, gdy wersja określona w pliku vcpkg.json dla zależności używa innego schematu przechowywania wersji niż używana w wersji bazowej repozytorium vcpkg. Powoduje to błąd, ponieważ narzędzie vcpkg nie może porównać wersji między różnymi schematami.

Jeśli zadeklarowane ograniczenie version>= używa innego schematu wersji niż ten używany w wersji bazowej, vcpkg nie może określić, która wersja jest większa lub równa drugiej.

Jeśli na przykład określisz:

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

Narzędzie vcpkg generuje następujący komunikat o błędzie:

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.

Rozdzielczości:

Użyj zgodnego schematu wersji:
- Sprawdź bazę danych wersji w repozytorium vcpkg w obszarze versions/b-/boost-regex.json, aby znaleźć wersję boost-regex, która używa tego samego schematu przechowywania wersji co punkt odniesienia.
- Zaktualizuj ograniczenie version>= w vcpkg.json do wersji, która używa zgodnego schematu.
Zastąp żądaną wersją
- Jeśli potrzebujesz określonej wersji funkcji boost-regex, która używa innego schematu przechowywania wersji, możesz zastąpić ją w manifeście.
- Zmodyfikuj vcpkg.json, aby uwzględnić sekcję przesłonięć określającą żądaną wersję:
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Przyczyna: Nieodpowiednia historia zatwierdzeń w płytkim klonie

Gdy narzędzie vcpkg jest klonowane z ograniczoną historią zatwierdzeń (płytkie klonowanie), nie ma wymaganej historii zatwierdzeń w celu rozwiązania określonych ograniczeń wersji lub punktów odniesienia. Skróty obiektów drzewa Git używane przez narzędzie vcpkg do pobierania określonych wersji portów są dostępne tylko wtedy, gdy wyewidencjonowana jest pełna historia zatwierdzeń. Narzędzie vcpkg wykrywa, kiedy zostało sklonowane do płytkiego repozytorium i generuje komunikat o błędzie, gdy nie można pobrać wersji portu.

Na przykład użycie vcpkg.json z określonym punktem odniesienia, tak jak poniżej:

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

Spowoduje to następujący błąd:

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

Ten błąd wskazuje, że zatwierdzenie (4f8427eb0bd40da1856d4e67bde39a4fda689d72) wymagane dla określonej wersji pakietu fmt nie jest dostępne w płytkim klonie.

Postanowienia

Przekształć w pełną kopię
- Najprostszym rozwiązaniem tego problemu jest przekonwertowanie na pełne klonowanie:
```
git fetch --unshallow
```
Korzystanie z funkcji GitHub Actions (domyślne płytkie klony)
- Funkcja GitHub Actions często domyślnie wykonuje płytkie klonowanie. Aby obejść ten proces, możesz zmodyfikować przepływ pracy funkcji GitHub Actions w celu wykonania pełnego klonowania. Dodaj następujący krok przed użyciem narzędzia vcpkg:
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

Przyczyna: Nieoczekiwane włączenie funkcji domyślnych w zależnościach przechodnich

Podczas zarządzania zależnościami za pomocą narzędzia vcpkg może się okazać, że zależności przechodnie są instalowane z ich domyślnymi funkcjami, nawet jeśli nie chcesz, aby te funkcje były używane w projekcie. Taka sytuacja może prowadzić do nieoczekiwanego nadmiernego rozrostu lub dodatkowej funkcjonalności w ostatecznej wersji projektu.

Scenariusz

Masz zależność od biblioteki Y, która z kolei zależy od biblioteki X. Biblioteka X ma funkcje domyślne, w tym foo, które chcesz wykluczyć z projektu. Manifest najwyższego poziomu dla biblioteki Y może wyglądać mniej więcej tak:

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

Oczekujesz, że X zostanie zainstalowany bez ich domyślnych funkcji z powodu ustawienia "default-features": false. Jednak X jest nadal instalowana z funkcją domyślną foo.

Powód

Właściwość default-features jest uwzględniana tylko w manifeście najwyższego poziomu. Oznacza to, że domyślne funkcje zależności przechodnich (na przykład X w tym scenariuszu) są nadal uwzględniane, chyba że jawnie wyłączone na najwyższym poziomie. Po rozwiązaniu biblioteki Y, vcpkg nie przekazuje ustawienia "default-features": false do przechodniej zależności X, co skutkuje zainstalowaniem X z domyślnymi funkcjami.

Rezolucja

Aby upewnić się, że przejściowe zależności, takie jak X, są instalowane bez ich domyślnych funkcji, należy podwyższyć ich poziom do bezpośrednich zależności w manifeście najwyższego poziomu i jawnie wyłączyć ich funkcje domyślne. Zmodyfikuj vcpkg.json, aby uwzględnić X bezpośrednio przy użyciu "default-features": false:

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

Takie podejście zapewnia, że X jest instalowana bez domyślnych funkcji, ponieważ teraz X jest bezpośrednią zależnością z jawną instrukcją wykluczania funkcji domyślnych.

Aby uzyskać bardziej szczegółowe informacje na temat sposobu działania funkcji domyślnych i sposobu zarządzania nimi, zobacz artykuł dotyczący koncepcji funkcji domyślnych .

Problem nie znajduje się tutaj

Jeśli problem nie znajduje się na liście, odwiedź nasze repozytorium, aby utworzyć nowe zgłoszenie.

Udostępnij za pośrednictwem