Aracılığıyla paylaş

Bakımcı kılavuzu

Bu belgede, bağlantı noktası tarifi eklerken veya güncelleştirirken uygulamanız gereken ilkeler listelenir. Debian'ın İlke Kılavuzu, Homebrew Bakımcı Yönergeleri ve Homebrew'un Formül Yemek Kitabı rolüne hizmet etmek için tasarlanmıştır.

Genel kayıt defteri tasarım hedefleri

Geçerli temeldeki bağlantı noktaları aynı anda yüklenebilir olmalıdır

Sunduğumuz herhangi bir temeldeki kitaplıkların birleşiminin en azından bazı yapılandırmalarda birlikte çalışmak için test edildiğini, seçilen kayıt defterindeki kitaplıkların aşağı akış kullanıcılarını gösterebilmek istiyoruz. Bağlantı noktalarının birbirini dışlamalarına izin vermek, bu tür testler için gerekli derleme sayısı olarak 2^number_of_such_casesartacağı için bu tür yapılandırmaları test etme özelliğini bozar. Ayrıca, ek bağımlılıkların yüklenmesi her zaman "güvenli" olarak kabul edilir: Bir bağlantı noktasının veya son kullanıcının gereksinimlerinde bir bağımlılığın yüklenmediğini onaylaması için bir yol yoktur.

Kullanıcılar için böyle bir alternatif durumu temsil etmek istiyorsanız, bir kişinin seçilen kayıt defterinin sürekli tümleştirmesinde hiç derlenmemiş ek bağlantı noktaları eklemeye çalışmak yerine alternatif formu bir açıklamayla uygulayan bir katman bağlantı noktasıportfile.cmakeaçıklayabilirsiniz. Örneğin, bkz . glad@0.1.36.

Kayıt defterlerinin kullanıma sunulmasından önce, kaplama bağlantı noktalarını yazmayı kolaylaştırabilecek test edilmemiş birkaç bağlantı noktasını alternatif olarak kabul ettik. Kayıt defterleri, bu test edilmemiş bağlantı noktalarının, seçilen kayıt defterinde değişiklik yapmadan yayımlanmasına izin vermediğinden bu artık kabul edilmez.

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.

Çekme isteği yapısı

Bağlantı noktası başına ayrı çekme istekleri yapma

Mümkün olduğunda, değişiklikleri birden çok PR'ye ayırın. Bu, gözden geçirmelerini önemli ölçüde kolaylaştırır ve bir değişiklik kümesiyle ilgili sorunların diğer tüm değişiklikleri tutmasını önler.

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

Örneğin, portfiles içindeki değişkenleri yeniden biçimlendirmekten veya yeniden adlandırmaktan kaçının; aksi takdirde eldeki sorun için değiştirilmesi için bir neden yoktur. Ancak, çekme isteğinin birincil amacı (kitaplığı güncelleştirmek) için dosyayı değiştirmeniz gerekiyorsa, yazım hatalarını düzeltme gibi açıkça yararlı değişiklikler takdir edilir!

Diğer depolarda adları denetleme

Bağlantı noktası adları, bağlantı noktasının hangi paketi yüklediği konusunda belirsiz olmaya çalışmalıdır. İdeal olarak, bağlantı noktasının adını bir arama altyapısında aramak sizi hızlı bir şekilde ilgili projeye yönlendirmelidir. Birden çok depodaki birçok paket adını aynı anda denetlemek için iyi bir hizmet repolojidir.

Kısa adlara sahip veya ortak sözcüklerden sonra adlandırılmış projeler, özellikle belirli bir sözcükle güçlü bir ilişkisi olan proje olmadığında kesinleştirme gerektirebilir. Örneğin, adı ip olan bir bağlantı noktası kabul edilemez çünkü benzer şekilde birden çok proje adlandırılabilir.

İyi belirsizleştiricilere örnek olarak şunlar verilebilir:

  • Deponun sahip kullanıcı adı veya kuruluşu: google-cloud-cpp.
  • Projenin parçası olduğu kitaplık paketinin adı: boost-dll.

