Bu sayfa, kurallarını kullanıma sunmayı planlayan kural yazarları içindir .
Şablon deposundan yeni bir kural kümesi başlatmanızı öneririz: https://github.com/bazel-contrib/rules-template Bu şablon aşağıdaki önerilere uygundur ve API belgeleri oluşturma işlevini içerir ve kural grubunuzu dağıtmayı önemsiz hale getirmek için bir CI/CD ardışık düzeni oluşturdu.
Barındırma ve adlandırma kuralları
Yeni kurallar, kuruluşunuz bünyesindeki kendi GitHub deposuna yerleştirilmelidir. GitHub'da ileti dizisi başlatın Kurallarınızın bazelbuild kurum içinde tutmaktır.
Bazel kuralları için depo adları aşağıdaki biçimde standartlaştırılmıştır:
$ORGANIZATION/rules_$NAME
GitHub'daki örneklere bakın.
Tutarlılık için Bazel kurallarınızı yayınlarken aynı biçimi kullanmanız gerekir.
Açıklayıcı bir GitHub deposu açıklaması ve README.md kullanın
başlık, örnek:
- Depo adı:
bazelbuild/rules_go - Depo açıklaması: Bazel için Go kuralları
- Depo etiketleri:
golang,bazel README.mdüstbilgisi: Bazel için kurallara gidin (bilmeyen kullanıcılara yol gösterecek https://bazel.build bağlantısını not edin. birlikte)
Kurallar dile (Scala gibi) ve çalışma zamanı platformuna göre gruplandırılabilir. (ör. Android) veya çerçeve (Spring gibi) kullanabilirsiniz.
Depo içeriği
Kullanıcıların hızlıca ulaşabilmeleri için her kural deposunun belirli bir düzeni olmalıdır. yeni kuralları kavrayacaksınız.
Örneğin, "insanların" ifadesi için yeni kurallar yazarken
mockascript dilini seçerseniz kural deposu aşağıdaki yapıya sahip olur:
/
LICENSE
README
MODULE.bazel
mockascript/
constraints/
BUILD
runfiles/
BUILD
runfiles.mocs
BUILD
defs.bzl
tests/
BUILD
some_test.sh
another_test.py
examples/
BUILD
bin.mocs
lib.mocs
test.mocs
MODULE.bazel
Projenin MODULE.bazel bölümünde kullanıcıların kullanacağı adı tanımlamanız gerekir.
kullanmanızı öneririz. Kurallarınız
bazelbuild kuruluşunda
rules_<lang> (rules_mockascript gibi). Aksi takdirde
depo <org>_rules_<lang> (build_stack_rules_proto gibi). Lütfen
GitHub'da bir ileti dizisi başlatın
kurallarınızın Google Ads'deki kurallara ilişkin kurallara
bazelbuild kuruluşu.
Aşağıdaki bölümlerde deponun şuna ait olduğunu varsayın: bazelbuild kuruluşu.
module(name = "rules_mockascript")
BENİOKU
Üst düzeyde, kısa bir açıklama içeren bir README olmalıdır
ve API kullanıcılarının beklemesi gereken
özellikleri içerir.
Kurallar
Çoğu zaman deponuz tarafından sağlanan birden fazla kural olur. Bir metin oluştur:
dile göre adlandırılmış dizin ve bir giriş noktası sağlar - defs.bzl dosyası
dışa aktarma (dizinin paket olması için bir BUILD dosyası da dahil edin).
rules_mockascript için bu,
mockascript ve bir BUILD dosyası ile bir defs.bzl dosyası içine:
/
mockascript/
BUILD
defs.bzl
Sınırlamalar
Kuralınız
araç zinciri kurallarını kullanarak
özel constraint_setting ve/veya
constraint_value sn. Bunları bir //<LANG>/constraints paketine yerleştirin. Sizin
dizin yapısı aşağıdaki gibi görünecektir:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
Lütfen okuyun
github.com/bazelbuild/platforms
mevcut kısıtlamalara bakmak ve en iyi uygulamaları
dilden bağımsız kısıtlarınız varsa bunlara katkıda bulunabilirsiniz.
Özel kısıtlamalar kullanmaya dikkat edin. Kurallarınızın tüm kullanıcıları,
bunları, BUILD dosyalarında platforma özgü mantık (örneğin,
(seçimler kullanarak).
Özel kısıtlamalarla tüm Bazel ekosisteminin çalışacağı bir dili
konuşacak.
Runfiles kitaplığı
Kuralınız çalıştırma dosyalarına erişim için standart bir kitaplık sağlıyorsa
//<LANG>/runfiles adresinde bulunan bir kütüphane hedefi (kısaltma) biçiminde
/ //<LANG>/runfiles:runfiles). Verilerine erişmesi gereken kullanıcı hedefleri
bağımlılıklar genellikle bu hedefi deps özelliklerine ekler.
Depo kuralları
Bağımlılıklar
Kurallarınızın harici bağımlılıklar olabilir. Bu bağımlılıkları MODULE.bazel dosyanız.
Araç zincirleri kaydediliyor
Kurallarınız, MODULE.bazel dosyası oluşturun.
Analiz aşamasında araç zincirlerini çözebilmek için Bazel'in
Kayıtlı toolchain hedefin tümünü analiz edebilir. Bazel için
toolchain.toolchain özelliğinin başvuruda bulunduğu tüm hedefleri analiz eder. Siparişteyse
karmaşık hesaplamalar yapmanız gereken araç zincirlerini kaydetmek için
depolanıyorsa depoyu toolchain hedefleri olan
<LANG>_toolchain hedefi olan depo. Önceki değer her zaman getirilir ve
ikincisi ise yalnızca kullanıcının gerçekten <LANG> kodu derlemesi gerektiğinde getirilir.
Sürüm snippet'i
Sürüm duyurunuzda, kullanıcılarınızın kopyalayıp yapıştırabileceği bir snippet sağlayın.
MODULE.bazel dosyasına ekleyebilir. Bu snippet, genel olarak aşağıdaki gibi görünür:
bazel_dep(name = "rules_<LANG>", version = "<VERSION>")
Testler
Kuralların beklendiği gibi çalıştığını doğrulayan testler olmalıdır. Bu
kuralların hedeflendiği dil için standart bir konumda bulunabilir veya
tests/ dizini üst düzeyde.
Örnekler (isteğe bağlı)
Kullanıcılara birkaç örnek içeren examples/ dizininin olmasının
temel yöntemlerine değineceğiz.
CI/CD
Birçok kural kümesi, GitHub İşlemler özelliğini kullanır. rules-template deposunda kullanılan ve "yeniden kullanılabilir iş akışı" ile basitleştirilmiş yapılandırmayı inceleyin bazel-katkıda barındırılan
org. ci.yaml, her PR ve main birleştirme işleminde test çalıştırır. release.yaml ise depoya her etiket aktardığında çalışır.
Daha fazla bilgi için kural şablonu deposundaki yorumlara göz atın.
Deponuz bazelbuild kuruluşu altındaysa bir belgenin eklenmesini isteyebilirsiniz ci.bazel.build bölümüne gönderebilirsiniz.
Belgeler
Şu ayrıntılar için Stardoc dokümanlarına bakın: belgelerin oluşturulabilmesi için kurallarınızı nasıl yorumlayacağınıza ilişkin talimatlar otomatik olarak oluşturur.
Kural şablonu dokümanlar/ klasör
docs/ klasöründeki Markdown içeriğinin her zaman güncel olmasını sağlamanın basit bir yolunu gösteriyor
dosyaları güncellendiğinden emin olun.
SSS
Kuralımızı neden ana Bazel GitHub deposuna ekleyemiyoruz?
Bazel sürümlerinden mümkün olduğunca kuralları birbirinden ayırmak istiyoruz. Daha net Bu da Bazel geliştiricilerinin üzerindeki yükü azaltır. Kullanıcılarımız için Ayrıştırma; kuralları değiştirme, yükseltme, eski sürüme geçirme ve değiştirme işlemlerini kolaylaştırır. Kurallara katkıda bulunmak, Bazel'e katkıda bulunmaktan daha hafif olabilir - ve GitHub deposu. Bazel'in kendisine gönderme erişimi vermek çok daha karmaşık bir iştir. bahsedeceğim.
Olumsuz tarafı ise, kullanıcılarımız için tek seferlik daha karmaşık bir yükleme işlemidir:
MODULE.bazel dosyasında kural grubunuza bir bağımlılık eklemesi gerekir.
Tüm kurallara Bazel deposunda (
//tools/build_rules veya //tools/build_defs). Hâlâ birkaç kuralımız var.
kalan kuralları devre dışı bırakmak için çalışmaya devam ediyoruz.