Aracılığıyla paylaş

Kayıt defterleri kavramları

  • Makale

Genel bakış

vcpkg, https://github.com/Microsoft/vcpkgadresinde bağlantı noktalarına paketlenmiş kitaplıkların bir seçimini barındırıyor. Bu bağlantı noktaları koleksiyonu, seçilmiş kayıt defteriolarak adlandırılır. Ancak vcpkg, seçilen kayıt defteriyle sınırlı değildir. Kullanıcılar özel kayıt defterleri oluşturarak bağlantı noktası seçimini genişletebilir.

Kayıt defteri, belirli bir yapıda düzenlenmiş bağlantı noktaları ve yardımcı dosya koleksiyonudur. Kayıt defteri yapısı izlenerek, bir kayıt defterinde yer alan bağlantı noktaları, seçilen kayıt defterindeki bağlantı noktalarına sunulan özelliklerle (sürüm oluşturma, ikili önbelleğe alma) yüklenebilir.

Şu anda üç tür kayıt defteri vardır:

vcpkg'ye, vcpkg-configuration.json dosyakullanılarak özel kayıt defterlerinde kullanılabilir bağlantı noktalarını dikkate almaları talimatı verilmektedir. Projelerinizde özel kayıt defterlerini kullanma öğreticisi için Öğreticisi: Git tabanlı kayıt defteri bağımlılık yükleme makalesine bakın.

Kayıt defteri yapısı

vcpkg'nin bir kayıt defteriyle arabirim oluşturması için aşağıdaki yapıya uygun olması gerekir:

  • ports adlı dizin, her alt dizinin alt dizin adıyla eşleşen belirli bir bağlantı noktası içeren bağlantı noktaları koleksiyonunu içerir. Örneğin, bağlantı noktası foo dosyaları ports/fookonumunda bulunur.
  • versions adlı dizin, sürümleri veritabanını oluşturan dosyaları içerir.

Örnek: kayıt defteri yapısı

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

Sürümler veritabanı

Tüm kayıt defterlerinin kökünde, sürümleri veritabanını içeren bir versions dizini bulunur.

Sürümler veritabanının iki bileşeni vardır:

  • Temel dosya
  • Sürüm dosyaları

Temel dosya, versions dizininin kökünde bulunan baseline.json adlı bir JSON dosyasıdır.

Sürüm dosyaları, kullanılabilir bağlantı noktalarıyla aynı adlara sahip JSON dosyalarıdır. bunlar versions/<prefix>/<port name>.jsoniçinde bulunmalıdır; burada <prefix>, bağlantı noktası adının ilk harfi ve ardından kısa çizgidir. Örneğin, foo bağlantı noktası için sürüm dosyası versions/f-/foo.json'de olmalıdır.

Sürüm dosyasının amacı iki kattır:

  • Her bağlantı noktasının tüm kullanılabilir sürümlerini listeleme
  • Her sürümün alma konumlarını işaret edin.

Sürüm dosyasının biçimi kayıt defterinin türüne bağlıdır.

Temel dosya

Türü ne olursa olsun tüm kayıt defterleri, versions/baseline.jsonkonumunda bulunan baseline.json adlı bir dosya içermelidir.

Temel dosyanın amacı, kayıt defterindeki tüm bağlantı noktaları için en son olarak kabul edilen sürüm kümesini açıklamaktır. Her seferinde bir bağlantı noktasının yeni bir sürümü kayıt defterine eklendiğinde, bu dosyanın güncellenmesi beklenmektedir.

Dosya, özellikleri taban çizgisi nesneleri olarak adlandırılan tek bir nesneden oluşan bir JSON dosyasıdır. Temel nesnelerin her birinin özellikleri, değerlerinin sürüm girdileri olduğu bağlantı noktası adlarıdır. kayıt defterlerine referans alınan makale, temel dosyaların düzenini daha ayrıntılı olarak açıklar.

Her temel sürüm girişi aşağıdaki özelliklere sahip bir nesnedir:

  • baseline: değer, ilgili vcpkg.json dosyasıyla eşleşen bağlantı noktasının sürümüdür.
  • port-version: değer, bağlantı noktasının port-version'i, ilgili vcpkg.json dosyasıyla eşleşir.

Örnek temel dosya

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

Aşağıdakiler için başvuru belgelerine bakın:

Sürüm dosyaları

Kayıt defterindeki her bağlantı noktasının karşılık gelen bir sürüm dosyası vardır. Sürüm dosyaları versions/<prefix>/<port name>.json konumunda depolanır; burada <prefix>, bağlantı noktası adının ilk harfi ve ardından kısa çizgidir. Örneğin, foo bağlantı noktası için sürüm dosyası versions/f-/foo.json'de bulunmaktadır.

Sürüm dosyasının amacı iki kattır:

  • Her bağlantı noktasının tüm kullanılabilir sürümlerini listeleme
  • Bu sürümlerin her birinin alma konumunu işaret edin

