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.
• Başka bir pakete ait sembolleri ve tanımları yükleyin.
• 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 olarak başka bir portun yerini alan portlar. Ardıl bir proje.
• Platform çakışması olmayan bağlantı noktaları. Örneğin, Windows'u desteklemeyen bir Linux projesi için yalnızca Windows'ta çalışan bir yedek çözüm.
• Bu ilkeden önce gelen ve çok sayıda kullanıcı ve katkıda bulunanlara sahip portlar.

İ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 politikadan önce gelen ve belirgin bir şekilde çok sayıda kullanıcı ve katkıda bulunan kişiye 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 geçici olarak muaf tutulmayan mevcut bağlantı noktaları kayıt defterinden kaldırı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ş projeler kararlı ve etkin bir şekilde korunmalıdır

Küratörlü kayıt defterine paketlenmiş projeler aktif bakımda olmalıdır. Etkin olmayan projelerin bağlantı noktalarının listeden silinme ihtimali var.

Proje şu durumlarda etkin değil olarak kabul edilir:

• Bakımcıları projenin durdurulmuş olduğunu bildirdi.
• 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ı kabul edilen ve sık sık değişikliğe uğramayan temel projeler için istisnalar uygulanır. Örneğin: zlib.

Paketlenmiş projeler olgun olmalıdır

Seçilmiş kayıt defterinde paketlenen projeler olgunlaşmış olmalı ve vcpkg kullanıcıları tarafından kullanıma hazır olmalıdır. Kişisel kullanıma yönelik projeler özel kayıt defterlerine yayımlanmalıdır.

Bu ifadelerden biri doğruysa, bir proje, seçilen kayıt defteri için yeterince olgun kabul edilir:

• Projenin en az altı aylık bir sürümü var.
• Proje, en az altı aylık etkin kamusal geliştirmeyi gösterir.
• Proje, önceki gereksinimleri karşılayan başka bir projenin resmi bir bileşenidir. Örneğin, yeni bir Boost kitaplığı veya Qt bileşeni.
• Proje, başka bir kapasitedeki önceki gereksinimlere eşdeğer olgunluk gösterir.

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

• Proje arama motorlarında gösterilmez.
• Projenin sık sık yeniden adlandırmaları var.
• 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.

El değmemiş dosyalarda önemsiz değişikliklerden kaçının

Başka bir şekilde değiştirilmemiş bağlantı noktasında önemsiz değişiklikler yapmayın; örneğin: değişkenleri yeniden biçimlendirme, yeniden adlandırma veya yazım hatalarını düzeltme. Bir portun yüklemesinin çıktısını etkilemeyen herhangi bir değişiklik önemsiz olarak kabul edilir. Önemsiz değişiklikler, aksi takdirde daha iyi kullanılan işlem süresini tüketir.

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

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

Bağlantı noktasının adını bir arama altyapısında veya Repology gibi özel paket tarayıcılarında aramak ilgili projeye 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 seçilen kayıt defterindeki bağlantı noktasının adı için geçerlidir; paketlenmiş projenin adı ve içeriği bu ilkeye uymak için gerekli değildir.

Adıyla güçlü bir ilişki kurarak bir projeyi paketleyen portlar için istisnalar 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 projelerinin bağlantı noktaları için GitHub sahibi kabul edilebilir ve kesin 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, herhangi bir tekil projeyle kesin olarak ilişkilendirilmiyor.

Bir adın belirsiz olup olmadığını belirlemek için, bağlantı noktası adından C++ ve açık kaynak projeleri 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, bağlantı noktaları son yeniden adlandırmalarından bir yıl sonrasına kadar yeniden adlandırılamaz.

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ş.

Vcpkg ekibi, inceleme süreci sırasında pull request'inizi taslak haline dönüştürebilir. Genellikle, PR'nizi 'Gözden Geçirmeye Hazır' olarak işaretleme zamanını belirten açıklamalar veya kodunuzda değişiklik yapma isteğiyle birlikte gelir.

Etkin olmayan PR'leri kapatma

vcpkg ekibi, 60 günden uzun bir süre boyunca etkinliği olmayan çekme isteklerini (PR) kapatabilir.

Gözden geçirilebilir durumdaki çekme istekleri için geri sayım, vcpkg bakımcısının son değişiklik isteğinde bulunmasından veya açıklama istemesinden itibaren başlar. Katkıda bulunan tarafından 60 gün içinde herhangi bir işlem yapılmazsa, PR eski kabul edilir ve ekibin takdirine bağlı olarak kapatılabilir.

Ç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.

60 günden uzun süre etkin olmayan ve gözden geçirilebilir durumda olmayan PR'ler gözden geçirilmeden 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(), ARCHIVE ile, vcpkg_extract_source_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()
• PREFER_NINJA kaldırıldıktan sonra vcpkg_configure_cmake, vcpkg_cmake_configure() 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. Bağlantı noktası zaten başka bir dosya 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::brotli hedefini üreten unofficial-brotli paketini oluşturur.

Telif hakkı dosyasını yükleme

Her bağlantı noktası, ${CURRENT_PACKAGES_DIR}/share/${PORT} klasöründe copyright 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ı, projelerin 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 projelerle eşliğ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ış bir değişken adı) vardır ve bunun derleme üzerinde gerçek bir etkisi yoktur.

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  FEATURES
    windowsfeature WINDOWS_OPTION
)

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

Ö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.

Varsayılan özellikleri devre dışı bırakmak karmaşık olduğundan, bir özelliğin varsayılan olarak açık olup olmadığını dikkatle göz önünde bulundurmanız gerekir.

'Geçişli' tüketici olarak varsayılan bir özelliği devre dışı bırakmak için şunlar gerekir:

• Tüm müşteriler, komut satırındaki özellik listesi aracılığıyla "default-features": false veya dahil olmak üzere [core] varsayılan özellikleri açıkça devre dışı bırakır.
• Komut satırında geçişli bağımlılığı vcpkg install adlandırma veya üst düzey bildirimde doğrudan bağımlılık olarak adlandırma

vcpkg'nin seçilmiş kayıt defterinde özellik ek API'ler, yürütülebilir dosyalar veya diğer ikili dosyalar 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 için geçmişte mevcut olup bugün kabul etmeyeceğimiz ö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 char* yerine const wchar_t* 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

Kitaplıkların gömülü kopyalarını kullanmayın. Tüm bağımlılıklar, güncelleştirilebilmeleri ve korunabilmeleri için ayrı ayrı ayrılmalı ve paketlenmelidir.

vcpkg'nin güvenilir, tutarlı ve sürdürülebilir bir paket yönetim sistemi sağlama hedefleriyle uyumsuz olan sürdürülen bağımlılıklar, çeşitli zorluklara neden olur.

Güncelleştirmelerde Zorluk: Kitaplıkların ekli kopyaları, güvenlik düzeltme ekleri dahil olmak üzere güncelleştirmeleri yukarı akış projelerinden izlemeyi ve uygulamayı zorlaştırır. Bu, ekosistemde olası güvenlik risklerine ve güncel olmayan bağımlılıklara yol açar.

Sembol Çakışmaları: Birden çok paket aynı kitaplığın farklı sürümlerini içerdiğinde paketle gelen bağımlılıklar sembol çakışmalarına neden olabilir.

Örneğin: Paket A satıcıları Kitaplığı X (sürüm 1) ve Paket B satıcıları Kitaplığı X (sürüm 2) ise, her iki paketi birbirine bağlayan bir uygulama çakışan semboller nedeniyle çalışma zamanı hataları veya tanımsız davranışla karşılaşabilir.

Vcpkg, bağımlılıkları ayrı ayrı paketleyerek kitaplığın tek bir sürümünün tüm paketlerde kullanılmasını sağlayarak bu tür çakışmaları ortadan kaldırır.

Lisans uyumluluğu: Satıcı bağımlılıkları, katıştırılmış kitaplıkların lisansını belirsizleştirebilir, bu da lisans koşullarının ihlaline veya uyumluluk sorunlarının oluşmasına yol açabilir.

Artan Bakım Yükü: Satıcı bağımlılıklarının yukarı akış sürümleriyle eşitlenmiş durumda tutulması için el ile büyük çaba harcanması gerekir ve genellikle paketler arasında yinelenen çalışmalara yol açar.

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)

Yalnızca install(TARGETS) satırına düzeltme yapılması gerekir.

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.

Aşağıdakilerden birini yaparsa bir lib çakışıyor olarak kabul edilir:

• Tanımlamak main
• Malloc'ı tanımlayın
• Diğer kitaplıklarda da bildirilen simgeleri tanımlama

Uyumsuz kütüphaneler genellikle tasarımın bir parçasıdır ve hata olarak değerlendirilmez. Bazı derleme sistemleri lib dizinindeki her şeye bağlandığından, bunlar adlı manual-linkbir alt dizine taşınmalıdır.

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

Önceden oluşturulmuş (yalnızca ikili) yapıtları yükleyen port'lara izin verilir, ancak diğer port'ların sürümlerinin değiştirilmesini etkili bir şekilde engellemedikleri sürece şiddetle önerilmez. Kaynaktan derleme tercih edilir çünkü derleyiciyi veya bayrakları değiştiren tüm 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ın, seçilen kayıt defterindeki diğer bağlantı noktaları tarafından sağlanan (veya çalışma zamanında gerektiren) bağımlılıkları vardır ve
3. Yüklü yapıtlar vcpkg'nin yayımlanan bağlantı etki alanına girer; örneğin aşağı akış bağlantı noktalarının veya kullanıcı projelerinin bağlaması beklenen kitaplıkları/üst bilgileri/CMake veya pkg-config meta verilerini yüklerler.

Gerekçe: Bu birleşim, bağımlılık grafiğinin ABI'sini, yukarı akış önceden oluşturulduğunda kullanılan sürümlere etkili bir şekilde kilitler. vcpkg, önceden oluşturulmuş kütüphaneye karşı bağlantı kuran tüketiciler için ince ODR / ABI bozulması riski oluşturmadan, zlib, openssl veya benzer bağımlılıkları güvenli bir şekilde güncelleyemez ve kullanıcılar önemli güvenlik yamalarını kaçırabilir.

"Yayımlanan bağlantı etki alanına erişir" genellikle aşağıdakilerden herhangi biri anlamına gelir:

• Tüketicilerin bağlanması amaçlanan .lib, .a, .so veya .dylib import kitaplıklarının yüklenmesi.
• Diğer vcpkg bağlantı noktalarından sembollere, türlere veya makrolara başvuran (doğrudan veya satır içi/şablon kodu aracılığıyla) sevkiyat üst bilgileri.
• Diğer vcpkg portlarına find_dependency() / Requires: çağrısı yapan CMake config / pkg-config dosyaları yükleniyor.

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

• Yalnızca konak yardımcı araçları (yürütülebilir dosyalar), çıkışları tüketilen ancak bağımlılıkları özel olarak paketlemeleri veya yalnızca yaygın sistem çalışma zamanı kitaplıklarına güvenmeleri koşuluyla bağımlı bağlantı noktalarıyla bağlantılı olmayan derleme zamanında kullanılır.
• Tamamen kendine yeten, önceden derlenmiş kitaplıklar, tüm açık kaynak yazılım bağımlılıklarını statik olarak bağlar ve sembollerini veya türlerini yüklü üst bilgiler veya dışarı aktarılan arabirimler aracılığıyla kullanıma sunmaz (tüketiciler geçişli ABI'yi gözlemleyemez veya buna bağımlı olamaz).
• Kullanıcı koduna link edilmemiş sadece veri, firmware veya varlık paketleri.

Yasak örnekler:

• Ö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.

"port-version" Değiştirilen bağlantı noktalarının bildirim dosyasındaki alanı güncelleştirin

vcpkg, belirli bir bağlantı noktasının güncel olup olmadığını ve bağlantı noktasının davranışı her değiştiğinde değiştirilmesi gerektiğini belirlemek için bu alanı kullanır.

Standart uygulamamız, yukarı akış sürümünde değişiklik yapmayan bağlantı noktası değişiklikleri için "port-version" alanını kullanmak ve yukarı akış sürümüne bir güncelleme yapıldığında "port-version" alanını sıfıra sıfırlamaktır.

Ö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 bağlantı noktaları için sürüm dosyalarını versions/ 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 bağlantı noktasını her güncelleştirdiğinizde sürüm dosyalarını da güncelleştirmenizi bekliyoruz.

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

Yukarı akışla ilgili düzeltme ekleri için yukarı akış sahiplerine bildirme

Bir düzeltme ekinin yukarı akış tarafından yararlı olması mümkünse, yukarı akışa düzeltme ekinin içeriği bildirilmelidir. (Ana projeyle ilgili olmayan, vcpkg'ye özgü davranış uygulayan düzeltme ekleri (örneğin, bir bağımlılığın devendor edilmesi) bildirim gerektirmez.)

Üstyapının düzeltme ekine karşı çıkabileceği durumlardan kaçınmak için bu tür düzeltme eklerini uygulamak üzere en az 30 gün bekleyeceğiz.

Değişikliğin doğru olduğundan çok güvenirsek bu bekleme süresini atlarız. Ö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.

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

Onaylanan veya birleştirilmiş bir düzeltme eki dosyası yukarı akıştan alınabiliyorsa, bağlantı noktaları bunları indirmeyi denemeli ve bunları bağlantı noktası dosyalarının parçası olarak bulundurmak yerine uygulamalıdır. Bu işlem aşağıdaki nedenden dolayı tercih edilir:

• Upstream'in yama değişikliklerini kabul ettiğini onaylar.
• Sorumluluğun üst bölümlere kaydırılması, 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

SHA çakışmalarını önlemek için düzeltme ekleri kararlı bir uç noktadan indirilmelidir. GitHub ve GitLab'dan bir çekme isteği ya da bir işlem için düzeltme eki dosyaları indirilirken, ?full_index=1 parametresi indirme URL'sine eklenmelidir.

Örnekler:

• https://github.com/google/farmhash/pull/40.diff?full_index=1
• https://github.com/linux-audit/audit-userspace/commit/f8e9bc5914d715cdacb2edc938ab339d5094d017.patch?full_index=1
• https://gitlab.kitware.com/paraview/paraview/-/merge_requests/6375.diff?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.