ルールのデプロイ

問題を報告する ソースを表示 ナイトリー · 7.4 .

このページは、ルールを他のユーザーに公開する予定のルール作成者を対象としています。

新しいルールセットは、テンプレート リポジトリ(https://github.com/bazel-contrib/rules-template)から作成することをおすすめします。このテンプレートは、以下の推奨事項に準拠しており、API ドキュメントの生成が含まれており、CI / CD パイプラインを設定して、ルールセットの配布を簡単に行えます。

ホスティング ルールと命名規則

新しいルールは、組織の GitHub リポジトリに配置する必要があります。ルールが bazelbuild 組織に属していると思われる場合は、GitHub でスレッドを開始します。

Bazel ルールのリポジトリ名は、$ORGANIZATION/rules_$NAME の形式で標準化されています。GitHub の例をご覧ください。一貫性を保つため、Bazel ルールを公開する際も同じ形式にする必要があります。

説明的な GitHub リポジトリの説明と README.md タイトルを使用してください。例:

  • リポジトリ名: bazelbuild/rules_go
  • リポジトリの説明: Bazel の Go ルール
  • リポジトリ タグ: golangbazel
  • README.md ヘッダー: Bazel の Go ルール(Bazel に慣れていないユーザーを適切な場所に案内する https://bazel.build へのリンクに注意してください)

ルールは、言語(Scala など)、ランタイム プラットフォーム(Android など)、フレームワーク(Spring など)でグループ化できます。

リポジトリのコンテンツ

すべてのルール リポジトリには、ユーザーが新しいルールをすばやく理解できるように、特定のレイアウトが必要です。

たとえば、mockascript 言語(make-believe)用に新しいルールを作成する場合、ルール リポジトリの構造は次のようになります。

/
  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

プロジェクトの MODULE.bazel で、ユーザーがルールの参照に使用する名前を定義する必要があります。ルールが bazelbuild 組織に属している場合は、rules_<lang>rules_mockascript など)を使用する必要があります。それ以外の場合は、リポジトリに <org>_rules_<lang>build_stack_rules_proto など)という名前を付ける必要があります。ルールを bazelbuild 組織のルールの規則に従う必要がある場合は、GitHub でスレッドを開始してください。

以降のセクションでは、リポジトリが bazelbuild 組織に属しているとします。

module(name = "rules_mockascript")

README

最上位には、ルールセットの簡単な説明と、API ユーザーが期待する内容を含む README が必要です。

ルール

多くの場合、リポジトリから複数のルールが提供されます。言語で名前を付けたディレクトリを作成し、エントリ ポイント(すべてのルールをエクスポートする defs.bzl ファイル)を指定します(ディレクトリがパッケージになるように BUILD ファイルも含めます)。rules_mockascript の場合、mockascript という名前のディレクトリと、その中に BUILD ファイルと defs.bzl ファイルが存在します。

/
  mockascript/
    BUILD
    defs.bzl

制約

ルールでツールチェーン ルールを定義する場合は、カスタムの constraint_settingconstraint_value を定義する必要がある場合があります。これらを //<LANG>/constraints パッケージに格納します。ディレクトリ構造は次のようになります。

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

ベスト プラクティスと既存の制約については、github.com/bazelbuild/platforms をご覧ください。言語に依存しない場合は、そちらに投稿することをおすすめします。カスタム制約の導入に注意してください。ルールのすべてのユーザーは、カスタム制約を使用して BUILD ファイルでプラットフォーム固有のロジックを実行します(たとえば、select)。カスタム制約を使用すると、Bazel エコシステム全体が使用する言語を定義できます。

Runfiles ライブラリ

ランファイルにアクセスするための標準ライブラリがルールで提供されている場合は、//<LANG>/runfiles//<LANG>/runfiles:runfiles の略語)にあるライブラリ ターゲットの形式にする必要があります。データ依存関係にアクセスする必要があるユーザー ターゲットは通常、このターゲットを deps 属性に追加します。

リポジトリ ルール

依存関係

ルールに外部依存関係がある場合は、MODULE.bazel ファイルで指定する必要があります。

ツールチェーンの登録

ルールでツールチェーンを登録することもできます。ツールチェーンは MODULE.bazel ファイルで指定することもできます。

分析フェーズでツールチェーンを解決するには、Bazel は登録されているすべての toolchain ターゲットを分析する必要があります。Bazel は、toolchain.toolchain 属性で参照されるすべてのターゲットを分析する必要がなくなります。ツールチェーンを登録するために、リポジトリで複雑な計算を実行する必要がある場合は、<LANG>_toolchain ターゲットを使用して、リポジトリの toolchain ターゲットでリポジトリを分割することを検討してください。前者は常にフェッチされ、後者はユーザーが実際に <LANG> コードをビルドする必要がある場合にのみフェッチされます。

リリース スニペット

リリースのお知らせで、ユーザーが MODULE.bazel ファイルにコピーして貼り付けることができるスニペットを提供します。このスニペットは通常、次のようになります。

bazel_dep(name = "rules_<LANG>", version = "<VERSION>")

テスト

ルールが想定どおりに機能していることを確認するテストが必要です。これは、ルールが適用される言語の標準の場所、または最上位の tests/ ディレクトリに配置できます。

例(省略可)

ルールの基本的な使用方法を示す examples/ ディレクトリがあると、ユーザーにとって便利です。

CI / CD

多くのルールセットで GitHub Actions が使用されています。rules-template リポジトリで使用されている構成をご覧ください。これは、bazel-contrib org でホストされている「再利用可能なワークフロー」を使用して簡素化されています。ci.yaml は各 PR と main コミットに対してテストを実行し、release.yaml はタグをリポジトリに push するたびに実行されます。詳細については、rules-template リポジトリのコメントをご覧ください。

リポジトリが bazelbuild 組織にある場合は、ci.bazel.build に追加するようリクエストできます。

ドキュメント

ドキュメントを自動生成できるようにルールにコメントを付ける方法については、Stardoc のドキュメントをご覧ください。

rules-template の docs/ フォルダには、Starlark ファイルが更新されるときに docs/ フォルダの Markdown コンテンツが常に最新の状態になるようにする簡単な方法が示されています。

よくある質問

メインの Bazel GitHub リポジトリにルールを追加できないのはなぜですか?

ルールと Bazel リリースを可能な限り分離したいと考えています。個々のルールの所有者が明確になり、Bazel デベロッパーの負荷が軽減されます。分離することで、ルールの変更、アップグレード、ダウングレード、置き換えが容易になります。ルールによっては、Bazel へのコントリビューションよりも、ルールへのコントリビューションの方が軽量になる場合があります。たとえば、対応する GitHub リポジトリへの完全な送信アクセス権などです。Bazel 自体への送信アクセス権を取得するプロセスは、はるかに複雑です。

デメリットは、ユーザーにとって 1 回限りのインストール プロセスが複雑になることです。ユーザーは、MODULE.bazel ファイルにルールセットの依存関係を追加する必要があります。

以前は、すべてのルールが Bazel リポジトリ(//tools/build_rules または //tools/build_defs の下)にありました。現在もいくつかのルールが残っていますが、残りのルールを移行する作業を進めています。