Bu sayfa, kurallarını başkalarına açık hale getirmeyi 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 uyar, API belgeleri oluşturma özelliğini içerir ve kural grubunuzun kolayca dağıtılmasını sağlamak 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 kod deposuna gitmelidir. 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ı şu biçimde standart hale getirilir:
$ORGANIZATION/rules_$NAME
.
GitHub'daki örneklere bakın.
Tutarlılık için Bazel kurallarınızı yayınlarken aynı biçimi izlemelisiniz.
Açıklayıcı bir GitHub deposu açıklaması ve README.md
başlığı kullandığınızdan emin olun. Örneğin:
- Kod deposu adı:
bazelbuild/rules_go
- Kod deposu açıklaması: Bazel için Go kuralları
- Kod deposu etiketleri:
golang
,bazel
README.md
üstbilgisi: Bazel için kuralları gidin (Bazel'i bilmeyen kullanıcıları doğru yere yönlendirecek https://bazel.build bağlantısını unutmayın)
Kurallar, dile (Scala gibi), çalışma zamanı platformuna (Android gibi) veya çerçeveye (Spring gibi) 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, (make-believe) 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 referansta bulunmak 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ırmanız gerekir (ör. build_stack_rules_proto
). Kurallarınızın bazelbuild kuruluşundaki kural kurallarına uyması gerektiğini düşünüyorsanız lütfen GitHub'da bir ileti dizisi başlatın.
Aşağıdaki bölümlerde deponun bazelbuild kuruluşuna ait olduğunu varsayalım.
workspace(name = "rules_mockascript")
BENİOKU
En üst düzeyde, kullanıcıların kuralınızı kullanabilmeleri için kopyalayıp WORKSPACE
dosyalarına yapıştırmaları gerekenleri (en azından) içeren bir README
olmalıdır.
Genel olarak bu, GitHub sürümünüzü gösteren bir http_archive
ve kuralınızın ihtiyaç duyduğu araçları indiren/yapılandıran bir makro çağrısı olur. Örneğin, Go kuralları için ş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 dayanıyorsa bunu kural belgelerinde 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
Genellikle deponuz tarafından sağlanan birden fazla kural bulunur. Dille adlandırılmış bir dizin oluşturun ve bir giriş noktası sağlayın: defs.bzl
dosyası, tüm kuralları dışa aktarır (ayrıca 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 yerleştirin. Dizin yapınız şöyle görünür:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
En iyi uygulamaları öğrenmek ve halihazırda hangi kısıtlamaların geçerli olduğunu öğrenmek için lütfen github.com/bazelbuild/platforms adresindeki sayfayı okuyun ve dilden bağımsız olan kısıtlamalarınızı burada paylaşmayı düşünün.
Özel kısıtlamalar uygulamaya dikkat edin. Kurallarınızın tüm kullanıcıları, BUILD
dosyalarında platforma özgü mantık gerçekleştirmek için bu kuralları kullanacaktır (örneğin, seçimler kullanarak).
Ö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şmek için standart bir kitaplık sağlıyorsa //<LANG>/runfiles
adresinde bulunan bir kitaplık hedefi (//<LANG>/runfiles:runfiles
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.
Kod deposu kuralları
Bağımlılıklar
Kurallarınızın harici bağımlılıkları olabilir. Kurallarınıza bağlı kalmayı kolaylaştırmak için lütfen bu dış bağımlılıklara bağımlılık bildiren bir WORKSPACE
makrosu sağlayın. Burada testlerin bağımlılıklarını değil, yalnızca kuralların çalışması için gereken bağımlılıkları bildirin. Geliştirme bağımlılıklarını WORKSPACE
dosyasına yerleştirin.
<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ç zincirlerini kaydetme
Kurallarınız, araç zincirlerini de kaydedebilir. Lütfen bu araç zincirlerini kaydeden ayrı bir WORKSPACE
makrosu sağlayın. Bu şekilde, kullanıcılar araç zincirlerini kaydetmelerine izin verirken önceki makroyu atlamaya karar verebilir ve bağımlılıkları manuel olarak kontrol 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 gerçekleştirmeniz gerekiyorsa depoyu kod deposundaki toolchain
hedefleriyle <LANG>_toolchain
hedefleriyle bölmeyi düşünün. Eski etiket her zaman getirilir. İkinci yöntem, 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 kendi 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, kuralların geçerli olduğu dilin standart konumunda veya en üst düzeydeki bir tests/
dizini olabilir.
Örnekler (isteğe bağlı)
Kuralların kullanılabilmesine yönelik birkaç temel yöntemin kullanıcılara gösterildiği bir examples/
dizininin olması kullanıcılar açısından faydalıdır.
CI/CD
Birçok kural kümesi, GitHub İşlemlerini kullanır. rules-template deposunda kullanılan yapılandırmaya bakın. Bu yapılandırma, bazel-contrib kuruluşunda barındırılan bir "yeniden kullanılabilir iş akışı" ile basitleştirilmiştir. ci.yaml
, her PR ve main
kombinasyonunda testler çalıştırır ve depoya bir etiket aktardığınızda release.yaml
çalıştırılır.
Daha fazla bilgi için kural şablonu deposundaki yorumları inceleyin.
Deponuz bazelbuild kuruluşu altındaysa deponuzun ci.bazel.build'e eklenmesini 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.
rules-template docs/ 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 Bazel GitHub deposuna ana ekleyemiyoruz?
Kuralları Bazel sürümlerinden mümkün olduğunca ayırmak istiyoruz. Bağımsız kurallara kimin sahip olduğu daha net bir şekilde anlaşılmıştır. Böylece Bazel geliştiricilerinin üzerindeki yük azalmıştır. Ayırma işlemi, kullanıcılarımız için kuralları değiştirmeyi, yeni sürüme geçirmeyi, eski sürüme geçirmeyi ve değiştirmeyi kolaylaştırır. Kurallara bağlı olarak, ilgili GitHub deposuna tam gönderim erişimi de dahil olmak üzere, kurallara katkıda bulunmak Bazel'e katkıda bulunmaktan daha hafif olabilir. Bazel'a gönderim erişimi almak çok daha karmaşık bir işlemdir.
Olumsuz tarafı ise kullanıcılarımız için daha karmaşık, tek seferlik bir yükleme işlemi olmasıdır:
Yukarıdaki README.md
bölümünde gösterildiği gibi, kullanıcıların bir kuralı kopyalayıp WORKSPACE
dosyalarına yapıştırmaları gerekir.
Eskiden tüm kurallar Bazel deposunda (//tools/build_rules
veya //tools/build_defs
altında) vardı. Bazı kurallarımız var
ancak kalan kuralların taşınması için çalışıyoruz.