Bu sayfa, kurallarını diğer kullanıcıların kullanımına sunmayı planlayan kural yazarları içindir.
Şablon deposundan yeni bir kural grubu oluşturmanızı öneririz: https://github.com/bazel-contrib/rules-template Bu şablon aşağıdaki önerilere uyar, API dokümanı oluşturma özelliğine sahiptir ve kural grubunuzu dağıtmayı kolaylaştırmak için bir CI/CD ardışık düzeni oluşturur.
Barındırma ve adlandırma kuralları
Yeni kurallar, kuruluşunuzun altındaki kendi GitHub deposuna eklenmelidir. Kurallarınızın bazelbuild kuruluşuna ait olduğunu düşünüyorsanız GitHub'da bir ileti dizisi başlatın.
Bazel kurallarının depo adları şu biçimde standartlaştırılmıştır:
$ORGANIZATION/rules_$NAME
.
GitHub'daki örneklere göz atın.
Tutarlılık için Bazel kurallarınızı yayınlarken aynı biçimi uygulamanız gerekir.
Açıklayıcı bir GitHub deposu açıklaması ve README.md
başlığı kullanın. Örnek:
- Depo adı:
bazelbuild/rules_go
- Depo açıklaması: Bazel için Go kuralları
- Depo etiketleri:
golang
,bazel
README.md
başlık: Bazel için Go kuralları (Bazel'i bilmeyen kullanıcıları doğru yere yönlendirecek https://bazel.build bağlantısına dikkat edin)
Kurallar dile (Scala gibi), çalışma zamanı platformuna (ör. Android) veya çerçeveye (ör. Spring) göre gruplandırılabilir.
Depo içeriği
Kullanıcıların yeni kuralları hızla anlayabilmesi için her kural deposunun belirli bir düzeni olmalıdır.
Örneğin, (hayali) mockascript
dili için yeni kurallar yazılırken 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 kurallarınıza referans vermek için kullanacağı adı tanımlamanız gerekir. Kurallarınız bazelbuild kuruluşuna aitse rules_<lang>
(rules_mockascript
gibi) kullanmanız gerekir. Aksi takdirde, deponuzu <org>_rules_<lang>
olarak adlandırmalısınız (build_stack_rules_proto
gibi). Kurallarınızın bazelbuild kuruluşundaki kurallara uygun olması gerektiğini düşünüyorsanız GitHub'da bir ileti dizisi başlatın.
Aşağıdaki bölümlerde, deponun bazelbuild kuruluşuna ait olduğu varsayılır.
module(name = "rules_mockascript")
BENİOKU
Üst düzeyde, kural kümenizin kısa bir açıklamasını içeren bir README
olmalıdır ve API kullanıcılarının bunu beklemesi gerekir.
Kurallar
Deponuz tarafından sağlanan birden fazla kural olabilir. Dile göre adlandırılmış bir dizin oluşturun ve bir giriş noktası sağlayın - defs.bzl
tüm kuralları dışa aktarın (dizinin paket olması için bir BUILD
dosyası da ekleyin).
rules_mockascript
için bu, mockascript
adlı bir dizin ve içinde bir BUILD
dosyası ile bir defs.bzl
dosyası olacağı anlamına gelir:
/
mockascript/
BUILD
defs.bzl
Sınırlamalar
Kuralınız araç zinciri kurallarını tanımlıyorsa özel constraint_setting
ve/veya constraint_value
tanımlamanız gerekebilir. Bunları bir //<LANG>/constraints
paketine koyun. Dizin yapınız şu şekilde görünür:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
En iyi uygulamalar için lütfen
github.com/bazelbuild/platforms
adresini okuyun ve mevcut kısıtlamalara bakın. Kısıtlamalar dilden bağımsızsa o sayfada kısıtlarınızı da katkıda bulunmayı düşünebilirsiniz.
Özel kısıtlamalar eklerken dikkatli olun. Kurallarınızın tüm kullanıcıları, BUILD
dosyalarında platforma özgü mantık yürütmek için bu kısıtlamaları kullanır (örneğin, seçim kullanarak).
Özel kısıtlamalarla tüm Bazel ekosisteminin konuşacağı bir dil tanımlarsınız.
Çalışma dosyası kitaplığı
Kuralınız çalıştırma dosyalarına erişmek için standart bir kitaplık sağlıyorsa //<LANG>/runfiles
konumunda bulunan bir kitaplık hedefi (//<LANG>/runfiles:runfiles
adının kısaltması) biçiminde olmalıdır. Veri bağımlılıklarına erişmesi gereken kullanıcı hedefleri, genellikle bu hedefi deps
özelliklerine ekler.
Depo kuralları
Bağımlılıklar
Kurallarınızda harici bağımlılıklar olabilir. Bu bağımlılıkları MODULE.bazel dosyanızda belirtmeniz gerekir.
Araç zincirlerini kaydetme
Kurallarınız, araç zincirlerini de kaydedebilir. Bu araç zincirlerini MODULE.bazel dosyasında da belirtebilirsiniz.
Analiz aşamasında araç zincirlerini çözümleyebilmek için Bazel'in kayıtlı tüm toolchain
hedeflerini analiz etmesi gerektiğini unutmayın. Bazel'in toolchain.toolchain
özelliği tarafından referans verilen tüm hedefleri analiz etmesi gerekmez. Araç zincirlerini kaydetmek için depoda karmaşık hesaplamalar yapmanız gerekiyorsa depoyu toolchain
hedefleriyle birlikte, <LANG>_toolchain
hedefleri olan depodan bölmeyi düşünün. İlki her zaman getirilir, ikincisi ise yalnızca kullanıcının <LANG>
kodu oluşturması gerektiğinde getirilir.
Snippet'i yayınlama
Sürüm duyurunuzda, kullanıcılarınızın kopyalayıp MODULE.bazel
dosyalarına yapıştırabilecekleri bir snippet sağlayın. Bu snippet genellikle 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 dizin, kuralların geçerli olduğu dilin standart konumunda veya üst düzey bir tests/
dizininde olabilir.
Örnekler (isteğe bağlı)
Kullanıcılara, kuralların kullanılabileceği birkaç temel yöntemi gösteren bir examples/
dizini sunmak faydalı olacaktır.
CI/CD
Birçok kural kümesi GitHub Actions'ı kullanır. rules-template deposunda kullanılan yapılandırmaya bakın. Bu yapılandırma, bazel-contrib.org'da barındırılan "yeniden kullanılabilir bir iş akışı" kullanılarak basitleştirilmiştir. ci.yaml
, her PR ve main
commit'te testler çalıştırır. release.yaml
ise depoya bir etiket aktardığınızda her zaman çalışır.
Daha fazla bilgi için rules-template deposundaki yorumlara bakın.
Deponuz bazelbuild kuruluşunun altındaysa ci.bazel.build alanına eklenmesini isteyebilirsiniz.
Belgeler
Dokümanların otomatik olarak oluşturulabilmesi için kurallarınıza nasıl yorum ekleneceğiyle ilgili talimatlar için Stardoc belgelerine bakın.
rules-template docs/ klasörü, Starlark dosyaları güncellendikçe docs/
klasöründeki Markdown içeriğinin her zaman güncel olmasını sağlamanın basit bir yolunu gösterir.
SSS
Kuralımızı ana Bazel GitHub deposuna neden ekleyemiyoruz?
Kuralları Bazel sürümlerinden mümkün olduğunca ayırmak istiyoruz. Ayrı kuralların kime ait olduğu daha net bir şekilde anlaşılır ve Bazel geliştiricilerinin üzerindeki yük azalır. Ayrıştırma, kullanıcılarımızın kuralları değiştirme, yükseltme, düşürme ve değiştirme işlemlerini kolaylaştırır. Kurallara katkıda bulunmak, kurallara bağlı olarak Bazel'e katkıda bulunmaktan daha az zaman alabilir. Bu katkı, ilgili GitHub deposuna tam gönderme erişimi de içerir. Bazel'ın kendisine gönderme erişimi almak çok daha karmaşık bir süreçtir.
Bunun dezavantajı, kullanıcılarımız için daha karmaşık bir tek seferlik yükleme işlemidir: MODULE.bazel
dosyalarında kural kümenize bağımlılık eklemeleri gerekir.
Tüm kurallar Bazel deposunda (//tools/build_rules
veya //tools/build_defs
altında) yer alıyordu. Orada hâlâ birkaç kuralımız var, ancak kalan kuralları devre dışı bırakmak için çalışmalarımız devam ediyor.