Panduan pemecahan masalah penerapan versi

Artikel
02/06/2025

Panduan ini ditujukan untuk pengguna yang menghadapi masalah dengan penomoran versi .

Memeriksa file versi untuk port

Nota

Proses yang dijelaskan di bawah ini dimaksudkan untuk bekerja untuk port dari registri vcpkg . Lihat dokumentasi registri kami untuk mempelajari bagaimana implementasi database versi di registri kustom.

Untuk memeriksa database versi port tertentu:

Navigasi ke direktori vcpkg/versions.
Temukan folder port:
- Temukan folder yang sesuai dengan huruf pertama port. Misalnya, untuk fmt buka folder bernama f-.
Buka file versi port:
- Temukan file JSON dengan nama port yang sama. Misalnya, file versi fmt diberi nama fmt.json.

File versi port berisi daftar versi yang tersedia dengan detail seperti tag versi dan hash objek pohon Git yang sesuai. Informasi ini diperlukan oleh vcpkg untuk mengambil versi port tertentu. Hanya versi yang terkandung dalam daftar ini yang tersedia untuk digunakan dalam file manifes Anda.

Untuk detail selengkapnya tentang penerapan versi, lihat dokumentasi referensi kami:

konsep penerapan versi
penerapan versi

Untuk detail selengkapnya tentang menggunakan manifes, lihat manifes

Penyebab: Meminta versi paket yang tidak ada

Ketika versi yang ditentukan dalam file manifes tidak ada di database versi vcpkg, vcpkg gagal menyelesaikan dependensi dan menghasilkan pesan kesalahan yang menyerupai berikut ini:

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.

Untuk mengatasi masalah ini:

Perbarui database versi:
- Versi yang Anda inginkan mungkin tidak ada di salinan lokal database versi Anda. Dalam hal ini, jalankan perintah git pull untuk memperbarui registri vcpkg ke commit terbaru.
Periksa versi yang tersedia:
- Pilih salah satu versi yang tersedia dalam database versi.
Perbarui file manifes.
- Edit file vcpkg.json Anda.
- Ubah versi yang ditentukan menjadi versi yang tersedia di repositori vcpkg. Misalnya, ubah dari "version>=": "100.0.0" menjadi "version>=": "10.1.1".
Jalankan penginstalan vcpkg:
- Jalankan perintah vcpkg install lagi di terminal atau prompt perintah Anda.

Penyebab: Menentukan batasan versi di berbagai skema

Konflik skema versi terjadi ketika versi yang ditentukan dalam file vcpkg.json untuk dependensi menggunakan skema penerapan versi yang berbeda dari yang digunakan dalam versi dasar repositori vcpkg. Ini mengakibatkan kesalahan karena vcpkg tidak dapat membandingkan versi di berbagai skema.

Jika batasan version>= yang dinyatakan menggunakan skema versi yang berbeda dari yang digunakan dalam versi dasar, vcpkg tidak dapat menentukan versi mana yang lebih besar atau sama dengan versi lainnya.

Misalnya, jika Anda menentukan:

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

vcpkg menghasilkan pesan kesalahan berikut:

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.

Resolusi:

Gunakan skema versi yang kompatibel:
- Periksa database versi di repositori vcpkg di bawah versions/b-/boost-regex.json untuk menemukan versi boost-regex yang menggunakan skema penerapan versi yang sama dengan garis besar.
- Perbarui batasan version>= di vcpkg.json Anda ke versi yang menggunakan skema yang kompatibel.
Ubah ke versi yang diinginkan
- Jika Anda memerlukan versi boost-regex tertentu yang menggunakan skema penomoran versi yang berbeda, Anda dapat menggantinya dalam manifes Anda.
- Modifikasi vcpkg.json Anda untuk menyertakan bagian penggantian guna menentukan versi yang diinginkan.
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Penyebab: Riwayat penerapan yang tidak memadai dalam kloning dangkal

Ketika vcpkg dikloning dengan riwayat penerapan terbatas (kloning dangkal), vcpkg tidak memiliki riwayat penerapan yang diperlukan untuk menyelesaikan batasan atau garis besar versi tertentu. Hash objek pohon Git yang digunakan oleh vcpkg untuk mengambil versi port tertentu hanya tersedia ketika riwayat penerapan penuh dicek keluar. vcpkg mendeteksi ketika telah dikloning ke dalam repositori dangkal dan menghasilkan pesan kesalahan ketika gagal mengambil versi port.

Misalnya, menggunakan vcpkg.json dengan garis besar tertentu seperti berikut ini:

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

Akan mengakibatkan kesalahan berikut:

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

Kesalahan ini menunjukkan bahwa commit (4f8427eb0bd40da1856d4e67bde39a4fda689d72) yang diperlukan untuk versi tertentu dari paket fmt tidak tersedia dalam kloning superfisial.

Resolusi:

Ubah menjadi klon penuh
- Solusi termudah untuk masalah ini adalah mengubah ke klon penuh.
```
git fetch --unshallow
```
Menggunakan GitHub Actions (Default Shallow Clones)
- GitHub Actions sering menggunakan kloning dangkal secara default. Untuk mengatasi hal ini, Anda dapat memodifikasi alur kerja GitHub Actions untuk melakukan klon penuh. Tambahkan langkah berikut sebelum menggunakan vcpkg:
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

Penyebab: Penyertaan fitur default yang tidak terduga dalam dependensi transitif

Saat mengelola dependensi dengan vcpkg, Anda mungkin menemukan bahwa dependensi transitif diinstal dengan fitur defaultnya, bahkan ketika Anda mungkin tidak menginginkan fitur tersebut untuk proyek Anda. Situasi ini dapat menyebabkan kembung atau fungsionalitas yang tidak terduga dalam build akhir Anda.

Skenario

Anda memiliki dependensi pada pustaka Y, yang pada gilirannya bergantung pada pustaka X. Pustaka X memiliki fitur default, termasuk foo, yang ingin Anda kecualikan dari proyek Anda. Manifes tingkat atas Anda untuk pustaka Y mungkin terlihat seperti ini:

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

Anda mengharapkan X akan diinstal tanpa fitur bawaannya karena pengaturan "default-features": false. Namun, X masih diinstal dengan fitur default foo.

Alasan

Properti default-features hanya dipertimbangkan pada manifes tingkat atas. Ini berarti bahwa fitur default dependensi transitif (seperti X dalam skenario ini) masih disertakan kecuali dinonaktifkan secara eksplisit di tingkat atas. Ketika pustaka Y terpecahkan, vcpkg tidak menyebarluaskan pengaturan "default-features": false ke dependensi transitif X, mengakibatkan penginstalan X dengan fitur defaultnya.

Resolusi

Untuk memastikan bahwa dependensi transitif seperti X diinstal tanpa fitur defaultnya, Anda perlu mempromosikannya untuk mengarahkan dependensi dalam manifes tingkat atas Anda dan secara eksplisit menonaktifkan fitur default mereka. Ubah vcpkg.json Anda untuk menyertakan X langsung dengan "default-features": false:

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

Pendekatan ini memastikan bahwa X diinstal tanpa fitur defaultnya, karena sekarang X adalah dependensi langsung dengan instruksi eksplisit untuk mengecualikan fitur default.

Untuk informasi lebih rinci tentang cara kerja fitur default dan cara mengelolanya, lihat artikel konsep fitur default .

Masalah tidak tercantum di sini

Jika masalah Anda tidak tercantum di sini, kunjungi repositori kami untuk membuat masalah baru.

Bagikan melalui