Kuralları Dağıtma

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

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 bazel-dev posta listesine ulaşı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 README.md başlığı kullanın. Örnek:

  • 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 Go kuralları (Bazel'i bilmeyen kullanıcıları doğru yere yönlendirecek https://bazel.build bağlantısına dikkat edin)

Kurallar dile (ör. Scala) veya platforma (ör. Android) göre gruplandırılabilir.

Depo içeriği

Kullanıcıların yeni kuralları hızla 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
  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 kurallarla ilgili kurallara uyması gerektiğini düşünüyorsanız lütfen bazel-dev posta listesine ulaşın.

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

workspace(name = "rules_mockascript")

BENİOKU

Üst düzeyde, kullanıcıların kuralınızı kullanmak için WORKSPACE dosyalarına kopyalayıp yapıştırması gerekenleri (en azından) 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. 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 adında bir dizin ve BUILD dosyası ile defs.bzl dosyasının içinde 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 için lütfen github.com/bazelbuild/platforms adresini okuyun ve mevcut kısıtlamalara bakın. Kısıtlamalar dilden bağımsızsa o sayfada kısıtlarınızı da katkıda bulunmayı düşünebilirsiniz. Ö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ıştırma dosyalarına erişmek için standart bir kitaplık sağlıyorsa //<LANG>/runfiles konumunda bulunan bir kitaplık hedefi (//<LANG>/runfiles:runfiles adının 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.

Depo kuralları

Bağımlılıklar

Kurallarınızda dış bağımlılıklar olabilir. Kurallarınıza bağlı olarak süreci kolaylaştırmak için lütfen bu dış bağımlılıklara bağımlılıkları bildirecek 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. Dizinimiz aşağıdaki gibi görünür:

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

Araç zincirlerini kaydetme

Kurallarınızda araç zincirleri de kaydedilebilir. 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.

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 yapmanız gerekiyorsa depoyu toolchain hedefleriyle birlikte, <LANG>_toolchain hedefleri olan depodan bölmeyi düşünün. İlki her zaman getirilir, ikincisi ise yalnızca kullanıcının <LANG> kodu oluşturması gerektiğinde getirilir.

Sürüm snippet'i

Sürüm duyurunuzda, kullanıcılarınızın WORKSPACE dosyalarına kopyalayıp 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 konum, kuralların hedeflendiği dil için standart konumda veya en üst düzeyde 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.

Test

Travis'i başlangıç dokümanlarındaki talimatları uygulayarak ayarlayın. Sonra aşağıdaki içeriğe sahip bir .travis.yml dosyasını deponuza ekleyin:

dist: xenial  # Ubuntu 16.04

# On trusty (or later) images, the Bazel apt repository can be used.
addons:
  apt:
    sources:
    - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
      key_url: 'https://bazel.build/bazel-release.pub.gpg'
    packages:
    - bazel

script:
  - bazel build //...
  - bazel test //...

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

SSS

Kuralımızı ana Bazel GitHub deposuna neden ekleyemiyoruz?

Bazel sürümlerinden mümkün olduğunca kuralları birbirinden ayırmak istiyoruz. Kurallar üzerinde kimin sahiplik sahibi olduğu daha net olduğundan Bazel geliştiricilerinin 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ö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: Yukarıdaki README.md bölümünde gösterildiği gibi, bir kuralı WORKSPACE dosyalarına kopyalayıp yapıştırmaları gerekir.

Tüm kurallar eskiden Bazel deposunda (//tools/build_rules veya //tools/build_defs altında) bulunuyordu. Hâlâ orada birkaç kuralımız var ancak kalan kuralları da taşımaya çalışıyoruz.