Bakımcı kılavuzu

  • Makale

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 portfile.cmake hiç derlenmemiş ek bağlantı noktaları eklemeye çalışmak yerine alternatif formu bir açıklamayla uygulayan bir katman bağlantı noktası oluşturabileceğini açıklayabilirsiniz. Örneğin, bkz . glad@0.1.36.

Kayıt defterlerinin kullanıma sunulmasından önce, yer paylaşımlı bağlantı noktalarını yazmayı kolaylaştırabilecek, alternatif olarak boringssltest edilmeyen birkaç bağlantı noktasını 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.

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

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

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-brotli unofficial::brotli::brotlioluşturarak paketini oluşturur.

Her bağlantı noktasının klasöründe ${CURRENT_PACKAGES_DIR}/share/${PORT}adlı copyright 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.

Özellikler

Alternatifleri uygulamak için özellikleri kullanmayın

Özellikler, ek işlevsellik olarak ele alınmalıdır. Yükler ve port[featureB] yüklerse port[featureA] 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

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 std::string_viewgeçerabsl::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.

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_REQUIRE_FIND_PACKAGE_<PackageName> belgelerine CMAKE_DISABLE_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.

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" 0)."port-version"
  • 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.

Not

Bu komutlar, değişikliklerinizi çalıştırmadan önce bağlantı noktalarına işlemenizi gerektirir. Bunun nedeni, bu sürüm dosyalarında bağlantı noktası dizininin Git SHA'sının gerekli olmasıdır. Ancak endişelenmeyin x-add-version , kaydedilmemiş yerel değişiklikleriniz varsa komut sizi uyarır.

Daha fazla bilgi için bkz . Sürüm oluşturma başvurusu ve Kayıt defterleri oluşturma.

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 option(VAR "Documentation" "Default Value")olarak set(VAR "value" CACHE STRING "Documentation") 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 && 0 eklemekAND FALSE, 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 WITH_TESTS POCO_ENABLE_SAMPLES gibi BUILD_TESTS 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 ile vcpkg_check_linkage(ONLY_STATIC_LIBRARY)olarak işaretlenmelidir.

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 CMakeLists.txt'ler ortak bir söz dizimi ve temel CMake dil yapılarını (diğer adıyla "Betik Komutları") paylaşırkenportfile.cmake, 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.