Kuralları Dağıtma

Bu sayfa, kurallarını diğer kullanıcıların kullanımına sunmayı planlayan kural yazarları içindir.

Şablon deposundan yeni bir kural grubu oluşturmanızı öneririz: https://github.com/bazel-contrib/rules-template Bu şablon, aşağıdaki önerilere uyar, API dokümanı oluşturma özelliğini içerir ve kural grubunuzu dağıtmayı kolaylaştırmak için bir CI/CD işlem hattı oluşturur.

Barındırma ve adlandırma kuralları

Yeni kurallar, kuruluşunuzun altında kendi GitHub 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ı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 kullanmanız gerekir.

Açıklayıcı bir GitHub deposu açıklaması ve README.md başlığı kullandığınızdan emin olun. Ö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 Go kuralları (Bazel'i bilmeyen kullanıcıları doğru yere yönlendirecek olan https://bazel.build bağlantısına dikkat edin)

Kurallar dil (ör. Scala), çalışma zamanı platformu (ör. Android) veya çerçeve (ör. Spring) gibi özelliklere göre gruplandırılabilir.

Depo içeriği

Her kural deposu, kullanıcıların yeni kuralları hızlı bir şekilde anlayabilmesi için belirli bir düzene sahip olmalıdır.

Örneğin, (hayali) mockascript dili için yeni kurallar yazarken 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 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 kurallar için geçerli olan kurala 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ğu varsayılmaktadır.

module(name = "rules_mockascript")

BENİOKU

En üst düzeyde, kural setinizin kısa bir açıklamasını ve API kullanıcılarının bekleyeceği bilgileri içeren bir README olmalıdır.

Kurallar

Genellikle, deponuz tarafından sağlanan birden fazla kural vardır. Dile göre adlandırılmış bir dizin oluşturun ve tüm kuralların dışa aktarıldığı bir defs.bzl dosyasıyla giriş noktası sağlayın (dizinin paket olması için BUILD dosyasını da ekleyin). rules_mockascript için bu, mockascript adlı bir dizin, BUILD dosyası ve defs.bzl dosyası olacağı anlamına gelir:

/
  mockascript/
    BUILD
    defs.bzl

Sınırlamalar

Kuralınız toolchain kurallarını tanımlıyorsa özel constraint_setting ve/veya constraint_value tanımlamanız gerekebilir. Bunları bir //<LANG>/constraintspakete yerleştirin. Dizin yapınız şu şekilde görünür:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

En iyi uygulamalar ve hangi kısıtlamaların zaten mevcut olduğunu görmek için lütfen github.com/bazelbuild/platforms adresini okuyun ve dil bağımsızlarsa kısıtlamalarınızı buraya eklemeyi düşünün. Ö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çimleri kullanma). Özel kısıtlamalarla, tüm Bazel ekosisteminin kullanacağı bir dil tanımlarsınız.

Runfiles kitaplığı

Kuralınız, çalışma zamanı dosyalarına erişmek için standart bir kitaplık sağlıyorsa bu kitaplık, //<LANG>/runfiles konumunda bulunan bir kitaplık hedefi biçiminde olmalıdır (//<LANG>/runfiles:runfiles kısaltması). 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ızın harici bağımlılıkları olabilir. Bu bağımlılıkları MODULE.bazel dosyanızda belirtmeniz gerekir.

Araç zincirlerini kaydetme

Kurallarınız, araç zincirlerini de kaydedebilir. Bunları MODULE.bazel dosyasında da belirtebilirsiniz.

Bazel'in analiz aşamasında araç zincirlerini çözebilmesi 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 toolchain hedefli depoyu <LANG>_toolchain hedefli depoyla bölmeyi düşünebilirsiniz. Birincisi her zaman getirilir, ikincisi ise yalnızca kullanıcının <LANG> kodunu oluşturması gerektiğinde getirilir.

Yayın snippet'i

Yayın duyurunuzda, kullanıcılarınızın MODULE.bazel dosyalarına kopyalayıp yapıştırabileceği bir snippet sağlayın. 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 geçerli olduğu dilin standart konumunda veya üst düzeyde bir tests/ dizininde olabilir.

Örnekler (isteğe bağlı)

Kullanıcılara, kuralların kullanılabileceği birkaç temel yolu gösteren bir examples/ dizini oluşturmak faydalı olur.

CI/CD

Birçok kural kümesi GitHub Actions'ı kullanır. bazel-contrib org'da barındırılan "yeniden kullanılabilir iş akışı" ile basitleştirilmiş rules-template deposunda kullanılan yapılandırmaya bakın. ci.yaml her çekme isteğinde ve main taahhüdünde testleri çalıştırır. release.yaml ise depoya bir etiket aktardığınızda çalışır. Daha fazla bilgi için kurallar şablonu deposundaki yorumlara bakın.

Deponuz bazelbuild kuruluşunun altındaysa eklenmesini isteyebilirsiniz ci.bazel.build.

Belgeler

Kurallarınıza nasıl yorum ekleyeceğinizle ilgili talimatlar için Stardoc belgelerine bakın. Bu sayede belgeler otomatik olarak oluşturulabilir.

rules-template docs/ klasörü, Starlark dosyaları güncellendikçe 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?

Kuralları Bazel sürümlerinden mümkün olduğunca ayırmak istiyoruz. Hangi kuralın kime ait olduğu daha net anlaşılır. Böylece Bazel geliştiricilerin üzerindeki yük azalır. Ayrıştırma, kullanıcılarımızın kuralları değiştirmesini, yükseltmesini, düşürmesini ve değiştirmesini kolaylaştırır. Kurallara katkıda bulunmak, Bazel'e katkıda bulunmaktan daha kolay olabilir. Bu durum, ilgili GitHub deposuna tam gönderme erişimi de dahil olmak üzere kurallara bağlıdır. Bazel'e gönderme erişimi elde etmek çok daha karmaşık bir süreçtir.

Bununla birlikte, kullanıcılarımız için tek seferlik kurulum süreci daha karmaşık hale gelir: Kullanıcılar, MODULE.bazel dosyalarına kural setinize bağlılığı eklemek zorundadır.

Eskiden tüm kurallar Bazel deposunda (//tools/build_rules veya //tools/build_defs altında) yer alıyordu. Burada hâlâ birkaç kural var ancak kalan kuralları taşımak için çalışıyoruz.