Build Foundation の創設メンバーの登録が開始されました。メーリングリストに参加し、参加契約を読み、登録してください。

ルールのデプロイ

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

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

テンプレートリポジトリ（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 ルール （Bazel に慣れていないユーザーを適切な場所に誘導する https://bazel.build へのリンクに注意してください）

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

リポジトリのコンテンツ

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

たとえば、mockascript 言語（架空の言語）の新しいルールを作成する場合、ルールリポジトリは次の構造になります。

/
  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 ライブラリ

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

リポジトリルール

依存関係

ルールには外部依存関係がある場合があります。ルールへの依存を簡単にするため、外部依存関係の依存関係を宣言する WORKSPACE マクロを提供してください。テストの依存関係は宣言しないでください。ルールが機能するために必要な依存関係のみを宣言してください。開発の依存関係は WORKSPACE ファイルに配置します。

<LANG>/repositories.bzl という名前のファイルを作成し、単一のエントリポイントマクロ rules_<LANG>_dependencies を提供します。ディレクトリは次のようになります。

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

ツールチェーンの登録

ルールでツールチェーンを登録することもできます。これらのツールチェーンを登録する別の WORKSPACE マクロを提供してください。これにより、ユーザーは前のマクロを省略して依存関係を手動で制御しながら、ツールチェーンを登録できます。

したがって、<LANG>/repositories.bzl ファイルに WORKSPACE という名前の rules_<LANG>_toolchains マクロを追加します。

分析フェーズでツールチェーンを解決するには、Bazel は登録されているすべての toolchain ターゲットを分析する必要があります。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 が使用されています。ルールテンプレートリポジトリで使用されている構成をご覧ください。これは、bazel-contrib 組織でホストされている「再利用可能なワークフロー」を使用して簡略化されています。ci.yaml は各 PR と main コミットでテストを実行し、release.yaml はリポジトリにタグを push するたびに実行されます。詳細については、ルールテンプレートリポジトリのコメントをご覧ください。

リポジトリが bazelbuild 組織に属している場合は、 ci.bazel.build への追加をリクエストできます。

ドキュメント

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

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

よくある質問

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

ルールを Bazel リリースからできるだけ切り離したいと考えています。個々のルールの所有者が明確になり、Bazel デベロッパーの負担が軽減されます。ユーザーにとっては、切り離すことでルールの変更、アップグレード、ダウングレード、置き換えが容易になります。ルールへの投稿は、対応する GitHub リポジトリへの完全な送信アクセス権など、ルールによっては Bazel への投稿よりも軽量にできます。Bazel 自体への送信アクセス権を取得するには、はるかに複雑なプロセスが必要です。

欠点は、ユーザー向けの 1 回限りのインストールプロセスが複雑になることです。上記の README.md セクションに示すように、ルールを WORKSPACE ファイルにコピーして貼り付ける必要があります。

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

ルールのデプロイ コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。