このページは、ルールを他のユーザーに公開する予定のルール作成者を対象としています。
新しいルールセットは、テンプレート リポジトリ(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 ルール
- リポジトリのタグ:
golang
、bazel
README.md
ヘッダー: Bazel の Go ルール(https://bazel.build へのリンクに注意し、Bazel に馴染みのないユーザーを適切な場所を参照してください)
ルールは、言語(Scala など)、ランタイム プラットフォーム(Android など)、フレームワーク(Spring など)でグループ化できます。
リポジトリのコンテンツ
すべてのルール リポジトリには、ユーザーが新しいルールをすばやく理解できるように、特定のレイアウトが必要です。
たとえば、mockascript
言語(make-believe)用に新しいルールを作成する場合、ルール リポジトリの構造は次のようになります。
/
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
プロジェクトの WORKSPACE
で、ユーザーがルールの参照に使用する名前を定義する必要があります。ルールが bazelbuild 組織に属している場合は、rules_<lang>
(rules_mockascript
など)を使用する必要があります。それ以外の場合は、リポジトリに <org>_rules_<lang>
(build_stack_rules_proto
など)という名前を付ける必要があります。ルールを bazelbuild 組織のルールの規則に従う必要がある場合は、GitHub でスレッドを開始してください。
以降のセクションでは、リポジトリが bazelbuild 組織に属していると仮定します。
workspace(name = "rules_mockascript")
README
最上位には、ユーザーがルールを使用する際に WORKSPACE
ファイルにコピーして貼り付ける必要があるものが(少なくとも)含まれている README
が必要です。通常は、GitHub リリースを指す http_archive
と、ルールに必要なツールをダウンロード/構成するマクロ呼び出しです。たとえば、Go ルールの場合は次のようになります。
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()
ルールが別のリポジトリのルールに依存している場合は、ルールのドキュメントでそのルールを指定し(たとえば、Sass ルールに依存する Skydoc ルールを参照)、すべての依存関係をダウンロードする WORKSPACE
マクロを指定します(上記の rules_go
を参照)。
ルール
多くの場合、リポジトリから複数のルールが提供されます。言語で名前を付けたディレクトリを作成し、エントリ ポイント(すべてのルールをエクスポートする defs.bzl
ファイル)を指定します(ディレクトリがパッケージになるように BUILD
ファイルも含めます)。rules_mockascript
の場合、mockascript
という名前のディレクトリと、その中に BUILD
ファイルと defs.bzl
ファイルが存在します。
/
mockascript/
BUILD
defs.bzl
制約
ルールでツールチェーン ルールを定義している場合は、カスタムの constraint_setting
や constraint_value
の定義が必要になることがあります。これらを //<LANG>/constraints
パッケージに格納します。ディレクトリ構造は次のようになります。
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
ベスト プラクティスと既存の制約については、github.com/bazelbuild/platforms をご覧ください。言語に依存しない場合は、そちらに投稿することをおすすめします。カスタム制約を導入する際は、ルールのすべてのユーザーが、BUILD
ファイルでプラットフォーム固有のロジックを実行するために(選択を使用するなど)使用することを考慮してください。カスタム制約を使用すると、Bazel エコシステム全体が使用する言語を定義できます。
Runfiles ライブラリ
ルールで runfile にアクセスするための標準ライブラリを提供する場合は、//<LANG>/runfiles
(//<LANG>/runfiles:runfiles
の省略形)にあるライブラリ ターゲットの形式にする必要があります。データ依存関係にアクセスする必要があるユーザー ターゲットは、通常、このターゲットを deps
属性に追加します。
リポジトリ ルール
依存関係
ルールに外部依存関係がある可能性があります。ルールへの依存関係を簡素化するには、これらの外部依存関係の依存関係を宣言する WORKSPACE
マクロを指定してください。そこで、テストの依存関係は宣言せず、ルールの動作に必要な依存関係のみを宣言します。開発用の依存関係を WORKSPACE
ファイルに配置します。
<LANG>/repositories.bzl
という名前のファイルを作成し、rules_<LANG>_dependencies
という名前の単一のエントリ ポイント マクロを指定します。ディレクトリは次のようになります。
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
ツールチェーンの登録
ルールでツールチェーンを登録することもできます。これらのツールチェーンを登録する個別の WORKSPACE
マクロを用意してください。これにより、ユーザーは以前のマクロを省略し、依存関係を手動で制御しながら、ツールチェーンを登録できます。
そのため、rules_<LANG>_toolchains
という名前の WORKSPACE
マクロを <LANG>/repositories.bzl
ファイルに追加します。
分析フェーズでツールチェーンを解決するには、Bazel は登録されているすべての toolchain
ターゲットを分析する必要があります。Bazel は、toolchain.toolchain
属性で参照されるすべてのターゲットを分析する必要はありません。ツールチェーンを登録するためにリポジトリで複雑な計算を行う必要がある場合は、toolchain
ターゲットを含むリポジトリと <LANG>_toolchain
ターゲットを含むリポジトリを分割することを検討してください。前者は常にフェッチされ、後者はユーザーが実際に <LANG>
コードをビルドする必要がある場合にのみフェッチされます。
リリース スニペット
リリースのお知らせで、ユーザーが WORKSPACE
ファイルにコピーして貼り付けることができるスニペットを提供します。このスニペットは通常、次のようになります。
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()
テスト
ルールが想定どおりに機能していることを確認するテストが必要です。この場所は、ルールの対象言語の標準的な場所か、最上位の tests/
ディレクトリに配置できます。
例(省略可)
ルールの基本的な使用方法を示す examples/
ディレクトリがあると、ユーザーにとって便利です。
CI / CD
多くのルールセットで GitHub Actions が使用されています。rules-template リポジトリで使用されている構成をご覧ください。これは、bazel-contrib 組織でホストされている「再利用可能なワークフロー」を使用して簡略化されています。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 回限りのインストール プロセスが複雑になることです。上記の README.md
セクションで説明したように、ルールをコピーして WORKSPACE
ファイルに貼り付ける必要があります。
以前は、すべてのルールが Bazel リポジトリ(//tools/build_rules
または //tools/build_defs
)に保存されていました。まだいくつかのルールがありますが、現在、残りのルールは除外しています。