このページは Cloud Translation API によって翻訳されました。

ルールのデプロイ

このページは、他のユーザーがルールを利用できるようにしようとしているルール作成者を対象としています。

テンプレートリポジトリ（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 ファイルでプラットフォーム固有のロジックを実行します（たとえば、select を使用します）。カスタム制約を使用して、Bazel エコシステム全体が話す言語を定義します。

Runfiles ライブラリ

ランファイルにアクセスするための標準ライブラリがルールで提供されている場合は、//<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 属性で参照されるすべてのターゲットを分析する必要はありません。ツールチェーンを登録するために、リポジトリで複雑な計算を実行する必要がある場合は、<LANG>_toolchain ターゲットを使用して、リポジトリの 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 の commit ごとにテストを実行します。release.yaml は、リポジトリにタグを push するたびに実行されます。詳細については、rules-template リポジトリ内のコメントをご覧ください。

リポジトリが bazelbuild 組織の下にある場合は、ci.bazel.build への追加を依頼できます。

ドキュメント

ルールにコメントしてドキュメントを自動的に生成する方法については、Stardoc のドキュメントをご覧ください。

rules-template docs/ フォルダは、Starlark ファイルの更新時に docs/ フォルダ内の Markdown コンテンツが常に最新であることを確認するための簡単な方法を示しています。

よくある質問

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

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

この方法の短所は、1 回限りのインストールプロセスが複雑になることです。上記の README.md セクションで説明したように、ルールを WORKSPACE ファイルにコピー&ペーストする必要があります。

以前は、すべてのルールが Bazel リポジトリ（//tools/build_rules または //tools/build_defs）に保存されていました。まだいくつかのルールがありますが、現在、残りのルールは除外しています。