C++ ve açık kaynak projeleri tarafından kullanılan yaygın önekler ve sonekler geçerli belirsizdir; bazı örnekler şunlardır ancak bunlarla sınırlı değildir:

  • cpp,
  • free,
  • lib,
  • open,
  • Sayılar

Örneğin, aşağıdaki bağlantı noktası adları karşılaştırılırken: ip-cpplibip ve ip5 ve geçersiz kesinleştiricileri kaldırırken, hepsi aynı köke (ip) indirgenir ve bu nedenle aynı ada sahip olduğu kabul edilir.

Tek bir projeyle kesin olarak ilişkilendirilmiş adlar için bu kılavuza özel bir durum oluşturulur. Örneğin: libpng, openssl ve zlib.

Kullanıcıların kafa karışıklığını önlemek için, genel kayıt defterine eklendikten sonra bağlantı noktasının yeniden adlandırılma sıklığını sınırlayabiliriz. Geçerli ilkemiz, yılda birden fazla yeniden adlandırmaya izin vermemektir.

GitHub taslak PR'lerini kullanma

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, bayat PR'lerin birikmesini önlemek için, katkıda bulunanın eylemini 60 günden uzun süredir bekleyen PR'leri kapatabilir. Bu geri sayım, bir vcpkg bakımcısının son değişiklik veya geri bildirim isteğinde bulunmasından itibaren başlar. 60 gün içinde hiçbir etkinlik gözlemlenmezse PR eski olarak kabul edilir ve vcpkg ekibinin takdirine bağlı olarak kapatılabilir.

Bağlantı noktası dosyaları

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:

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şırı açıklamalardan kaçının

İdeal olarak, portfiles kısa, basit ve mümkün olduğunca bildirim temelli olmalıdır. Çekme isteği göndermeden önce komut tarafından create tanıtılan kazan plakası açıklamalarını kaldırın.

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

Bağlantı noktaları, hangi bağlantı noktalarının yüklendiği içeriği değiştirebilecek bir formda yüklü olan bağlantı noktalarını temel alarak davranışlarını değiştirmemelidir. Örneğin, verilen:

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

ile

> vcpkg install b

tarafından b yüklenen dosyalar, önceki yüklemesinin aetkisinden bağımsız olarak aynı olmalıdır. Bu, bağlantı noktalarının bir işlem gerçekleştirmeden önce yüklü ağaçta başka bir bağlantı noktası tarafından bir şeyin sağlanıp sağlanmadığını algılamaya çalışmaması gerektiği anlamına gelir. 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 bağlantı noktası üst bilgi için son derece yaygın bir ad kullanmak istiyorsa, bu üst bilgileri yerine bir alt dizine includeyerleştirmelidir.

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

Resmi olmayan bir ad alanına CMake dışarı aktarmaları ekleme

Vcpkg için ideal olan temel tasarım, kullanıcılar için "kilitleme" oluşturmamaktır. Derleme sisteminde, sistemdeki bir kitaplığa bağlı olarak ve vcpkg kitaplığına bağlı olarak arasında bir fark olmamalıdır. Bu amaçla, yukarı akışların vcpkg ile çakışmadan kendi resmi CMake dışarı aktarmalarını eklemesine izin vermek için mevcut kitaplıklara "belirgin adla" CMake dışarı aktarmaları veya hedefleri eklemekten kaçınıyoruz.

Bu amaçla, yukarı akış kitaplığında olmayan bağlantı noktasının dışarı aktardığı tüm CMake yapılandırmalarının ön eki olmalıdır unofficial- . Tüm ek hedefler ad alanında unofficial::<port>:: olmalıdır.

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

  • find_package(unofficial-<port> CONFIG) unique-to-vcpkg paketine ulaşmak için bir yol olarak
  • unofficial::<port>::<target> bu bağlantı noktasından dışarı aktarılan bir hedef olarak.

Örnekler:

  • brotli , hedefini unofficial-brotliunofficial::brotli::brotlioluşturarak paketini oluşturur.

