Aracılığıyla paylaş

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

Bir kerede birçok hizmeti denetlemek için iyi bir hizmet Repology'dir. Eklediğiniz kitaplık başka bir kitaplıkla karıştırılmış olabilirse, açıkça ifade etmek için yeniden adlandırmayı göz önünde bulundurun. Adların daha uzun olduğu ve/veya aynı adın gelecekte kullanılmasıyla çakışma olasılığının düşük olduğu durumları tercih ediyoruz. Bağlantı noktası GitHub'da bir kitaplığa başvuruyorsa, karışıklık olasılığı varsa adın ön ekini kuruluşa eklemek iyi bir uygulamadır.

Başka bir şekilde ifade etmek gerekirse, bunun nedeni kullanıcıya bekledikleri şeyi aramasını Xxx ve farklı bir şey elde ederek şaşırmamasını sağlamaktırvcpkg install Xxx.

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-brotliunofficial::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
]])

Ö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'leri değil davranışları etkinleştirmelidir

Tüketici doğrudan bir kitaplığa bağlıysa, istenen özellikleri kolayca listeleyebilir (library[feature1,feature2]). Ancak, bir tüketici kitaplık kullandığını bilmiyorsa bu özellikleri listeleyemez. Bu gizli kitaplık, özelliklerin mevcut bir genel arabirime ek sıkıştırma algoritmaları (ve dolayısıyla davranışlar) eklediği yer gibiyse libarchive , varsayılan özellikler son tüketici doğrudan adlandırmasa bile makul düzeyde işlevsel geçişli bir kitaplığın derlenmesini sağlamanın bir yolunu sunar.

Özellik ek API'ler (veya yürütülebilir dosyalar veya kitaplık ikili dosyaları) ekliyorsa ve mevcut API'lerin davranışını değiştirmiyorsa, varsayılan olarak kapalı bırakılmalıdır. Bunun nedeni, bu API'leri kullanmak isteyebilecek tüm tüketicilerin doğrudan başvuru yoluyla kolayca ihtiyaç duyması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

Varsayılan olarak, vcpkg_cmake_configure() için BUILD_SHARED_LIBSuygun ayarı geçirir, ancak bu değişkene uygun olmayan kitaplıklar için ayarını açabilirsiniz VCPKG_LIBRARY_LINKAGE:

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

Ö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

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. Ayrıca, bir koşulluyu devre dışı bırakırken, koşula veya && 0 eklemekAND FALSE, koşullunun her satırını silmekten daha iyidir.

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, sürüm çarpması önemli miktarda bağımlı bağlantı noktasını kesmediği sürece 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_TESTSPOCO_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.