Kuralları Dağıtma

Sorun bildir Kaynağı göster

Bu sayfa, kurallarını başkalarına açık hale getirmeyi 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 uyar, API belgeleri oluşturma özelliğini içerir ve kural grubunuzun kolayca dağıtılmasını sağlamak 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 kod 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ı için depo adları şu biçimde standart hale getirilir: $ORGANIZATION/rules_$NAME. GitHub'daki örneklere bakın. Tutarlılık için Bazel kurallarınızı yayınlarken aynı biçimi izlemelisiniz.

Açıklayıcı bir GitHub deposu açıklaması ve README.md başlığı kullandığınızdan emin olun. Örneğin:

  • Kod deposu adı: bazelbuild/rules_go
  • Kod deposu açıklaması: Bazel için Go kuralları
  • Kod deposu etiketleri: golang, bazel
  • README.md üstbilgisi: Bazel için kuralları gidin (Bazel'i bilmeyen kullanıcıları doğru yere yönlendirecek https://bazel.build bağlantısını unutmayın)

Kurallar, dile (Scala gibi), çalışma zamanı platformuna (Android gibi) veya çerçeveye (Spring gibi) 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, (make-believe) mockascript dili için yeni kurallar yazarken 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 kurallarınıza referansta bulunmak için kullanacağı adı tanımlamanız gerekir. Kurallarınız bazelbuild kuruluşuna aitse rules_<lang> (rules_mockascript gibi) kullanmanız gerekir. Aksi takdirde, deponuzu <org>_rules_<lang> olarak adlandırmanız gerekir (ör. build_stack_rules_proto). Kurallarınızın bazelbuild kuruluşundaki kural kurallarına 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ğunu varsayalım.

workspace(name = "rules_mockascript")

BENİOKU

En üst düzeyde, kullanıcıların kuralınızı kullanabilmeleri için kopyalayıp WORKSPACE dosyalarına yapıştırmaları gerekenleri (en azından) içeren bir README olmalıdır. Genel olarak bu, GitHub sürümünüzü gösteren bir http_archive ve kuralınızın ihtiyaç duyduğu araçları indiren/yapılandıran bir makro çağrısı olur. Örneğin, Go kuralları için şu şekilde 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 dayanıyorsa bunu kural belgelerinde belirtin (örneğin, Sass kurallarına bağlı olan Skydoc kurallarına bakın) ve tüm bağımlılıkları indirecek bir WORKSPACE makrosu sağlayın (yukarıdaki rules_go bölümüne bakın).

Kurallar

Genellikle deponuz tarafından sağlanan birden fazla kural bulunur. Dille adlandırılmış bir dizin oluşturun ve bir giriş noktası sağlayın: defs.bzl dosyası, tüm kuralları dışa aktarır (ayrıca 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 yerleştirin. Dizin yapınız şöyle görünür:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

En iyi uygulamaları öğrenmek ve halihazırda hangi kısıtlamaların geçerli olduğunu öğrenmek için lütfen github.com/bazelbuild/platforms adresindeki sayfayı okuyun ve dilden bağımsız olan kısıtlamalarınızı burada paylaşmayı düşünün. Özel kısıtlamalar uygulamaya dikkat edin. Kurallarınızın tüm kullanıcıları, BUILD dosyalarında platforma özgü mantık gerçekleştirmek için bu kuralları kullanacaktır (örneğin, seçimler kullanarak). Özel kısıtlamalarla, tüm Bazel ekosisteminin konuşacağı bir dil tanımlarsınız.

Runfiles kitaplığı

Kuralınız çalıştırma dosyalarına erişmek için standart bir kitaplık sağlıyorsa //<LANG>/runfiles adresinde bulunan bir kitaplık hedefi (//<LANG>/runfiles:runfiles kısaltması) biçiminde olmalıdır. Veri bağımlılıklarına erişmesi gereken kullanıcı hedefleri genellikle bu hedefi deps özelliklerine ekler.

Kod deposu kuralları

Bağımlılıklar

Kurallarınızın harici bağımlılıkları olabilir. Kurallarınıza bağlı kalmayı kolaylaştırmak için lütfen bu dış bağımlılıklara bağımlılık bildiren 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ı bildirin. Geliştirme bağımlılıklarını WORKSPACE dosyasına yerleştirin.

<LANG>/repositories.bzl adlı bir dosya oluşturun ve rules_<LANG>_dependencies adlı tek bir giriş noktası makrosu sağlayın. Dizinimiz aşağıdaki gibi görünür:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

Araç zincirlerini kaydetme

Kurallarınız, araç zincirlerini de kaydedebilir. Lütfen bu araç zincirlerini kaydeden ayrı bir WORKSPACE makrosu sağlayın. Bu şekilde, kullanıcılar araç zincirlerini kaydetmelerine izin verirken önceki makroyu atlamaya karar verebilir ve bağımlılıkları manuel olarak kontrol edebilir.

Bu nedenle, <LANG>/repositories.bzl dosyasına rules_<LANG>_toolchains adlı bir WORKSPACE makrosu ekleyin.

Analiz aşamasında araç zincirlerini çözümleyebilmek için Bazel'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 gerçekleştirmeniz gerekiyorsa depoyu kod deposundaki toolchain hedefleriyle <LANG>_toolchain hedefleriyle bölmeyi düşünün. Eski etiket her zaman getirilir. İkinci yöntem, 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 kendi WORKSPACE dosyalarına yapıştırabilecekleri bir snippet sağlayın. 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 geçerli olduğu dilin standart konumunda veya en üst düzeydeki bir tests/ dizini olabilir.

Örnekler (isteğe bağlı)

Kuralların kullanılabilmesine yönelik birkaç temel yöntemin kullanıcılara gösterildiği bir examples/ dizininin olması kullanıcılar açısından faydalıdır.

CI/CD

Birçok kural kümesi, GitHub İşlemlerini kullanır. rules-template deposunda kullanılan yapılandırmaya bakın. Bu yapılandırma, bazel-contrib kuruluşunda barındırılan bir "yeniden kullanılabilir iş akışı" ile basitleştirilmiştir. ci.yaml, her PR ve main kombinasyonunda testler çalıştırır ve depoya bir etiket aktardığınızda release.yaml çalıştırılır. Daha fazla bilgi için kural şablonu deposundaki yorumları inceleyin.

Deponuz bazelbuild kuruluşu altındaysa deponuzun ci.bazel.build'e eklenmesini isteyebilirsiniz.

Belgeler

Belgelerin otomatik olarak oluşturulabilmesi için kurallarınızı nasıl yorumlayacağınızla ilgili talimatlar için Stardoc dokümanlarına bakın.

rules-template docs/ klasörü, Starlark dosyaları güncellendiğinde 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 Bazel GitHub deposuna ana ekleyemiyoruz?

Kuralları Bazel sürümlerinden mümkün olduğunca ayırmak istiyoruz. Bağımsız kurallara kimin sahip olduğu daha net bir şekilde anlaşılmıştır. Böylece Bazel geliştiricilerinin üzerindeki yük azalmıştır. Ayırma işlemi, kullanıcılarımız için kuralları değiştirmeyi, yeni sürüme geçirmeyi, eski sürüme geçirmeyi ve değiştirmeyi kolaylaştırır. Kurallara bağlı olarak, ilgili GitHub deposuna tam gönderim erişimi de dahil olmak üzere, kurallara katkıda bulunmak Bazel'e katkıda bulunmaktan daha hafif olabilir. Bazel'a gönderim erişimi almak çok daha karmaşık bir işlemdir.

Olumsuz tarafı ise kullanıcılarımız için daha karmaşık, tek seferlik bir yükleme işlemi olmasıdır: Yukarıdaki README.md bölümünde gösterildiği gibi, kullanıcıların bir kuralı kopyalayıp WORKSPACE dosyalarına yapıştırmaları gerekir.

Eskiden tüm kurallar Bazel deposunda (//tools/build_rules veya //tools/build_defs altında) vardı. Bazı kurallarımız var ancak kalan kuralların taşınması için çalışıyoruz.