Her bağlantı noktasının klasöründe copyrightadlı ${CURRENT_PACKAGES_DIR}/share/${PORT} bir dosya sağlaması gerekir. Bir paketin lisans içeriği kaynak dosyalarında kullanılabiliyorsa, bu dosya çağrısıyla vcpkg_install_copyright()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. Bu, yeni bağlantı noktaları için vcpkg_install_copyright önerilmez, 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. Yükler ve port[featureA] yüklerse port[featureB]port[featureA,featureB], yüklenmesi gerekir. Ayrıca, ikinci bir bağlantı noktası bağımlıysa [featureA] ve üçüncü bir bağlantı noktası bağımlıysa [featureB], hem ikinci hem de üçüncü bağlantı noktalarının yüklenmesi bağımlılıklarını karşılamalıdır.

Bu durumdaki kitaplıkların vcpkg ile ifade edilen kullanılabilir seçeneklerden birini seçmesi ve farklı bir ayar isteyen kullanıcıların şu anda katman bağlantı noktalarını kullanması gerekir.

Geriye dönük uyumluluk için bugün kabul etmeyeceğiniz 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.

Varsayılan özellikler, kitaplığı kullandığını bilmeyen müşteriler için makul düzeyde işlevsel bir kitaplığın yüklenmesini sağlamaya yöneliktir. 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

Bir bağlantı noktasının tüketicisi yalnızca bu bağlantı noktasının temel işlevselliğine bağlıysa, yüksek olasılıkla özelliği açarak bozulmamalıdır. Alternatif doğrudan tüketici tarafından değil gibi /std:c++17 / -std=c++17derleyici ayarları tarafından denetlendiğinde bu daha da önemlidir.

Geriye dönük uyumluluk için bugün kabul etmeyeceğiniz mevcut örnekler:

  • redis-plus-plus[cxx17] bir çok doldurmayı denetler, ancak ayarı yüklü ağaçta pişirmez.
  • ace[wchar] , yerine tüm API'leri kabul const wchar_t*const char*etmek üzere değiştirir.

Bir özellik, değiştirilenin yüklü ağaçta pişirilmiş olması koşuluyla polifill'leri diğer adlarla değiştirebilir

Yukarıdakilere bakılmaksızın, bağlantı noktaları aşağıdakiler gibi bir özellik ile çok dolumları 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üklü üst bilgilerde pişirilir, böylece ABI uyuşmazlığı "imkansız" çalışma zamanı hataları pek olası değildir
  3. Bağlantı noktası tüketicisinin her iki modda da çalışan kod yazması mümkündür; örneğin, çok doldurulmuş veya doldurulmamış bir tür tanımı kullanarak

Örnek:

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

Temel alınan alternatiflerin kullanıma sunulması kritik önem taşıyorsa, kullanıcıya bağlantı noktasının özel bir katmana nasıl kopyalanması konusunda bilgi 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")

Derleme teknikleri

Satıcı bağımlılıklarını kullanmayın

Kitaplıkların eklenmiş 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, yönergeleri kullanarak file(GLOB) alternatif derleme sistemlerini CMake'e yeniden yazmak daha kolay ve daha sürdürülebilir olabilir.

Örnekler: abseil

Statik veya paylaşılan ikili dosyaları seçme

CMake kitaplıkları oluştururken, vcpkg_cmake_configure() kullanıcının istenen varyantı temelinde için BUILD_SHARED_LIBS 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 bağlantı noktasının gelecekteki sürdürülebilirliğ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 kitaplığa düzeltme eki uygulanırken, istenmeyen hedeflere eklemek EXCLUDE_FROM_ALL ve çağrıyı install(TARGETS ...) içinde if(BUILD_SHARED_LIBS)sarmalama 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 satıra install(TARGETS) düzeltme eki 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}
)

Aşağıdaki kullanılarak vcpkg_check_features() 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 ve CMAKE_DISABLE_FIND_PACKAGE_<PackageName> belgelerine CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> bakın.

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

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

Çakışan fiiller genellikle tasarım gereğidir ve hata olarak kabul edilmez. 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üncelleştirirken, yukarı akış aksini belirtmediği sürece aynı kuralı 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 işlemeler, ü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.

Kuralımız, yukarı akış sürümünü değiştirmeyen bağlantı noktasında yapılan değişiklikler için alanını kullanmak "port-version" ve "port-version" yukarı akış sürümüne bir güncelleştirme yapıldığında sıfıra sıfırlamaktır.

