Bu sayfa, kurallarını başkalarına 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 uygun olup API belgesi oluşturma adımını içerir ve kural grubunuzu dağıtmayı önemsiz hale getirmek için bir CI/CD ardışık düzeni oluşturur.
Barındırma ve adlandırma kuralları
Yeni kurallar, kuruluşunuz dahilindeki kendi GitHub deposuna yerleştirilmelidir. Kurallarınızın bazelbuild kuruluşuna ait olduğunu düşünüyorsanız GitHub'da bir ileti dizisi başlatın.
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
başlığı kullanın. Örnek:
- Kod deposu adı:
bazelbuild/rules_go
- Depo açıklaması: Bazel için Go kuralları
- Depo etiketleri:
golang
,bazel
README.md
üstbilgisi: Bazel için kurallara gidin (Bazel'i bilmeyen kullanıcıları doğru yere yönlendirecek https://bazel.build bağlantısını kullanın)
Kurallar dil (Scala gibi), çalışma zamanı platformu (ör. Android) veya çerçeveye (ör. Spring) göre gruplandırılabilir.
Depo içeriği
Kullanıcıların yeni kuralları hızlı bir şekilde anlayabilmesi için her kural deposunun belirli bir düzeni olmalıdır.
Örneğin, mockascript
dili için yeni kurallar yazarken kural deposu aşağıdaki yapıya sahip olur:
/
LICENSE
README
WORKSPACE
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
ÇALIŞMA ALANI
Projenin WORKSPACE
bölümünde kullanıcıların kurallarınıza başvurmak 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ğunu varsayın.
workspace(name = "rules_mockascript")
BENİOKU
Üst düzeyde, (en azından) kullanıcıların kuralınızı kullanmak için WORKSPACE
dosyalarına kopyalayıp yapıştırmaları gereken öğeleri içeren bir README
olmalıdır.
Genel olarak bu, GitHub sürümünüzü işaret eden bir http_archive
ve kuralınızın ihtiyaç duyduğu tüm araçları indiren/yapılandıran bir makro çağrısı olacaktır. Örneğin, Go kuralları için bu değer şu şekilde görünür:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_go",
urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()
Kurallarınız başka bir deponun kurallarına bağlıysa bunu kural dokümanlarında belirtin (örneğin, Sass kurallarına bağlı olan Skydoc kurallarına bakın) ve tüm bağımlılıkları indirecek bir WORKSPACE
makrosu sağlayın (yukarıdaki rules_go
bölümüne bakın).
Kurallar
Çoğu zaman deponuz tarafından sağlanan birden fazla kural olur. 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
adında bir dizin ve BUILD
dosyası ile defs.bzl
dosyasının içinde 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 yerleştirin. Dizin yapınız aşağıdaki gibi görünecektir:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
En iyi uygulamalar için lütfen
github.com/bazelbuild/platforms
adresini okuyun ve mevcut kısıtlamaları görmek için
dilden bağımsız olan kısıtlamalarınızı söz konusu kısıtlamalara katkıda bulunmayı düşünün.
Özel kısıtlamalar sunmaya dikkat edin. Kurallarınızın tüm kullanıcıları, BUILD
dosyalarında platforma özel mantık gerçekleştirmek (örneğin, selects kullanarak) için bunları kullanır.
Özel kısıtlamalarla tüm Bazel ekosisteminin konuşacağı bir dil tanımlarsınız.
Runfiles kitaplığı
Kuralınız çalıştırma dosyalarına erişim 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 dış bağımlılıklar olabilir. Kurallarınıza bağlı olarak süreci kolaylaştırmak için lütfen bu dış bağımlılıklara bağımlılıkları bildirecek bir WORKSPACE
makrosu sağlayın. Burada testlerin bağımlılıklarını belirtmeyin, yalnızca kuralların çalışması için gereken bağımlılıkları bildirin. WORKSPACE
dosyasına geliştirme bağımlılıkları ekleyin.
<LANG>/repositories.bzl
adlı bir dosya oluşturun ve rules_<LANG>_dependencies
adlı tek bir giriş noktası makrosu sağlayın. Dizinimiz aşağıdaki gibi görünür:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
Araç zincirleri kaydediliyor
Kurallarınız araç zincirleri de kaydedebilir. Lütfen bu araç zincirlerini kaydeden ayrı bir WORKSPACE
makrosu sağlayın. Bu sayede kullanıcılar, önceki makroyu atlayıp bağımlılıkları manuel olarak kontrol ederken araç zincirlerini kaydetmeye devam edebilir.
Bu nedenle, <LANG>/repositories.bzl
dosyasına rules_<LANG>_toolchains
adlı bir WORKSPACE
makrosu ekleyin.
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. Önceki kod her zaman, 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 WORKSPACE
dosyalarına yapıştırabilecekleri bir snippet sağlayın. Bu snippet, genel olarak aşağıdaki gibi görünür:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_<LANG>",
urls = ["<url_to_the_release.zip"],
sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()
Testler
Kuralların beklendiği gibi çalıştığını doğrulayan testler olmalıdır. Bu konum, kuralların hedeflendiği dil için standart konumda veya en üst düzeyde bir tests/
dizininde olabilir.
Örnekler (isteğe bağlı)
Kuralların kullanılabileceği birkaç temel yöntemi kullanıcılara gösteren bir examples/
dizininin olması kullanıcılar açısından faydalıdır.
CI/CD
Birçok kural kümesi, GitHub İşlemler özelliğini kullanır. rules-template deposunda kullanılan ve bazel-contrib kuruluşunda barındırılan "yeniden kullanılabilir iş akışı" ile basitleştirilmiş olan yapılandırmayı inceleyin. 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 ci.bazel.build bölümüne eklemenizi isteyebilirsiniz.
Belgeler
Belgelerin otomatik olarak oluşturulabilmesi için kurallarınızı nasıl yorumlayacağınızla ilgili talimatlar için Stardoc dokümanlarına bakın.
Kural şablonu dokümanları/ klasörü, Starlark dosyaları güncellendiğinde 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ı neden ana Bazel GitHub deposuna ekleyemiyoruz?
Bazel sürümlerinden mümkün olduğunca kuralları birbirinden 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'a katkıda bulunmaktan daha hafif olabilir. Buna karşılık gelen GitHub deposuna tam gönderme erişimi de dahildir. Bazel'ın kendisine gönderme erişimi almak çok daha karmaşık bir süreçtir.
Olumsuz tarafı ise kullanıcılarımız için tek seferlik daha karmaşık bir yükleme işlemidir: Yukarıdaki README.md
bölümünde gösterildiği gibi, bir kuralı kopyalayıp WORKSPACE
dosyalarına yapıştırmaları 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ı kullanımdan kaldırmaya çalışıyoruz.