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 ardışık düzeni oluşturur.

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 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 göz atı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 başlık: Bazel için kurallara gidin (Bazel'i bilmeyen kullanıcıları doğru yere yönlendirecek https://bazel.build bağlantısına dikkat edin)

Kurallar dile (ör. Scala), çalışma zamanı platformuna (ör. Android) veya çerçeveye (ör. Spring) 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 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, kod 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 GitHub'da bir ileti dizisi başlatın.

Aşağıdaki bölümlerde, deponun bazelbuild kuruluşuna ait olduğu varsayılır.

module(name = "rules_mockascript")

BENİOKU

Üst düzeyde, kural kümenizin kısa bir açıklamasını içeren bir README olmalıdır ve API kullanıcılarının bunu beklemesi gerekir.

Kurallar

Deponuz genellikle birden fazla kural sağlar. Dilin adıyla bir dizin oluşturun ve bir giriş noktası sağlayın. Tüm kuralları dışa aktaran defs.bzl dosyası (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 koyun. Dizin yapınız şu şekilde görünür:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

En iyi uygulamalar ve mevcut kısıtlamaları görmek için lütfen github.com/bazelbuild/platforms adresini inceleyin. Dilden bağımsız kısıtlamalarınızı buraya gönderebilirsiniz. Ö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.

Çalışma dosyası 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. Bu bağımlılıkları MODULE.bazel dosyanızda belirtmeniz gerekir.

Araç zincirlerini kaydetme

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

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çlar zincirlerini kaydettirmek için depoda karmaşık hesaplamalar yapmanız gerekiyorsa toolchain hedefli deposu <LANG>_toolchain hedefli depodan ayırabilirsiniz. İ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 MODULE.bazel dosyalarına kopyalayıp yapıştırabilecekleri bir snippet sağlayın. Bu snippet genellikle 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 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.

CI/CD

Birçok kural kümesi GitHub Actions'ı kullanır. rules-template deposunda kullanılan yapılandırmaya bakın. Bu yapılandırma, bazel-contrib.org'da barındırılan "yeniden kullanılabilir bir iş akışı" kullanılarak basitleştirilmiştir. ci.yaml, her PR ve main commit'te testler çalıştırır. release.yaml ise depoya bir etiket aktardığınızda her zaman çalışır. Daha fazla bilgi için rules-template deposundaki yorumları inceleyin.

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 ekleyeceğinizle ilgili talimatlar için Stardoc belgelerine bakın.

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ı ana Bazel GitHub deposuna neden ekleyemiyoruz?

Kuralları Bazel sürümlerinden mümkün olduğunca ayırmak istiyoruz. Kurallar için kimin sorumlu 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önderim 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: MODULE.bazel dosyalarında kural kümenize bağımlılık eklemeleri 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.