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ğine sahiptir 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şunuz bünyesindeki kendi GitHub deposuna yerleştirilmelidir. 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ı 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 uygulamanız gerekir.

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

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

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 yazılırken 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 başvurmak 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ğunu varsayın.

workspace(name = "rules_mockascript")

BENİOKU

Üst düzeyde, (en azından) kullanıcıların kuralınızı kullanmak için WORKSPACE dosyalarına kopyalayıp yapıştırmaları gereken öğeleri içeren bir README olmalıdır. Genel olarak bu, GitHub sürümünüzü işaret eden bir http_archive ve kuralınızın ihtiyaç duyduğu tüm araçları indiren/yapılandıran bir makro çağrısı olacaktır. Örneğin, Go kuralları için bu değer ş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 kural 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

Çoğu zaman deponuz tarafından sağlanan birden fazla kural olur. Dile göre adlandırılmış bir dizin oluşturun ve bir giriş noktası sağlayın - defs.bzl tüm kuralları dışa aktarın (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 ş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 sunmaya dikkat edin. Kurallarınızın tüm kullanıcıları, BUILD dosyalarında platforma özel mantık gerçekleştirmek (örneğin, selects kullanarak) için bunları kullanır. Özel kısıtlamalarla tüm Bazel ekosisteminin konuşacağı bir dil tanımlarsınız.

Runfiles 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 dış bağımlılıklar olabilir. Kurallarınıza bağlılığı basitleştirmek için lütfen bu harici bağımlılıklara olan bağımlılıkları açıklayacak 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ı belirtin. WORKSPACE dosyasına geliştirme bağımlılıkları ekleyin.

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

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

Araç zincirlerini kaydetme

Kurallarınız araç zincirleri de kaydedebilir. Lütfen bu araç zincirlerini kaydeden ayrı bir WORKSPACE makrosu sağlayın. Bu sayede kullanıcılar, önceki makroyu çıkarmaya ve bağımlılıkları manuel olarak kontrol etmeye karar verebilirken araç zincirlerini kaydetmeye devam edebilir.

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

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ç zincirlerini kaydetmek için depoda karmaşık hesaplamalar yapmanız gerekiyorsa depoyu toolchain hedefleriyle birlikte, <LANG>_toolchain hedefleri olan depodan bölmeyi düşünün. Önceki kod her zaman, 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 WORKSPACE dosyalarına yapıştırabilecekleri bir snippet sağlayın. Bu snippet genellikle 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 konum, kuralların hedeflendiği dil için standart konumda veya en üst düzeyde tests/ dizininde olabilir.

Örnekler (isteğe bağlı)

Kuralların kullanılabileceği birkaç temel yöntemi kullanıcılara gösteren bir examples/ dizininin olması kullanıcılar açısından faydalıdı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 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 ci.bazel.build bölümüne eklemenizi 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ü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?

Bazel sürümlerinden mümkün olduğunca kuralları birbirinden ayırmak istiyoruz. Ayrı kuralların kime ait olduğu daha net bir şekilde anlaşılır ve Bazel geliştiricilerinin üzerindeki yük azalır. Ayrıştırma, kullanıcılarımızın kuralları değiştirme, yükseltme, düşürme ve değiştirme işlemlerini 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önderme erişimi de içerir. Bazel'e gönderme erişimi almak çok daha karmaşık bir süreçtir.

Olumsuz tarafı ise kullanıcılarımız için tek seferlik daha karmaşık bir yükleme işlemidir: Yukarıdaki README.md bölümünde gösterildiği gibi, bir kuralı kopyalayıp WORKSPACE dosyalarına yapıştırmaları 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.