Kuralları Dağıtma

Sorun bildir 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:

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

module(name = "rules_mockascript")

BENİOKU

Üst düzeyde, kısa bir açıklama içeren bir README olmalıdır ve API kullanıcılarının beklemesi gereken özellikleri içerir.

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 dahil edin). 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ızın harici bağımlılıklar olabilir. Bu bağımlılıkları MODULE.bazel dosyanız.

Araç zincirleri kaydediliyor

Kurallarınız, MODULE.bazel dosyası oluşturun.

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 için 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. MODULE.bazel dosyasına ekleyebilir. Bu snippet, genel olarak 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 kuralların hedeflendiği dil 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: MODULE.bazel dosyasında kural grubunuza bir bağımlılık eklemesi gerekir.

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.