ルールのデプロイ

問題を報告 ソースを表示

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

テンプレート リポジトリ(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
  • リポジトリの説明: Go rules for Bazel
  • リポジトリのタグ: golangbazel
  • README.md ヘッダー: Bazel の Go ルール(Bazel に不慣れなユーザーを適切な場所に誘導する https://bazel.build へのリンクに留意してください)

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

リポジトリのコンテンツ

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

たとえば、(make-believe)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

最上位の README には、ユーザーがルールを使用するために WORKSPACE ファイルにコピー&ペーストする必要がある内容を(少なくとも)含める必要があります。通常は、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_settingconstraint_value の定義が必要になることがあります。これらを //<LANG>/constraints パッケージに入れます。ディレクトリ構造は次のようになります。

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

ベスト プラクティスについては、github.com/bazelbuild/platforms をご覧ください。どのような制約がすでに存在しているのかを確認し、言語に依存しない場合は、制約を提供することを検討してください。カスタム制約を導入する場合は、ルールのすべてのユーザーがそれらを使用して、BUILD ファイルでプラットフォーム固有のロジックを実行します(たとえば、selects を使用)。カスタム制約では、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 属性で参照されるすべてのターゲットを分析する必要はありません。ツールチェーンを登録するため、リポジトリ内で複雑な計算を実行する必要がある場合は、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 の comit ごとにテストを実行し、リポジトリにタグを push するたびに release.yaml を実行します。詳細については、rules-template リポジトリのコメントをご覧ください。

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

ドキュメント

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

rules-template docs/ フォルダを使用すると、Starlark ファイルの更新時に docs/ フォルダ内のマークダウン コンテンツを常に最新の状態にする簡単な方法を確認できます。

よくある質問

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

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

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

以前は、すべてのルールが Bazel リポジトリ(//tools/build_rules または //tools/build_defs)に保存されていました。引き続き 2 つのルールがありますが、残りのルールについては、今後削除する予定です。