Bu sayfa, kurallarını başkalarına sunmayı planlayan kural yazarları içindir.
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 bazel-dev posta listesine ulaşın.
Bazel kurallarının depo adları şu 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 uygulamanız gerekir.
Açıklayıcı bir GitHub deposu açıklaması ve başlığı kullandığınızdan emin olun. README.md
Örneğin:
- 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 (Bazel'i bilmeyen kullanıcıları doğru yere yönlendirecek https://bazel.build bağlantısını kullanın)
Kurallar dile (ör. Scala) veya platforma (ör. Android) 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, (hayali) mockascript
dili için yeni kurallar yazılırken 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
WORKSPACE
Projenin WORKSPACE
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>
(ör. rules_mockascript
) kullanmanız gerekir. Aksi takdirde, deponuzu <org>_rules_<lang>
(ör. build_stack_rules_proto
) olarak adlandırmanız gerekir. Kurallarınızın bazelbuild kuruluşundaki kurallarla ilgili kurallara uyması gerektiğini düşünüyorsanız lütfen bazel-dev posta listesine ulaşın.
Aşağıdaki bölümlerde, deponun bazelbuild kuruluşuna ait olduğu varsayılır.
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 şöyle 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 deposun kurallarına bağlıysa bunu kurallar dokümanında belirtin (örneğin, Sass kurallarına bağlı Skydoc kurallarına bakın) ve tüm bağımlılıkları indiren bir WORKSPACE
makrosu sağlayın (yukarıdaki rules_go
bölümüne bakın).
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
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 ş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.
Runfiles kitaplığı
Kuralınız, çalışma dosyalarına erişmek için standart bir kitaplık sağlıyorsa bu kitaplık //<LANG>/runfiles
(//<LANG>/runfiles:runfiles
kısaltması) konumunda bulunan bir kitaplık hedefi şeklinde 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. Kurallarınıza bağlılığı basitleştirmek için lütfen bu harici bağımlılıklara olan bağımlılıkları açıklayacak 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ı belirtin. Geliştirme bağımlılıkları WORKSPACE
dosyasına yerleştirilir.
<LANG>/repositories.bzl
adlı bir dosya oluşturun ve rules_<LANG>_dependencies
adlı tek bir giriş noktası makrosu sağlayın. Dizinim aşağıdaki gibi görünür:
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
Araç zincirlerini kaydetme
Kurallarınızda araç zincirleri de kaydedilebilir. Lütfen bu araç zincirlerini kaydeden ayrı bir WORKSPACE
makrosu sağlayın. Bu sayede kullanıcılar, önceki makroyu çıkarmaya ve bağımlılıkları manuel olarak kontrol etmeye karar verebilirken araç zincirlerini kaydetmeye devam edebilir.
Bu nedenle, <LANG>/repositories.bzl
dosyasına rules_<LANG>_toolchains
adlı bir WORKSPACE
makrosu ekleyin.
Bazel'in, analiz aşamasında araç zincirlerini çözmek iç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 WORKSPACE
dosyalarına kopyalayıp yapıştırabilecekleri bir snippet sağlayın. Bu snippet genellikle 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 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.
Test
Travis'i başlangıç dokümanlarındaki talimatları uygulayarak ayarlayın. Ardından, aşağıdaki içeriğe sahip bir .travis.yml
dosyasını deponuza ekleyin:
dist: xenial # Ubuntu 16.04
# On trusty (or later) images, the Bazel apt repository can be used.
addons:
apt:
sources:
- sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
key_url: 'https://bazel.build/bazel-release.pub.gpg'
packages:
- bazel
script:
- bazel build //...
- bazel test //...
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.
SSS
Kuralımızı ana Bazel GitHub deposuna neden ekleyemiyoruz?
Kuralları Bazel sürümlerinden mümkün olduğunca ayırmak istiyoruz. Kurallar üzerinde kimin sahiplik sahibi olduğu daha net olduğundan Bazel geliştiricilerinin yükü azalır. Kullanıcılarımız için kuralların ayrılması, kuralları değiştirmeyi, yükseltmeyi, düşürmeyi ve değiştirmeyi 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'e 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: Yukarıdaki README.md
bölümünde gösterildiği gibi, bir kuralı WORKSPACE
dosyalarına kopyalayıp yapıştırmaları gerekir.
Tüm kurallar eskiden Bazel deposunda (//tools/build_rules
veya //tools/build_defs
altında) bulunuyordu. Hâlâ birkaç kural orada olsa da kalan kuralları taşımaya çalışıyoruz.