Bakımcı kılavuzu

Bu belgede vcpkg'ye katkıda bulunurken izleyebileceğiniz ilkeler, yönergeler ve en iyi yöntemler açıklanmaktadır.

Aşağıdakiler ile aynı role hizmet etmek için tasarlanmıştır:

• Debian İlke Kılavuzu,
• Homebrew Bakımcı Yönergeleri ve
• Homebrew'ün Formül Rehberi.

Seçilmiş kayıt defteri tasarım hedefleri

Bağlantı noktalarının aynı anda yüklenmesi gerekir

Kayıt defterine dahil edilen bir bağlantı noktası, kayıt defterindeki diğer tüm bağlantı noktalarıyla birlikte başarıyla derlenmelidir. Bağlantı noktalarının tüm birleşimi, vcpkg'nin otomatik CI'si tarafından düzenli olarak test edilir.

Bağlantı noktası aşağıdakilerden hiçbirini yapmamalıdır:

• Başka bir bağlantı noktasıyla çakışan dosyaları yükleyin.
• Çakışan kitaplıkları bir manual-link dizinine yerleştirin bölümünde açıklanan dar kapsamlı, açıkça bağlanmış kitaplıklar dışında, başka bir pakete ait sembolleri ve tanımları yüklemeyin.
• Başka bir bağlantı noktasının varlığını veya yokluğunu test edin. Bağımlılık bildirme dışında.

Özel durumlar şunlar için yapılır:

• Resmi kapasitede başka bir bağlantı noktasının yerini alan bağlantı noktaları. Bu, şu durumları içerir:
  • Aynı proje ardıl bir bileşen yayımlar.
  • Başka bir proje, bir fork yoluyla da dahil olmak üzere, terk edilmiş bir bileşenin bakımını üstlenir.
  • Başka bir proje ardıl bir bileşen yayımlar.
• Platform çakışması olmayan bağlantı noktaları. Örneğin, Windows’u desteklemeyen bir Linux bileşeni için yalnızca Windows’a yönelik bir alternatif.
• Bu ilkeden önce gelen ve çok sayıda kullanıcı ve katkıda bulunanlara sahip portlar.

vcpkg bakımcıları grandfathering istisnalarını duruma göre değerlendirir. Örneğin, boringssl özel kayıt defterleri kullanılabilir olmadan önce eklendi ve openssl, OpenSSL çatal ailesi için kurallı sağlayıcı olmasına rağmen, hâlâ anlamlı kullanıcıları olduğu için seçilen kayıt defterinde kalır. Yalnızca önceki kabul bir istisnayı garanti etmez.

İlkeye uymayan bağlantı noktaları, özenle hazırlanmış kayıt defterine kaydedilemez.

Tavsiye

Bağlantı noktanız seçilen kayıt defterine eklenmiyorsa , özel bir kayıt defteri yayımlamayı veya katman bağlantı noktası kullanmayı göz önünde bulundurun.

Bağlantı noktaları en az bir resmi üçlüde test edilmelidir

Kurulu kayıt defterindeki tüm portlar, resmi en az bir üçlü için CI'de test edilmelidir.

Özel durumlar şunlar için yapılır:

• Geçici koşullar, örneğin:
  • Bağlantı noktası, CI altyapısında bir güncelleme yapılmadan derlenemiyor.
  • Yukarı akış bağımlılığında yeni bir hataya neden olan değişiklik nedeniyle bağlantı noktası derlenmiyor ve durumu çözmek için devam eden bir çalışma var.
• Bu ilkeden önce gelen ve çok sayıda kullanıcı ve katkıda bulunanlara sahip portlar.

En az bir resmi üçlüde test edilemeyen yeni portlar, seçilen kayıt defterine kabul edilmez. Artık bu ilkeye uymayan ve yukarıda listelenen bir özel durum için uygun olmayan mevcut portlar kayıt defterinden kaldırılır. Örneğin, bir portun desteklediği her resmi üçlüde CI testi devre dışı bırakıldıysa ve hiçbir özel durum geçerli değilse, port listeden çıkarılır.

Tavsiye

Bağlantı noktanız seçilen kayıt defterine eklenmiyorsa , özel bir kayıt defteri yayımlamayı veya katman bağlantı noktası kullanmayı göz önünde bulundurun.

Paketlenmiş bileşenler kararlı olmalı ve aktif olarak bakımı yapılmalıdır

Küratörlü kayıt deposunda paketlenen bileşenler etkin bakımda olmalıdır. Etkin olmayan bileşenler için bağlantı noktaları listeden kaldırılabilir.

Bir bileşen şu durumlarda etkin değil olarak kabul edilir:

• Bakımcıları bileşenin terk edildiğini ilan etti.
• Kaynak deposu arşivlenmiş veya artık katkıları kabul etmemektedir.
• Bakımcılar yanıt vermiyor veya ulaşılamıyor.
• Uzun zamandır anlamlı bir değişiklik yapılmadı.

Olgun ve kararlı olarak kabul edilen ve sık sık değişiklik almayan temel bileşenler için istisna uygulanır. Örneğin: zlib.

Paketlenmiş bileşenler kararlı olmalıdır

Küratörlü registry'de paketlenen bileşenler olgun olmalı ve vcpkg kullanıcıları tarafından kullanılmak üzere tasarlanmalıdır. Kişisel kullanıma yönelik bileşenler özel registry'lere yayımlanmalıdır.

Şu ifadelerden biri doğruysa, bileşen küratörlü kayıt için yeterince olgun kabul edilir:

• Bileşenin en az altı ay önce yayımlanmış bir sürümü vardır.
• Bileşen en az altı aylık aktif, kamuya açık geliştirmeyi gösterir.
• Bileşen, en az altı aylık yayınları olan veya aktif olarak kamuya açık geliştirildiği bir projenin resmi bir parçasıdır. Örneğin, yeni bir Boost kitaplığı veya Qt bileşeni.
• Bileşen, başka bir bağlamda önceki gereksinimlere eşdeğer olgunluğu gösterir.

Bileşen olgunlaşmamışlığının bazı göstergeleri şunlardır:

• Bileşen arama motorlarında görünmez.
• Bileşen sık sık yeniden adlandırılır.
• Diğer kitaplıklarla çakışmalar.

Tavsiye

Bağlantı noktanız seçilen kayıt defterine eklenmiyorsa , özel bir kayıt defteri yayımlamayı veya katman bağlantı noktası kullanmayı göz önünde bulundurun.

Pull İsteği Yapısı

Her bağlantı noktası için ayrı çekme istekleri yapın

Daha küçük çekme isteklerini (PR) gözden geçirmek daha kolaydır. Çekme istekleri tek bir portta değişiklik yapmalıdır. Bu, Sürekli Tümleştirme (CI) sonuçlarının bekleme sürelerini de azaltır.

PR'leri tek bir bağlantı noktasıyla sınırlamak bazı durumlarda mümkün olmayabilir. Örneğin, bir bağlantı noktası değiştirildiğinde, bu durum aşağı akış tüketicilerinin güncellenmesi veya düzeltme eki uygulanması ihtiyacını doğurabilir.

İlişkisiz kozmetik değişikliklerden kaçının

Yeniden biçimlendirme, değişkenleri yeniden adlandırma veya yazım hatalarını düzeltme gibi ilgisiz kozmetik değişiklikleri, aksi halde değiştirilmemiş bir portta yapmayın. Bu değişiklikler, başka yerde daha iyi kullanılabilecek işlem süresini tüketir. Derlemenin doğruluğunu, uyumluluğunu, güvenilirliğini veya yeniden üretilebilirliğini geliştiren değişiklikler yalnızca yüklü dosyalar değişmediği için önemsiz olarak kabul edilmez.

