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ı 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 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
  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

WORKSPACE

Projenin WORKSPACE 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ılır.

workspace(name = "rules_mockascript")

BENİOKU

En üst düzeyde, kullanıcıların kuralınızı kullanmak için README dosyalarına kopyalayıp yapıştırmaları gereken (en azından) bilgileri içeren bir WORKSPACE olmalıdır. Genel olarak bu, GitHub sürümünüze işaret eden bir http_archive ve kuralınızın ihtiyaç duyduğu araçları indirip yapılandıran bir makro çağrısı olur. Örneğin, Go kuralları için bu durum ş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 bağlıysa bunu kurallar dokümanlarında 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 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 özel mantık yürütmek için bu kısıtlamaları kullanır (örneğin, seçimler kullanma). Özel kısıtlamalarla, tüm Bazel ekosisteminin kullanacağı bir dil tanımlarsınız.

Runfiles kitaplığı

Kuralınız, runfile'lara 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 dış bağımlılıkları olabilir. Kurallarınıza bağlılığı kolaylaştırmak için lütfen bu harici bağımlılıklarla ilgili bağımlılıkları bildirecek bir WORKSPACE makrosu sağlayın. Testlerin bağımlılıklarını burada 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ünecektir:

/
  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 sayede kullanıcılar, önceki makroyu atlamaya ve bağımlılıkları manuel olarak kontrol etmeye karar verebilir. Ayrıca, araç zincirlerini kaydetmeye devam edebilirler.

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

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 hedefleri olan depoyu <LANG>_toolchain hedefleri olan 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

Sürüm duyurunuzda, kullanıcılarınızın WORKSPACE 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:

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 ü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 dokümanlarına bakın. Bu sayede dokümanlar 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 kuralların kime ait olduğu daha net anlaşılır. Böylece Bazel geliştiricilerinin 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, kurallara bağlı olarak ilgili GitHub deposuna tam gönderme erişimi de dahil olmak üzere değişebilir. 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, yukarıdaki README.md bölümünde gösterildiği gibi bir kuralı WORKSPACE dosyalarına kopyalayıp yapıştırmak 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.