Örneğin:

  • Zlib'in paket sürümü şu anda 1.2.1açık olmayandır (ile eşdeğeri "port-version""port-version").0
  • 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ının sürüm dosyalarını versions/ güncelleştirme

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, ilgili dosyalar için zlib ş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

tüm değiştirilen 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.

Yama

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:
    • yukarı akış buna katılmıyor
    • 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 dolanıklığına neden olacak 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. (Yukarı akışla ilgili olmayan vcpkg'ye özgü davranış uygulayan düzeltme ekleri(örneğin, bir bağımlılığın süslenmesi) bildirim gerektirmez.)

Yukarı akışın düzeltme eki ile aynı fikirde olmadığı durumlardan kaçınmak için bu tür düzeltme eklerini uygulamak için en az 30 gün bekleyeceğiz.

Değişikliğin doğru olduğundan çok güvenirsek bu bekleme süresini atlarız. Yüksek güvenilirlik düzeltme eklerine örnek olarak şunlar verilebilir 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 #includes ekleniyor.
  • Küçük ve belirgin ürün kodu düzeltmeleri (örneğin, başlatılmamış değişken başlatma).
  • Testler veya örnekler gibi derlemenin ilgisiz vcpkg bileşenlerini devre dışı bırakma.

Düzeltme eki uygulama yerine seçenekleri tercih etme

Bir çağrıda vcpkg_configure_xyz() ayarları doğrudan düzeltme eki uygulama üzerinden ayarlamak 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] find_package(XYz) CMake betiklerindeki çağrılar şu aracılığıyla devre dışı bırakılabilir: -DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON
  • [CMAKE] Önbellek değişkenleri (veya set(VAR "value" CACHE STRING "Documentation")olarak option(VAR "Documentation" "Default Value") bildirildi) yalnızca komut satırında olarak -DVAR:STRING=Foogeçirilerek 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:

  • Yukarı akışın düzeltme eki değişikliklerini kabul ettiğini onaylar
  • Onus yukarı akışını 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

SHA çakışmalarını önlemek için düzeltme ekleri kararlı bir uç noktadan indirilmelidir. GitHub ve GitLab'den ?full_index=1 bir çekme isteğinden veya işlemeden düzeltme eki dosyaları indirilirken, 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

Değerleri geçersiz kılmaya düzeltme eki uygulama VCPKG_<VARIABLE> tercih etme

ö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}")

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

Bu nedenle, ayarlarken CMAKE_<LANG>_FLAGSderleme sistemine doğrudan düzeltme eki uygulamak tercih edilir.

Düzeltme eklerini simge durumuna küçültme

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 veya AND FALSE eklemek&& 0, koşullunun 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ölgeye veya if(0) eklemek #if 0 daha kısadır.

Bağlantı noktasının eski olması ve bağlantı noktasının daha yeni bir sürüme güncelleştirilmesi 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 uygulama

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 bağlantı noktası gönderirken veya BUILD_TESTSWITH_TESTS gibi POCO_ENABLE_SAMPLES seçenekleri denetleyin 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, yukarı akış kitaplığı sürüm ve hata ayıklamada aynı ada sahipse yeni bir ad 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 kitaplık CMake tümleştirme dosyaları ()foo-config.cmake oluşturuyorsa, yeniden adlandırma yalnızca çıkış arşivlerini/LIB'leri çağırmak file(RENAME) yerine CMake derlemesinin kendisine düzeltme eki uygulanarak yapılmalıdır.

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 ediyoruz. 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 durumlara ekleriz:

  • İnsanların bu topluluk üçlüslerini gerçekten kullanacakları gösterilmiştir; ve
  • Böyle üçlülerin bozulduğ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 Betik 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ı üçlü dosyada ayarlanan değişkenlere doğrudan erişime sahiptir, ancak CMakeLists.txts'ler (genellikle gerçekleşen bir çeviri olsa da -- VCPKG_LIBRARY_LINKAGE yerine BUILD_SHARED_LIBS).

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.

  • Last updated on