Ayırt edici bağlantı noktası adlarını kullanma

Bağlantı noktasının adı, içeriğini göstermelidir.

Portun adını bir arama altyapısında veya Repology gibi özel paket tarayıcılarında aramak, ilgili bileşenine yol açmalıdır.

Kısa adlara sahip veya ortak sözcüklerden sonra adlandırılmış bağlantı noktaları kesinleştirme gerektirir. Bu yalnızca küratörlü kayıttaki portun adı için geçerlidir; paketlenmiş bileşenin adı ve içeriğinin bu ilkeye uyması gerekmez.

Bir bileşeni bağlantı noktasının adıyla güçlü bir ilişkilendirmeyle paketleyen bağlantı noktaları için özel durumlar yapılır. Örneğin: libpng, opensslveya zlib.

Bu ilkeye uymak için, belirsiz adlara sahip yeni bağlantı noktaları aşağıdaki gibi bir ön ek kullanabilir:

• Deponun sahibi, kullanıcı adı veya kuruluşu. Örnek: google-cloud-cpp. GitHub üzerinde barındırılan bileşenlerin portları için, GitHub sahibi kabul edilebilir ve belirsiz olmayan bir ön ektir<github owner>-<repository name>.
• Paketin ait olduğu paketin adı: boost-dll. Yalnızca paket böyle bir paketin resmi bir bileşeniyse.

Örnek: Belirsiz bağlantı noktası adı

Adı ip olan bir bağlantı noktası belirsiz olarak kabul edilir çünkü:

• ad çok kısa,
• ad yaygın bir sözcük ve
• ad hiçbir tek bileşenle güçlü biçimde ilişkilendirilmiyor.

Bir adın belirsiz olup olmadığını belirlemek için, port adından C++ ve açık kaynak bileşenleri tarafından kullanılan aşağıdaki ortak ön ekleri ve sonekleri kaldırın:

• cpp
• free
• lib
• open
• sayılar

Örneğin: ip-cpp, libip ve ip5, aynı ip köke indirgendikleri için belirsizdir.

Bağlantı noktası yeniden adlandırmalarını sınırla

Kullanıcıların kafa karışıklığını önlemek için bir bağlantı noktasının 12 aylık bir süre içinde bir kereden fazla yeniden adlandırılmaması gerekir.

GitHub taslak PR'lerini kullanın

GitHub Taslak PR'leri, henüz birleştirmeye hazır olmayan işlerde CI veya insan geri bildirimi almak için harika bir yoldur. Yeni PR'lerin çoğu taslak olarak açılmalı ve CI geçtikten sonra normal PR'lere dönüştürülmelidir.

GitHub Taslak PR'leri hakkında daha fazla bilgi için bkz. Taslak çekme isteklerine giriş.

Bir vcpkg bakımcısı, gözden geçirme işlemi sırasında PR'nizi taslak haline dönüştürebilir; genellikle değişiklik isterken veya PR'nin ne zaman incelemeye hazır olarak işaretlenmesi gerektiğini belirten yorumlar bırakırken.

Etkin olmayan PR'leri kapatma

Vcpkg bakımcısı, çekme isteği katkıda bulunandan 60 günden uzun süredir işlem bekliyorsa onu kapatabilir. Hareketsizlik geri sayımı yalnızca katkıda bulunanın işlem yapması gerektiğinde çalışır. Çekme isteği derleme laboratuvarı doğrulamasını beklerken veya bir vcpkg bakımcısı tarafından gözden geçirilirken çalışmaz.

Çekme isteği şu durumlarda gözden geçirilebilir durumdadır:

• Başarısız PR kontrolü yoktur ya da katkıda bulunan kişi yardım ister veya hataların nedenini haklı gösterir.
• Bir vcpkg bakımcısından bekleyen herhangi bir istenen değişiklik veya açıklama yok.
• Birleştirme çakışmaları yoktur.

Geri sayım, PR katkıda bulunanın işlem yapmasını gerektiren bir duruma girdiğinde başlar. Bu durum, katkıda bulunanın çözmesi gereken sorunlarla bir çekme isteği açıldığında veya bir vcpkg bakımcısı değişiklik veya açıklama isteğinde bulunduğunda gerçekleşebilir. Bir vcpkg bakımcısı, katkıda bulunanın işlem yapmasını isterken çekme talebini taslak olarak işaretleyebilir.

Katkıda bulunandan gelen esaslı yanıt, geri sayımı sıfırlar. Yanıt bekleyen tüm talepleri çözümlerse ve PR gözden geçirmeye hazırsa, katkıda bulunanın yeniden işlem yapması gerekene kadar geri sayım durdurulur. Eylem gerektiğinde katkıda bulunan 60 gün içinde yanıt vermezse PR eski olarak kabul edilir ve vcpkg bakımcısının takdirine bağlı olarak kapatılabilir.

Portfiles

Kullanım dışı bırakılmış yardımcı işlevlerden kaçının

Şu anda aşağıdaki yardımcılar kullanım dışı bırakılmıştır:

• vcpkg_extract_source_archive_ex(), vcpkg_extract_source_archive() ile, ARCHIVE için desteklenen aşırı yükleme ile değiştirilmelidir.
• 'vcpkg_extract_source_archive()'suz kullanım dışı bırakılan aşırı yükleme, ARCHIVE ile desteklenen aşırı yükleme ile değiştirilmelidir.
• vcpkg_apply_patches() "extract" yardımcılarının bağımsız değişkenleri olan PATCHES ile değiştirilmelidir (örn. vcpkg_from_github())
• vcpkg_build_msbuild() şununla değiştirilmelidir: vcpkg_install_msbuild()
• vcpkg_copy_tool_dependencies() şununla değiştirilmelidir: vcpkg_copy_tools()
• vcpkg_configure_cmake kaldırıldıktan sonra vcpkg_cmake_configure(), PREFER_NINJA ile değiştirilmelidir
• vcpkg_build_cmake şununla değiştirilmelidir: vcpkg_cmake_build()
• vcpkg_install_cmake şununla değiştirilmelidir: vcpkg_cmake_install()
• vcpkg_fixup_cmake_targets şununla değiştirilmelidir: vcpkg_cmake_config_fixup

Yedek yardımcı işlevlerden bazıları, tüketicilerin davranışlarını belirli sürümlerde sabitlemesine olanak sağlamak ve yardımcıların davranışını belirli bir sürümde kilitlemek için "araç bağlantı noktalarında" bulunur. Araç bağlantı noktalarının bağlantı noktanıza "dependencies"eklenmesi gerekir; örneğin:

{
  "name": "vcpkg-cmake",
  "host": true
},
{
  "name": "vcpkg-cmake-config",
  "host": true
}

Bağlantı noktası dosyalarında açıklamaları aşırı şekilde kullanmaktan kaçının

İdeal olarak, port dosyaları kısa, basit ve mümkün olduğunca deklaratif olmalıdır. Çekme isteği göndermeden önce create komutu tarafından tanıtılan şablon yorumları kaldırın.

Onaltılık basamak dizeleri için küçük harf kullanın

vcpkg'deki özelliklerin çoğu onaltılık basamak dizelerini karşılaştırmaya dayanır. Bazı örnekler SHA512 karmalarını, Git işleme kimliklerini ve ağaç nesnesi karmalarını içerir ancak bunlarla sınırlı değildir.

Vcpkg dahili olarak, harflerin büyük-küçük olmasının önemsiz olduğu durumlarda bu tür değerlerin karşılaştırılması için küçük harf normalleştirme kullanır. Ancak vcpkg altyapısının üzerine kurulu araçlar aynı konuları dikkate almayabilir. Bu nedenle onaltılık dizeler gerekir

Tutarlılığı sağlamak için kelimeler aşağıdaki senaryolarda küçük harfe dönüştürülecek:

• SHA512 vcpkg yardımcı işlevlerindeki parametresi.
• REF Değer onaltılık bir dize olduğunda vcpkg yardımcı işlevindeki parametresi.
• git-tree Sürüm veritabanı dosyalarındaki nesnesi.
• sha512 Dosyadaki scripts/vcpkg-tools.json nesnesi.
• Onaltılık dizenin harf büyüklüğünün önem taşımadığı diğer yerler.

Bağlantı noktaları yola bağımlı olmamalıdır

Bağlantı noktaları, yüklü olan diğer bağlantı noktalarına bağlı olarak hangi içerikleri yüklediklerini değiştirecek şekilde işlevlerini değiştirmemelidir. Örneğin, verilen:

> vcpkg install a
> vcpkg install b
> vcpkg remove a

ile

> vcpkg install b

b tarafından yüklenen dosyalar, önceki yüklemesinin a etkisinden bağımsız olarak aynı olmalıdır. Portlar, herhangi bir işlem yapmadan önce, kurulu yapıda başka bir port tarafından bir şeyin sağlanıp sağlanmadığını algılamaya çalışmamalıdır. Bu tür "yola bağımlı" davranışın belirli ve yaygın bir nedeni aşağıda "Özellikleri tanımlarken bağımlılıkları açıkça denetle" başlığı altında açıklanmıştır.

Benzersiz bağlantı noktası ilişkilendirme kuralı

Vcpkg sisteminin tamamında, kullanıcının eşzamanlı olarak kullanması beklenen iki bağlantı noktası aynı dosyayı sağlamaz. Bir port, zaten başka bir port tarafından sağlanan bir dosyayı yüklemeye çalışırsa yükleme başarısız olur. Bir port, üst bilgi için son derece genel bir ad kullanmak istiyorsa, bu üst bilgileri include yerine bir alt dizine yerleştirmelidir.

Bu özellik, kayıt defterindeki tüm bağlantı noktalarını yüklemeye çalışan sürekli tümleştirme çalışmaları tarafından düzenli olarak denetlenir ve eğer iki bağlantı noktası aynı dosyayı sağlarsa FILE_CONFLICTS ile başarısız olur.

Resmi olmayan bir namespace'e CMake dışa aktarmalarını ekleyin.

Vcpkg için ideal olan temel tasarım, kullanıcılar için "kilitleme" oluşturmamaktır. Derleme sisteminde, sistemdeki bir kitaplığa veya vcpkg'den gelen bir kitaplığa bağımlılık arasında fark olmamalıdır. Bu amaçla, üst akışların vcpkg ile çakışmadan kendi resmi CMake dışa aktarımlarını eklemesine izin vermek için mevcut kitaplıklara "yaygın adlarla" CMake dışa aktarımları veya hedefleri eklemekten kaçınıyoruz.

Bu amaçla, ana kütüphanede olmayan ve bağlantı noktasının dışarı aktardığı tüm CMake yapılandırmalarının ön eki unofficial- olmalıdır. Ek hedeflerin hepsi unofficial::<port>:: ad alanında olmalıdır.

Bu, kullanıcının aşağıdakileri görmesi gerektiği anlamına gelir:

• find_package(unofficial-<port> CONFIG) vcpkg'e özgü pakete ulaşmanın bir yolu olarak
• unofficial::<port>::<target> bu bağlantı noktasından dışarı aktarılan bir hedef olarak.

Örnekler:

• brotli, unofficial-brotli hedefini üreten unofficial::brotli::brotli paketini oluşturur.

Telif hakkı dosyasını yükleme

Her bağlantı noktası, copyright klasöründe ${CURRENT_PACKAGES_DIR}/share/${PORT} adlı bir dosya sağlamalıdır. Bir paketin lisans içeriği kaynak dosyalarında mevcutsa, ilgili dosya vcpkg_install_copyright() çağrısıyla oluşturulmalıdır. vcpkg_install_copyright ayrıca gerekirse birden çok telif hakkı dosyasını paketlemektedir.

vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

Bu dosyayı el ile oluşturmak için daha eski bir yöntem, CMake'in file yerleşik komutudur. Yeni bağlantı noktaları için vcpkg_install_copyright tercih edilir, ancak yine de izin verilir.

file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)

Yukarı akış kaynak dosyalarındaki lisans içeriği metin biçiminde değilse (örn. PDF dosyası), copyright kullanıcının lisans gereksinimlerini nasıl bulabileceğine ilişkin bir açıklama içermelidir. Mümkünse, kullanıcıların güncel olup olmadığını denetleyebilmesi için bunu gösteren özgün kaynak dosyalarına bir bağlantı da içermelidir.

file(WRITE "${CURRENT_PACKAGES_DIR}/share/${PORT}/copyright" [[As of 2023-07-25, according to
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/README.md#end-user-license-agreement
this software is bound by the "SOFTWARE DEVELOPMENT KIT LICENSE AGREEMENT" PDF located at
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/ADL%20SDK%20EULA.pdf
]])

Bağlantı noktalarında sürüm kısıtlamaları

Bağlantı noktaları içindeki sürüm kısıtlamaları, bileşenlerin bağımsız gelişimini engelleyebileceğinden genellikle kaçınılmalıdır. Bu tür kısıtlamaların eklenmesine yalnızca, belirli önceki sürümlerle kanıtlanmış uyumsuzluk gibi iyi belgelenmiş bir gerekçe olduğunda izin verilebilir. Bu kısıtlamalar yalnızca bağımsız bileşenlerle eşitliği korumak için kullanılmamalıdır.

içindeki MAYBE_UNUSED_VARIABLES değişkenler en az bir yapılandırmaya uygulanmalıdır

CMake yapılandırma adımı sırasında uyarıyı susturmak için yeni MAYBE_UNUSED_VARIABLES bir değişken eklerken, yeni değişkenin ne zaman uygulandığını açıklayan bir açıklama eklemeniz gerekir. Bir değişken herhangi bir yapılandırmada geçerli değilse, büyük olasılıkla temel alınan bir hata (örneğin, yanlış yazılmış değişken adı) vardır ve bu değişkenin eklenmesi derleme üzerinde gerçek bir etkiye sahip değildir.

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  FEATURES
    windowsfeature WINDOWS_OPTION
)

vcpkg_cmake_configure(
  SOURCE_PATH "${SOURCE_PATH}"
  OPTIONS
    ${FEATURE_OPTIONS}
  MAYBE_UNUSED_VARIABLES
    WINDOWS_OPTION # Applies only on Windows
)

Özellikler

Alternatifleri uygulamak için özellikleri kullanmayın

Özellikler, ek işlevsellik olarak ele alınmalıdır. Eğer port[featureA] yüklenirse ve port[featureB] yüklenirse, o zaman port[featureA,featureB] yüklenmelidir. Ayrıca, ikinci bir bağlantı noktası [featureA]'a ve üçüncü bir bağlantı noktası [featureB]'e bağımlıysa, hem ikinci hem de üçüncü bağlantı noktalarının yüklenmesi, bağımlılıklarının karşılandığından emin olmalıdır.

Bu durumdaki kitaplıklar, vcpkg'de belirtilen mevcut seçeneklerden birini seçmelidir ve farklı bir ayar isteyen kullanıcıların şu anda katman bağlantı noktaları kullanması gerekir.

Geriye dönük uyumluluk nedeniyle bugünün şartlarında kabul etmeyeceğimiz mevcut örnekler:

• libgit2, libziptümlerinde open62541 TLS veya şifreleme arka ucu seçme özellikleri vardır. curl farklı şifreleme arka uç seçeneklerine sahiptir, ancak çalışma zamanında bunlar arasında seçim yapılmasına izin verir, yani yukarıdaki tenet korunur.
• darknet, opencv2opencv3, bağımlılıkları için hangi opencv sürümünün kullanılacağını denetleyen özellikler içerir.

Bir özellik önizleme veya beta işlevselliğiyle etkileşime geçebilir

Yukarıdakilere bakılmaksızın, önizleme işlevselliğinin önizleme dışı işlevselliği kesintiye uğratmama olasılığı yüksek olan bir önizleme dalı veya benzer bir dal varsa (örneğin, API kaldırma yok), bu ayarı modellemek için bir özellik kabul edilebilir.

Örnekler:

• Azure SDK'larının (formdaki azure-Xxx) bir public-preview özelliği vardır.
• imgui , genel numaralı sürümlerinin her birine eklenmiş bir birleştirme işlemesi kullanan önizleme yerleştirme dalını devreye alan bir experimental-docking özelliğe sahiptir.

Varsayılan özellikler API eklememelidir

Uyarı

Yukarı akış derleme sistemi tarafından varsayılan olarak etkinleştirilen bir özellik, özelliğin girişlere default-features eklenmesi gerektiği anlamına gelmez. default-features'in amacı, yukarı akış tarafından alınan kararları modellemek değil, klasik mod kullanıcılarına kolaylık sağlamaktır.

Makul düzeyde işlevsel bir kitaplığın yüklenmesini sağlamak için varsayılan özellikler, kitaplığı kullandıklarının farkında olmayan müşteriler hedeflenerek tasarlanmıştır. Kitaplık kullandıklarını bilmiyorlarsa, özellikleri listelemeyi bilemezler. Örneğin, libarchive sıkıştırma algoritmalarını etkinleştiren özellikleri mevcut bir genel arabirimde kullanıma sunar; bu tür özelliklerden herhangi biri olmadan oluşturulmuşsa kitaplığın yardımcı programı olmayabilir.

Müşteriler burada hem paket grafiğini kullanan kullanıcı projelerini hem de bu grafın içindeki alt bağımlı bağlantı noktalarını içerir. Her ikisi de bağımlılık gereksinimlerini aynı özellik arabirimi aracılığıyla ifade eder.

Varsayılan özellikleri devre dışı bırakmak karmaşık olduğundan, bir özelliğin varsayılan olarak açık olması gerekip gerekmediğini dikkatle göz önünde bulundurun.

Geçişli bağımlılık için varsayılan özellikleri devre dışı bırakmak için:

• Bağlantı noktasına bağımlı olan her müşteri, bağımlılık bildiriminde "default-features": false kullanarak varsayılan özelliklerini devre dışı bırakmalıdır.
• Üst düzey proje, geçişli bağımlılığı da doğrudan adlandırmalıdır; bunun için ya bildiriminde vcpkg install ile ya da "default-features": false komut satırında [core] ile belirtmelidir.

Varsayılan özelliklerin devre dışı bırakılması, başka bir müşterinin bu özelliklerden herhangi birini açıkça istemesini engellemez.

Bu ilke için API, kitaplık arabirimleri, yürütülebilir komut satırı arabirimleri ve diğer ikili arabirimler de dahil olmak üzere tüketicilere sunulan herhangi bir arabirimdir. Bir özellik, mevcut bir API'nin arkasına davranış eklediğinde varsayılan olarak etkinleştirilebilir; örneğin, mevcut bir genel arabirim aracılığıyla ek sıkıştırma algoritmalarının desteklenmesi.

vcpkg'nin küratörlü kaydında, bir özellik API ekliyorsa varsayılan olarak kapalı olmalıdır. Emin değilseniz, bir özelliği varsayılan olarak işaretlemeyin.

Yayımlanan arabirimlerdeki alternatifleri denetlemek için özellikleri kullanmayın

Eğer bir portun tüketicisi yalnızca o portun temel işlevselliğine dayanıyorsa, büyük olasılıkla özelliği açmak onları etkilememelidir. Tüketici tarafından doğrudan kontrol edilmeyen alternatifler söz konusu olduğunda, bu ayarlar /std:c++17 / -std=c++17 gibi derleyici ayarları tarafından denetlendiğinde, bu daha da önemlidir.

Geriye dönük uyumluluk nedeniyle bugünün şartlarında kabul etmeyeceğimiz mevcut örnekler:

• redis-plus-plus[cxx17] bir polyfill'i kontrol eder, ancak ayarı yüklü ağaca entegre etmez.
• ace[wchar] tüm API'lerin const wchar_t* yerine const char* kabul edilmesi için değişir.

Bir özellik, yüklü ağaçta yerleşik olması şartıyla polifill'leri takma adlarla değiştirebilir.

Yukarıdakilere bakılmaksızın, modüller şu koşullarda polyfill desteğini kaldırabilir:

1. Özelliğin açılması, polifill'leri çok doldurulmuş varlığın diğer adlarına dönüştürür
2. Polyfill'in durumu yüklenen başlık dosyalarına dahil edilir, böylece ABI uyuşmazlığı nedeniyle çalışma zamanı hatalarının olması pek olası değildir.
3. Bağlantı noktası tüketicisinin her iki modda da çalışan kod yazması mümkündür; örneğin, polifill uygulanmış veya uygulanmamış bir typedef kullanarak

Örnek:

• abseil[cxx17]veya yerine absl::string_viewgeçerstd::string_view; düzeltme eki, pişirme gereksinimini uygular.

Önerilen çözümler

Altındaki alternatiflerin açıklanması kritik önem taşıyorsa, kullanıcıya port'u özel bir havuza nasıl kopyalayacakları konusunda talimat vermek için derleme zamanında iletiler sağlamanızı öneririz.

set(USING_DOG 0)
message(STATUS "This version of LibContoso uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")

Yapı teknikleri

Proje ile birlikte gelen bağımlılıkları kullanmayın

Kullanıcıların vcpkg aracılığıyla bunları seçip güncelleştirebilmesi için bağımlılıkları ayrı olarak paketlemeyi tercih edin. Projeye dahil edilen bağımlılıklar çeşitli zorluklara neden olabilir:

• Güncelleştirme zorluğu: Güvenlik düzeltmeleri uygulanırken de dahil olmak üzere projeye dahil edilmiş bağımlılıkları izlemek ve güncelleştirmek zordur.
• Simge çakışmaları: Projeye dahil edilen bağımlılık, bağımlılığın başka bir sürümüyle aynı simgeleri tanımlayabilir ve çalışma zamanı hatalarına veya tanımlanmamış davranışa neden olabilir.
• Lisans uyumluluğu: Projeye dahil edilen bağımlılıklar lisans gereksinimlerini gizleyebilir veya lisans uyumluluğu sorunları oluşturabilir.
• Daha fazla bakım: Vendorlanan bağımlılıkların yukarı akış sürümleriyle eşitlenmiş tutulması bakım çalışmalarını artırır ve işi portlar arasında çoğaltabilir.

Bu nedenlerle, mümkün olduğunda bağımlılıkları satıcıdan bağımsız hâle getirin. Vendor bağımlılıkları bir kullanıcının bağlama alanına sunulmamalıdır.

Bağlantı etki alanı, çalışma zamanında birbirine göre çözümlenebilen simge kümesidir. Windows'ta her DLL'nin genel olarak kendi bağlantı etki alanı vardır. İşlem genelinde sembol tablosu olan platformlarda, bağlantı etki alanı genellikle tüm işlemi içerir.

Bir bileşen, gömülü bağımlılığını vcpkg aracılığıyla seçilen bir bağımlılıkla aynı bağlantı etki alanında görünür hâle getirirse, her iki kopya da aynı simgeleri tanımlayabilir. Bu, Tek Tanım Kuralı'nı ihlal eder ve çalışma zamanı hatalarına veya tanımsız davranışlara neden olabilir. Sorun yalnızca iki sürüm uyumsuz olacak kadar farklı olduğunda görünebilir.

Paketle gelen bir bağımlılığa yalnızca alt akış portları ve kullanıcı uygulamaları tarafından kullanılan bağlantı etki alanlarından tamamen yalıtıldığında izin verilir. Örneğin, aşağı akış ikili dosyaları araca bağlanmıyorsa ve bağımlılığın sembolleri bağlantı alanlarına giremiyorsa, yalnızca konak derleme aracı statik olarak bağlı bir bağımlılık içerebilir.

CMake kullanmayı tercih edin

Birden çok derleme sistemi kullanılabilir olduğunda, CMake kullanmayı tercih edin. Ayrıca, uygun olduğunda, file(GLOB) yönergelerini kullanarak alternatif derleme sistemlerini CMake'e yeniden yazmak daha kolay ve daha bakımı kolay olabilir.

Örnekler: abseil

Ya statik ya da paylaşılan ikili dosyaları seçin.

CMake kitaplıkları oluştururken, vcpkg_cmake_configure() kullanıcının istenen varyantı temelinde BUILD_SHARED_LIBS için doğru değeri geçirir.

alternatif yapılandırma parametrelerini kullanarak string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" ...)hesaplayabilirsiniz.

# portfile.cmake

string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)

vcpkg_cmake_configure(
    SOURCE_PATH ${SOURCE_PATH}
    OPTIONS
        -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
        -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
)

Bir kitaplık, derleme değişkenini seçmek için yapılandırma seçenekleri sunmuyorsa derlemeye düzeltme eki uygulanmalıdır. Derlemeye düzeltme eki eklerken her zaman portun gelecekteki bakım yapılabilirliğini en üst düzeye çıkarmaya çalışmanız gerekir. Bu genellikle eldeki sorunu düzeltmek için dokunulması gereken satır sayısını en aza indirmek anlamına gelir.

Örnek: İstenmeyen çeşitlemeler oluşturmamak için CMake kitaplığına düzeltme eki uygulama

Örneğin, CMake tabanlı bir kütüphaneye düzeltme uygulanırken, istenmeyen hedeflere EXCLUDE_FROM_ALL eklemek ve install(TARGETS ...) çağrısını bir if(BUILD_SHARED_LIBS) içinde sarmalamak yeterli olabilir. Bu, istenmeyen değişkenden bahseden her satırı sarmalamaktan veya silmekten daha kısa olacaktır.

Aşağıdaki içeriklere sahip bir proje CMakeLists.txt için:

add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)

install(TARGETS contoso contoso_static EXPORT ContosoTargets)

install(EXPORT ContosoTargets
  FILE ContosoTargets
  NAMESPACE contoso::
  DESTINATION share/contoso)

install(TARGETS) Satırı, istenmeyen hedefi de varsayılan derlemenin dışında tutan koşullu bir blokla değiştirin:

add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)

if(BUILD_SHARED_LIBS)
  set_target_properties(contoso_static PROPERTIES EXCLUDE_FROM_ALL 1)
  install(TARGETS contoso EXPORT ContosoTargets)
else()
  set_target_properties(contoso PROPERTIES EXCLUDE_FROM_ALL 1)
  install(TARGETS contoso_static EXPORT ContosoTargets)
endif()

install(EXPORT ContosoTargets
  FILE ContosoTargets
  NAMESPACE contoso::
  DESTINATION share/contoso)

Özellikleri tanımlarken bağımlılıkları açıkça kontrol edin

İsteğe bağlı bir bağımlılığı yakalayan bir özellik tanımlarken, özellik açıkça etkinleştirilmediğinde bağımlılığın yanlışlıkla kullanılmayacağından emin olun.

set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF)
if ("zlib" IN_LIST FEATURES)
  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
  set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON)
endif()

vcpkg_cmake_configure(
  SOURCE_PATH ${SOURCE_PATH}
  OPTIONS
    -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
    -DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_FIND_PACKAGE_ZLIB}
)

vcpkg_check_features() kullanılarak aşağıdaki kod parçacığı eşdeğerdir.

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  FEATURES
    "zlib"    CMAKE_REQUIRE_FIND_PACKAGE_ZLIB
  INVERTED_FEATURES
    "zlib"    CMAKE_DISABLE_FIND_PACKAGE_ZLIB
)

vcpkg_cmake_configure(
    SOURCE_PATH ${SOURCE_PATH}
    OPTIONS
      ${FEATURE_OPTIONS}
)

ZLIB kod parçacığında büyük/küçük harfe duyarlıdır. Daha fazla bilgi için CMAKE_DISABLE_FIND_PACKAGE_<PackageName> ve CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> belgelerine bakın.

Çakışan kitaplıkları manual-link dizinine yerleştirin.

lib veya .a içine yüklenen, .so, .dylib, .lib ya da debug/lib dosyası gibi bir bağlayıcı girdi dosyası, aşağıdakilerden herhangi birini yaparsa çakışan olarak kabul edilir:

• Tanımlar main.
• Tanımlar malloc.
• Diğer kitaplıklarda da tanımlanan simgeleri tanımlar.

Bazı bağlayıcı giriş dosyaları, tüketicilerin başka bir yerde tanımlayabilecekleri veya edinebilecekleri sembollerin yerine geçen kasıtlı olarak dar kapsamlı ikameler sağlar. Örneğin, Google Test, yazarlarının kendi giriş noktalarını tanımlamak yerine bunu kullanmayı tercih ettiği test yürütülebilir dosyaları için gtest-main.libmain sağlar.

Çakışan bağlayıcı giriş dosyalarını, derleme sistemleri kitaplık dizinindeki dosyaları otomatik olarak bağladığında bunları seçmemesi için lib/manual-link veya debug/lib/manual-link içine yerleştirin. Windows DLL'leri debug/bin veya bin içinde kalır; açık bağlama gerektiğinde içe aktarma kitaplıkları manual-link içine yerleştirilmelidir. Tüketiciler bu dosyaların bağlanmasına açıkça onay vermelidir ve çakışan tanımlardan kaçınmaktan sorumludur. Bu özel durum, başka bir bileşenin alternatif sağlayıcılarını paketlemeye yönelik genel bir mekanizma değildir ve bağlayıcı giriş dosyasının manual-link içine taşınması, sembollerini tüketicinin bağlayıcı bağlamından yalıtmaz.

Önceden oluşturulmuş ikili dosyaları yükleme

Önceden oluşturulmuş (yalnızca ikili) yapıtları yükleyen portlara izin verilir, ancak yapıtların kullanıcıların vcpkg aracılığıyla bağımlılıkları seçmesini veya güncelleştirmesini engellememesi koşuluyla kesinlikle önerilmez. Kaynaktan derleme tercih edilir çünkü derleyiciyi ve bayrakları denetleyen vcpkg ayarlarına saygı gösterir.

Aşağıdaki koşulların tümünü karşılayan bağlantı noktalarını reddedeceğiz:

1. Kaynaktan oluşturmak yerine önceden oluşturulmuş ikili dosyaları yükleyin ve
2. Bu ikili dosyalar, küratörlü kayıt deposundaki diğer portlar tarafından sağlanan çalışma zamanı bağımlılıklarını içerir veya gerektirir ve
3. Yüklü yapıtlar, bu bağımlılıkları vcpkg aracılığıyla seçilen sürümleri de içerebilen bir bağlantı etki alanına maruz bırakır.

Bu birleşim, bağımlılık grafiğini, upstream prebuilt oluşturulduğunda kullanılan sürümlere etkili bir şekilde kilitler. vcpkg, openssl veya zlib gibi bir bağımlılığı güncelleştirirse, önceden oluşturulmuş ve kullanıcı tarafından seçilen sürümler aynı bağlantı etki alanında uyumsuz simgeler tanımlayabilir. Bu, Tek Tanım Kuralı ihlallerine, ABI uyumsuzluklarına veya eksik güvenlik güncelleştirmelerine neden olabilir.

Bir artifact, üst bağımlılığın onu açığa çıkarma niyetinde olup olmadığına bakılmaksızın, bir bağımlılık kullanıcının bağlantı alanında yer aldığında onu açığa çıkarır. Buna aşağıdakiler dahildir:

• İstemci tarafından bağlanabilir .lib, .a, .so, .dylib veya bağımlılığı kullanıcının bağlantı etki alanına getiren içe aktarma kitaplıkları.
• Diğer vcpkg portlarından sembollere, türlere veya makrolara başvuran (doğrudan veya satır içi/şablon kodu aracılığıyla) yüklü başlık dosyaları.
• Diğer vcpkg portlarını çağıran find_dependency() CMake yapılandırması veya Requires: pkg-config dosyaları yüklendi.

İzin verilen (ancak yine de önerilmez) senaryolar:

• Paketlenmiş bağımlılıkları yalıtmaları veya yalnızca yaygın sistem çalışma zamanı kitaplıklarına güvenmeleri koşuluyla, çıktıları tüketilen ancak bağımlı portlar tarafından karşı bağlanmayan, derleme sırasında kullanılan yalnızca ana sistemde kullanılan yardımcı araçlar.
• Paketlenmiş bağımlılıkları tamamen ayrı bağlantı etki alanlarında kalan ve kurulu başlık dosyalarında veya dışarı aktarılan arabirimlerde görünmeyen önceden oluşturulmuş kitaplıklar. Tek başına statik bağlama, bir bağımlılığı kullanıcının bağlantı etki alanından yalıtmaz.
• Kullanıcı koduna link edilmemiş sadece veri, firmware veya varlık paketleri.

Yasak örnekler:

• Özel bir kopyasını zlib statik olarak bağlayan ve simgelerini, vcpkg aracılığıyla seçilen zlib sürümünü de içerebilen bir bağlantı etki alanına sunan önceden oluşturulmuş bir kitaplık.
• Önceden oluşturulmuş ve belirli bir libfoo sürümüne karşı derlenmiş lib/libfoo.lib artı <zlib.h> içeren üst bilgileri yükleyen bir zlib; tüketiciler daha sonra uyumluluk bekleyerek libfoo ile bağlantı kurar.
• Önceden oluşturulmuş bir SDK, ikili dosyanın eski bir OpenSSL sürümünde derlendiği sırada find_dependency(OpenSSL) çağrısını yapan bir CMake paket dosyasını yükler.

Azaltmalar / alternatifler:

• Yukarı akış betiklerini kullanarak kaynaktan derleme sağlayın veya ince bir CMake sarmalayıcı ekleyin.
• Yukarı akıştan kaynak tabanlı bir sürüm veya yeniden üretilebilir derleme talimatları yayımlamasını isteyin; ayrıca portfile.cmake içindeki bir yoruma yukarı akış sorununu/PR’yi ekleyin.
• Bu kuralları karşılayamayan kuruluşa özgü ön derlemeler için yer katman üstü bağlantı noktası veya özel kayıt deposu kullanın.

Sürüm oluşturma

Alan için "version" yaygın kuralları izleyin

Yeni bir bağlantı noktası oluştururken paket yazarı tarafından kullanılan sürüm oluşturma kuralını izleyin. Bağlantı noktasını güncellerken, üst akım aksini belirtmediği sürece aynı konvansiyonu kullanmaya devam edin. Kurallarımızın tam açıklaması için sürüm oluşturma belgelerimize bakın.

Yukarı akış bir süredir yayın yayımlamadıysa en son değişiklikleri almak için bağlantı noktasının sürüm oluşturma düzenini version-date olarak değiştirmeyin. Bu commitler, üretime hazır olmayan değişiklikleri içerebilir. Bunun yerine yukarı akış deposundan yeni bir sürüm yayımlamasını isteyin.

Değiştirilen her bağlantı noktası için "port-version" alanını güncelleştirin

Bir bağlantı noktasını değiştiren her PR'nin bu bağlantı noktasının yeni bir sürümünü üretmesi gerekir. PR'ler squash ile birleştirilir, bu nedenle değiştirilen her portun sürümünü işleme veya gözden geçirme düzeltmesi başına değil PR başına bir kez güncelleştirin.

Yukarı akış sürümü değişmediyse "port-version" alanını artırın. Yukarı akış sürümü değiştiyse, alanı kaldırarak veya "port-version" olarak ayarlayarak 0 değerini sıfıra sıfırlayın.

Örneğin:

• Zlib'in paket sürümü şu anda 1.2.1 ve açık bir "port-version" yoktur (bu, bir "port-version" değerine yani 0'e eşdeğerdir).
• Yanlış telif hakkı dosyasının dağıtıldığını keşfettiniz ve bunu portfile dosyasında düzelttiniz.
• Bildirim dosyasındaki "port-version" alanı olarak 1güncelleştirmeniz gerekir.

Daha fazla bilgi için sürüm oluşturma belgelerine bakın.

Değiştirilen her port için versions/ içindeki sürüm dosyalarını güncelleyin

vcpkg, sürüm oluşturma özelliğini desteklemek için bir dizi meta veri dosyası kullanır. Bu dosyalar aşağıdaki konumlarda bulunur:

