Kuralları Dağıtma

. Sorun bildirin Kaynağı göster Gece · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

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:

  • 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 (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
  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 kullanacağı adı tanımlamanız gerekir. kullanmanızı öneririz. Kurallarınız bazelbuild yapısında 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.

workspace(name = "rules_mockascript")

BENİOKU

Üst düzeyde, en azından şunu içeren bir README olmalıdır: kullanıcıların kuralınızı kullanmak için kopyalayıp WORKSPACE dosyasına yapıştırması gerekir. Genel olarak bu, GitHub sürümünüzü işaret eden bir http_archive olur ve kuralınızın ihtiyaç duyduğu araçları indiren/yapılandıran bir makro çağrısı. Örneğin, Go için kuralları seçerseniz şö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 deponun kurallarına bağlıysa bunu (örneğin, bkz. Skydoc kuralları, Bunlar, Sass kurallarına bağlıdır) ve bir WORKSPACE sağlayın makrosuna göz atın (yukarıdaki rules_go adresine bakın).

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 ekleyin). 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ızda dış bağımlılıklar olabilir. Kurallarınıza bağlı olarak daha basit olursa lütfen öğelere bağımlılıkları bildirecek bir WORKSPACE makrosu sağlayın bu dış bağımlılıkları sayabiliriz. Testlerin bağımlılıklarını burada bildirmeyin, yalnızca ve kuralların çalışması için gereken bağımlılıkları ifade eder. Geliştirme bağımlılıklarını WORKSPACE dosyası yükleyin.

<LANG>/repositories.bzl adında bir dosya oluşturun ve tek bir giriş noktası sağlayın rules_<LANG>_dependencies adlı makroyu kullanı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 ayrı bir WORKSPACE belirtin. makrosu tarafından kontrol edilir. Böylece kullanıcılar önceki makroyu kontrol edebilir ve bağımlılıkları manuel olarak kontrol edebilirsiniz. araç zincirlerini kaydedin.

Dolayısıyla, rules_<LANG>_toolchains adlı WORKSPACE makroyu <LANG>/repositories.bzl dosyası.

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 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. WORKSPACE dosyasına ekleyebilir. 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 dili 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: WORKSPACE dosyasına aşağıda gösterildiği gibi bir kuralı kopyalayıp yapıştırmaları gerekir Yukarıdaki README.md bölümü.

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.