Sürüm dosyasının düzeni, bir "versions" dizisi içeren bir nesnedir ve bu dizideki her giriş bir sürüm nesnesidir. Bir sürüm nesnesi aşağıdaki özellikleri içermelidir:

  • Sürüm özelliği: Özelliğin anahtarı ve değeri, vcpkg.json dosyasında bağlantı noktası tarafından kullanılanlarla eşleşmelidir. Anahtar, version, version-semver, version-dateveya version-stringbiri olmalıdır; değeri, bağlantı noktasının bildirim dosyasında (vcpkg.json) göründüğü şekilde sürüm olmalıdır.
  • port-version: değer, bağlantı noktasının vcpkg.json dosyasında göründüğü şekliyle bağlantı noktasının port-version değeridir.
  • git-tree: (yalnızca Git kayıt defterlerinde) değer, bağlantı noktasının dizinine karşılık gelen git ağacı SHA'dır. Bu, bağlantı noktasının dizin içeriğinin karma değeri hesaplanarak elde edilen bir SHA'dır; bu git-tree SHA, sağlanan git ağacına uygun olan bağlantı noktasının içeriğini almak için Git tarafından kullanılabilir. Bu, vcpkg'nin kayıt defterleri Git geçmişinden bağlantı noktalarının eski sürümlerini almasını mümkün kılar. Belirli bir bağlantı noktası sürümü için bu değeri nasıl edineceğinizi öğrenmek için git kayıt defterleri bölümünü okuyun.
  • path: (yalnızca dosya sistemi kayıt defterlerinde) değer, belirli bir sürüm için bağlantı noktası dosyalarını içeren dizinin tam yoludur.

Dosya sistemi kayıt defteri sürüm dosyası örneği

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Aşağıdakiler için başvuru belgelerine bakın:

Yerleşik kayıt defteri

Yerleşik kayıt defteri özel bir kayıt defteri türüdür. klasik modda kullanılan varsayılan kayıt defteridir. bildirim modundavarsayılan kayıt defteri belirtilmediğinde vcpkg örtük olarak yerleşik kayıt defterini kullanır.

Dahili kayıt defteri, vcpkg deposunu https://github.com/Microsoft/vcpkg'den git clone ettiğinizde oluşturulmuş olan seçilmiş kayıt defterinin yerel kopyasını ifade eder. Bazı işlemler, VCPKG_ROOT ortam değişkeninin yerleşik kayıt defterine işaret etmesini bekler.

vcpkg "tek satırlık komut" veya Visual Studio yükleyicisi aracılığıyla alınırsa, yerleşik kayıt defteri, https://github.com/Microsoft/vcpkg depoya işaret eden bir Git kayıt defterine eşdeğer olur.

Git kayıt defterleri

Git kayıt defteri, kayıt defteri yapısını izleyen ve kayıt defterindeki bağlantı noktaları için sürüm oluşturma sağlamak üzere Git'in özelliklerinden yararlanan bir depodur. https://github.com/Microsoft/vcpkg'da düzenlenmiş kayıt defteri, bir Git kayıt defteri uygulamasıdır.

Git kayıt defterleri herhangi bir Git deposu sağlayıcısında barındırılarak, özel kayıt defterinize erişimi denetlemek için seçtiğiniz Git barındırma hizmetini kullanmanıza olanak tanıyarak kayıt defterinizin paylaşılması kolaylaşır.

Git kayıt defterleri, özel kayıt defteri uygulamak için önerilen yöntemdir. Sürüm oluşturma mekanizması, seçilen kayıt defteri tarafından kullanılanla aynı olduğundan, Git kayıt defterleri sürüm veritabanı dosyalarınızı yönetmek için x-add-version kullanabilir.

Git kayıtlarının uygulanma ayrıntıları için kayıt defterleri referansı'e bakın.

Git kayıt defterine yeni sürüm ekleme

x-add-version komutu, kayıt defterine yeni bir bağlantı noktası veya yeni bir sürüm eklemek için kullanılabilir. Bu komutu kullanarak sürüm eklerken dikkate alınması gereken birkaç şey vardır:

Önemli

Yeni bir sürüm eklerken, sürüm geçmişinin yeniden yazılmasını önlemek için bağlantı noktasının bildirilen sürümünü henüz yayımlanmamış bir sürüme güncelleştirmeyi unutmayın.

Bir bağlantı noktasında değişiklik yaparken, ilk adım vcpkg.json dosyasındaki sürümünü artırmak olmalıdır. Değişiklikleriniz paketin upstream sürümünde bir güncelleme içeriyorsa, port-version'yi 0olarak ayarlamayı unutmayın; aksi takdirde, port-version'ü bir artırın.

x-add-version komut, sürüm veritabanını güncelleştirmeden önce tüm bağlantı noktası değişikliklerinizin depoya işlenmesini gerektirir.