• ${VCPKG_ROOT}/versions/baseline.json, (bu dosya tüm bağlantı noktaları için ortaktır) ve
• ${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json (bağlantı noktası başına bir tane).

Örneğin, zlib için ilgili dosyalar şunlardır:

• ${VCPKG_ROOT}/versions/baseline.json
• ${VCPKG_ROOT}/versions/z-/zlib.json

Bir PR'deki değiştirilen her port için, sürüm dosyalarını nihai Git ağacını kaydetmek için güncelleştirin. Gözden geçirme sırasında başka değişiklikler yaparsanız, birleştirilmemiş sürüm girdisini yenilemek için vcpkg x-add-version <port-name> --overwrite-version komutunu çalıştırın

"port-version" değerini yeniden artırmadan

Bu dosyaları güncelleştirmek için önerilen yöntem komutunu çalıştırmaktır x-add-version ; örneğin:

vcpkg x-add-version zlib

Aynı anda birden çok bağlantı noktasını güncelleştiriyorsanız şunu çalıştırabilirsiniz:

vcpkg x-add-version --all

değiştirilen tüm bağlantı noktalarının dosyalarını aynı anda güncelleştirmek için.

Daha fazla bilgi için Sürüm oluşturma başvurusu ve Kayıt Defterleri makalelerine bakın.

Güncellemeler

vcpkg, dağıttığımız bileşenlerin nihai sahipleri değil, bir paketleme çözümüdür. Bazı durumlarda, bileşenlerin platformlarla uyumluluğunu veya bileşenlerin birbiriyle uyumluluğunu geliştirmek için düzeltme ekleri uygulamamız gerekir.

• Şu düzeltme eklerinden kaçınmak istiyoruz:
  • üst kaynak aynı fikirde değil
  • güvenlik açıklarına veya kilitlenmelere neden olabilir
  • Yukarı akış sürüm güncelleştirmelerinde bakım yapamaz hale geldik
  • vcpkg deposunun kendisiyle lisans karmaşasına neden olabilecek kadar büyük

Upstream bildirimi ve bekleme süreleri

Üst akış sorumluları, bileşenlerinin davranışının nihai belirleyicileridir. vcpkg bakımcıları, upstream ile ilgili düzeltme ekleri ve yeni port gönderimlerindeki yapay zeka kod inceleme araçları tarafından tanımlanan hatalar için upstream’e bildirim yapılmasını gerektirir.

upstream ile ilgili yamalar

Bir düzeltme ekinin upstream tarafından yararlı olma ihtimali varsa, vcpkg bakımcıları düzeltme ekinin içeriği hakkında upstream'in bilgilendirilmesini gerektirir. Yukarı akışla ilgili olmayan vcpkg'ye özgü davranış uygulayan yamalar (örneğin, bir bağımlılığı vendordan ayırma) bildirim gerektirmez.

Yukarı akışın yamayla aynı fikirde olmadığı durumlardan kaçınmak için, vcpkg bakımcıları bu tür düzeltme eklerini uygulamadan önce yukarı akış bildiriminden sonra en az 30 gün bekler.

vcpkg bakımcıları, değişikliğin doğru olduğundan emin olmaları durumunda bu bekleme süresini atlar. Örnek olarak yüksek güvenilirlikli yamalar arasında şunlar yer alır, ancak bunlarla sınırlı değildir:

• Yukarı akışın düzeltme eki olarak kabulü (örneğin, bir çekme isteği yukarı akışından belirli bir değişikliğin geri aktarılması birleştirildi).
• Eksik olan #include işaretleri ekleniyor.
• Küçük ve açık ürün kodu hatalarının düzeltilmesi (örneğin, başlatılmamış bir değişkeni başlatmak).
• Derlemedeki testler veya örnekler gibi ilgisiz vcpkg bileşenlerini devre dışı bırakma.

Yeni portlarda yapay zeka tarafından tanımlanan hatalar

Özenle seçilmiş kayıt deposu, bilinen şekilde istismar edilebilir kodların dağıtımını önlemeyi amaçlar, ancak vcpkg bakımcıları her bileşenin kaynak kodunu kapsamlı olarak denetleyemez. Yapay zeka kodu gözden geçirme bulguları tek başına yukarı akış kodunun savunmasız olduğuna ilişkin son bir belirleme değildir.

Yapay zeka kodu gözden geçirme araçları yeni bir port gönderiminin gözden geçirilmesi sırasında bir hata tanımladığında, vcpkg bakımcıları, yararlanılabilir olabilecek hatalar için projenin güvenlik raporlama sürecini izleyerek hatanın upstream'e bildirilmesini gerektirir. Bu gereksinim, tespit, portun yama uygulamadığı yukarı akış koduyla ilgili olsa bile geçerlidir.

• Upstream bildirilen davranışın bir hata olmadığını belirlerse, vcpkg bakımcıları bu belirlemeyi nihai olarak kabul eder ve bu bulgu temelinde yeni port gönderimini reddetmez.
• Yukarı akış hatayı düzeltirse, vcpkg bakımcıları düzeltme eki uygulama ilkesine ve yeni portlar için diğer gereksinimlere tabi olarak sabit sürümü veya yukarı akış onaylı bir düzeltme ekini kabul eder.
• Yukarı akış, hatanın bildirilmesinden sonraki 30 gün içinde yanıt vermezse vcpkg bakımcıları varsayılan olarak YZ bulgusunu kötüye kullanılabilir bir sorun olarak kabul eder ve yeni port gönderimini kapatır.

Düzeltme eki bekleme süresine yönelik yüksek güvenilirlikli özel durumlar, bu hata raporlama gereksinimini veya yukarı akış yanıtı gereğini ortadan kaldırmaz.

Yama yapma yerine seçenekleri tercih edin

Bir çağrıda vcpkg_configure_xyz() üzerinden seçenekleri ayarlamak, ayarları doğrudan yamalamaya tercih edilir.

Düzeltme eki uygulamaktan kaçınmanıza olanak sağlayan yaygın seçenekler:

• [MSBUILD] <PropertyGroup> proje dosyasının içindeki ayarlar parametreler aracılığıyla /p: geçersiz kılınabilir
• [CMAKE] CMake betiklerindeki find_package(XYz) çağrıları, şu aracılığıyla devre dışı bırakılabilir: -DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON
• [CMAKE] Önbellek değişkenleri (set(VAR "value" CACHE STRING "Documentation") veya option(VAR "Documentation" "Default Value") olarak bildirilenler) komut satırında -DVAR:STRING=Foo olarak geçilerek kolayca geçersiz kılınabilir. Parametrenin FORCE öğesine set()geçirilip geçirilmediği önemli bir özel durumdur. Daha fazla bilgi için CMake belgelerine set bakın

Onaylanan düzeltme eklerini bağlantı noktasında denetlemek yerine indirmeyi tercih edin

Onaylanmış veya birleştirilmiş bir yama üst kaynak commit’inden alınabiliyorsa, porta commit etmek yerine indirip uygulayın. Bu işlem şu nedenlerle tercih edilir:

• upstream’in yama değişikliklerini kabul ettiğini onaylar.
• Sorumluluğu sürecin önceki aşamalarına kaydırarak gözden geçirme işlemini basitleştirir.
• Düzeltme ekini kullanmayan kullanıcılar için vcpkg deposu boyutunu küçültür.
• vcpkg deposuyla lisans çakışmalarını önler.

Düzeltme eklerini, içeriği değişebilen çekme isteği veya birleştirme isteği fark URL'lerinden değil, yalnızca tam işleme kimliğine sabitlenmiş URL'lerden indirin. GitHub veya GitLab'den bir commit yaması indirirken URL'nin sonuna ?full_index=1 ekleyin. Bu parametre farkta tam nesne kimlikleri istemektedir; değiştirilebilir bir URL'yi değiştirilemez yapmaz.

Örneğin:

https://github.com/linux-audit/audit-userspace/commit/f8e9bc5914d715cdacb2edc938ab339d5094d017.patch?full_index=1

Düzeltme eki uygulamayı değerleri geçersiz kılmaya tercih edin VCPKG_<VARIABLE>

ön ekli VCPKG_<VARIABLE> bazı değişkenlerin eşdeğeri CMAKE_<VARIABLE>vardır. Ancak, bunların tümü iç paket derlemesine geçirilmiyor (bkz. uygulama: Windows araç zinciri).

Aşağıdaki örneği inceleyin:

set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")

vcpkg'nin yerleşik araç zincirleri kullanılarak bu işe yarar çünkü VCPKG_<LANG>_FLAGS değeri uygun CMAKE_<LANG>_FLAGS değişkene iletilir. Ancak, 'nin değişkenlerini tanımayan vcpkgözel bir araç zinciri bunları iletmez.

Bu nedenle, CMAKE_<LANG>_FLAGS ayarlanırken derleme sistemine doğrudan düzeltme eki uygulamak tercih edilir.

Yamaları minimize etme

Bir kitaplıkta değişiklik yaparken son farkı en aza indirmek için çaba gösterin. Bu, bir bölgeyi etkileyen değişiklikler yaparken yukarı akış kaynak kodunu yeniden biçimlendirmemeniz gerektiği anlamına gelir. Koşulluyu devre dışı bırakırken, koşula AND FALSE veya && 0 eklemek, koşulun her satırını silmekten daha iyidir. Büyük bir bölgenin devre dışı bırakılması gerekiyorsa, düzeltme ekindeki her satırı silmek yerine, bölgenin etrafına if(0) veya #if 0 eklemek daha kısadır.

Port eskiyse ve portu daha yeni bir sürüme güncellemek aynı sorunu çözecekse, düzeltme eki eklemeyin. vcpkg, eski sürümlere düzeltme eki uygulama yerine bağlantı noktalarını güncelleştirmeyi tercih eder.

Bu, vcpkg deposunun boyutunun aşağıda tutulmasına yardımcı olur ve düzeltme ekinin gelecekteki kod sürümlerine uygulanma olasılığını artırır.

Düzeltme eklerinde özellik uygulamayın

vcpkg'de düzeltme eki uygulamanın amacı, derleyiciler, kitaplıklar ve platformlarla uyumluluğu etkinleştirmektir. Doğru Açık Kaynak yordamını (Sorun/PR/vb. gönderme) takip etmek yerine yeni özellikler uygulamak değildir.

Testleri/belgeleri/örnekleri varsayılan olarak oluşturmayın

Yeni bir port gönderirken, BUILD_TESTS, WITH_TESTS veya POCO_ENABLE_SAMPLES gibi seçenekleri kontrol edin ve ek ikili dosyaların devre dışı bırakıldığından emin olun. Bu, ortalama kullanıcının derleme sürelerini ve bağımlılıklarını en aza indirir.

İsteğe bağlı olarak, testleri oluşturmayı sağlayan bir test özellik ekleyebilirsiniz, ancak bu listede olmamalıdır Default-Features .

Kitaplığın mevcut kullanıcılarının vcpkg'ye geçiş yapmasını sağlama

Eklemeyin CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS

Kitaplığın yazarı zaten kullanmıyorsa, C++ şablonlarıyla kötü etkileşime girip belirli derleyici özelliklerini bozabileceğinden bu CMake işlevini kullanmamalıyız. .def dosyası sağlamayan ve __declspec() bildirimleri kullanmayan kitaplıklar yalnızca Windows için paylaşılan derlemeleri desteklemez ve şu şekilde işaretlenmelidir:

if(VCPKG_TARGET_IS_WINDOWS)
    vcpkg_check_linkage(ONLY_STATIC_LIBRARY)
endif()

Yukarı akış tarafından verilen adların dışındaki ikili dosyaları yeniden adlandırmayın

Başka bir deyişle, yukarı akış kitaplığının yayın ve hata ayıklamada farklı adları varsa (libx ve libxd), hata ayıklama kitaplığı olarak yeniden adlandırılmamalıdır libx. Tam tersi, bağlı bulunduğumuz kütüphanenin sürüm ve hata ayıklamada aynı adı varsa yeni bir isim eklememeliyiz.

Önemli uyarı:

• Statik ve paylaşılan varyantlar genellikle ortak bir şema olarak yeniden adlandırılmalıdır. Bu, tüketicilerin ortak bir ad kullanmasını ve aşağı akış bağlantısından bilgisiz olmasını sağlar. Bu güvenlidir çünkü her seferinde yalnızca bir tane kullanılabilir hale getiririz.

Bir kütüphane CMake tümleştirme dosyaları oluşturuyorsa (foo-config.cmake), yeniden adlandırma, yalnızca çıkış arşivlerini/LIB'leri doğrudan çağırmak yerine CMake derlemesine düzeltme eki uygulanarak yapılmalıdır (file(RENAME)).

Son olarak, Oluşturulan LIB'leri kırdığı için Windows'ta DLL dosyaları derleme sonrası hiçbir zaman yeniden adlandırılmamalıdır.

Bildirim

Bildirim dosyasının biçimlendirilmesi gerekir. Tüm bildirim dosyalarını biçimlendirmek için aşağıdaki komutu kullanın:

> vcpkg format-manifest --all

Üçüz

Şu anda topluluk dışı üçlü ekleme isteklerini kabul etmiyoruz. Topluluktan tam üçlü durumuna yükseltme öncelikli olarak donanımın bu üçlüleri test etme bütçesine bağlıdır ve kullanıcıların gerçekten kullandıklarının tam olarak test edilme olasılığını en üst düzeye çıkarmak için vcpkg tarafından gönderilen ölçümler tarafından yönlendirilir.

Topluluk üçlülerini şu durumlarda ekleyeceğiz:

• İnsanların bu topluluk üçlüsünü gerçekten kullanacakları gösterilmiştir ve
• Böyle bir üçlünün bozulmuş olduğunu bilmiyoruz.

Örneğin, yazar gerçekten böyle bir şey kullanacağını belirtmek yerine yalnızca "kümeyi tamamlamaya" çalıştığı için içine üçlü https://github.com/microsoft/vcpkg/pull/29034 eklemedik ve sonuçları yeniden konumlandırılabilir hale getirmek için patchelf çözümü oluşturulana kadar linux-dynamic eklemedik.

Yararlı uygulama notları

Portfile'lar Script Modunda çalıştırılır

'ler ve portfile.cmake'ler ortak bir söz dizimi ve temel CMake dil yapılarını (diğer adıyla "Betik Komutları") paylaşırkenCMakeLists.txt, portfile'lar "Betik Modu"nda, dosyalar ise CMakeLists.txt "Proje Modu"nda çalıştırılır. Bu iki mod arasındaki en önemli fark, "Betik Modu"nun "Araç Zinciri", "Dil" ve "Hedef" kavramlarına sahip olmamasıdır. Bu yapılara (ör. CMAKE_CXX_COMPILER, , CMAKE_EXECUTABLE_SUFFIXCMAKE_SYSTEM_NAME) bağlı olan betik komutları da dahil olmak üzere herhangi bir davranış doğru olmayacaktır.

Bağlantı noktası dosyaları, triplet dosyasında ayarlanan değişkenlere doğrudan erişime sahiptir, ancak CMakeLists.txts'ler değildir (genellikle bir çeviri gerçekleşir -- VCPKG_LIBRARY_LINKAGE ile BUILD_SHARED_LIBS arasında).

Portfiles tarafından çağrılan portfile'lar ve Project derlemeleri farklı işlemlerde çalıştırılır. Kavramsal:

+----------------------------+       +------------------------------------+
| CMake.exe                  |       | CMake.exe                          |
+----------------------------+       +------------------------------------+
| Triplet file               | ====> | Toolchain file                     |
| (x64-windows.cmake)        |       | (scripts/buildsystems/vcpkg.cmake) |
+----------------------------+       +------------------------------------+
| Portfile                   | ====> | CMakeLists.txt                     |
| (ports/foo/portfile.cmake) |       | (buildtrees/../CMakeLists.txt)     |
+----------------------------+       +------------------------------------+

Bir portfile içindeki konağı belirlemek için standart CMake değişkenleri uygundur (CMAKE_HOST_WIN32).

Bir portfile içindeki hedefi belirlemek için vcpkg üçlü değişkenleri kullanılmalıdır (VCPKG_CMAKE_SYSTEM_NAME).

Olası ayarların tam listesi için üçlü belgelerimize de bakın.