Örnek: Git kayıt defterine yeni bir bağlantı noktası sürümü ekleme

git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json

--x-builtin-ports-root ve --x-builtin-registry-versions-dir yeniden yönlendirme seçenekleri sırasıyla kayıt defterinizin ports ve versions dizinlerine işaret etmelidir.

x-add-version komutu başarıyla çalıştırıldıktan sonra, son işlemeyi sürüm dosyası değişikliklerini içerecek şekilde düzeltin.

git commit --amend -m "Update foo to new version"

Dosya sistemi kayıt defterleri

Dosya sistemi kayıt defterleri, bir dosya sisteminde bulunan bir kayıt defterinin uygulamasıdır. Ortak kayıt defteri yapısını izler ancak sürüm oluşturma özellikleri sunmak için Git'i kullanmaz. Bunun yerine, bağlantı noktalarının her sürümü için ayrı bir yol kullanarak ilkel bir sürüm denetimi biçimi kullanırlar.

Bu tür bir kayıt defteri, bağlantı noktalarınız için bir test alanı olarak veya Git olmayan bir sürüm denetim sisteminde kayıt defteri için alternatif sağlamak için uygundur. Büyük bağlantı noktaları koleksiyonu için dosya sistemi kayıt defterleri önerilmez ve bu tür bir kayıt defteri için sürüm veritabanı dosyalarını işlemek için herhangi bir araç sağlanmaz.

Dosya sistemi kayıt defterini uygulama yöntemleri hakkında detaylar için kayıt defterleri başvurusu bkz.

Kayıt defterlerini kullanma

Projenizde özel bir kayıt defteri kullanmak için, projenizin bildirim dosyasının (vcpkg.json)yanında bir yapılandırma dosyası (vcpkg-configuration.json) oluşturmanız gerekir.

Varsayılan kayıt defteri

bağlantı noktası adlarını çözümlemek, bir bağlantı noktasının adı registries dizisindeki diğer kayıt defterleri tarafından bildirilen paket desenlerinden herhangi biriyle eşleşmediğinde varsayılan kayıt defteri geri dönüş olarak çalışır.

Özel kayıt defterleriyle ilgilenmeyen kullanıcılara kolaylık sağlamak için vcpkg, yerleşik kayıt defteri varsayılan kayıt defteri olarak örtük olarak ekler. Bu davranışı değiştirmek için, varsayılan kayıt defteri herhangi bir kayıt defterine ayarlanabilir veya tamamen devre dışı bırakılabilir. default-registry özelliği.

Örnek: Özel kayıt defterini varsayılan olarak ayarlama

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

Örnek: Varsayılan kayıt defterini devre dışı bırakma

vcpkg-configuration.json

{
  "default-registry": null
}

Kayıt defterleri dizisi

vcpkg ile yüklenebilecek bağlantı noktalarının seçimini genişletmek için, registries dizisini kullanarak ek kayıt defterleri belirtebilirsiniz.

Örnek: Yapılandırmaya özel kayıt defterleri ekleme

Not (dikkat)

Kayıt defteri türüne bağlı olarak, registries dizisinde farklı bilgiler sağlamanız gerekebilir. Her kayıt defteri türü için hangi özelliklerin gerekli olduğunu öğrenmek için vcpkg-configurtion.json başvuru bakın.

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://my.privateregistry.git",
      "baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
      "packages": [ "foo" ]
    },
    {
      "kind": "filesystem",
      "path": "C:/path/to/registry",
      "baseline": "baseline1",
      "packages": [ "bar" ]
    }
  ]
}

Sürüm geçmişini yeniden yazma

Bir sürüm, sürüm dosyalarına yayımlandıktan sonra, git kayıt defteri veya dosya sistemi kayıt defterindeki ilişkili git-tree numarasını değiştirmeyin.

vcpkg'nin tasarım ilkelerinden biri, yüklü bağımlılıkların sürümlerinin kullanıcı müdahalesi olmadan değişmemesidir. git-tree girdisini değiştirerek sürüm dosya geçmişini yeniden yazmak bu ilkeyi ihlal eder.

Mevcut sürümde sorunlar varsa, yeni bir port-versionoluşturmayı tercih edin.

Sürüm dosyalarını silme

Not

Bu bölüm yalnızca Git kayıt defterleri için geçerlidir

Kayıt defterinizden bir portu kaldırırken, port dizinindeki içeriğini ve temel dosyadaki girdisini çıkarın. Ancak ilişkili sürümler dosyasını kaldırmaz.

Sürüm dosyası kaldığı sürece kayıt defterinde artık bir bağlantı noktası olmasa bile, bağlantı noktası kullanıcıları overridessürümünü kullanarak eski sürümleri yükleyebilir.

Sonraki adımlar

Şimdi deneyebileceğiniz bazı görevler şunlardır: