ルールのデプロイ

<ph type="x-smartling-placeholder"></ph> 問題を報告する ソースを表示 夜間 · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

このページは、ルールを利用できるようにすることを予定しているルール作成者向けです できます。

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

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

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

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

GitHub リポジトリの説明はわかりやすいものにし、README.md 例:

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

ルールは、言語(Scala など)、ランタイム プラットフォーム、 フレームワーク(Spring など)の 3 つのコンポーネントがあります。

リポジトリのコンテンツ

ユーザーがルールをすぐに実行できるように、すべてのルール リポジトリに特定のレイアウトを用意する 理解しやすくなっています。

たとえば、(仮説の)ルールに関する新しいルールを 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 など)。恐れ入りますが、 GitHub でスレッドを開始する ルールの規約に従う必要がある場合は、 bazelbuild 組織。

以降のセクションでは、リポジトリが 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()

ルールが別のリポジトリのルールに依存している場合は、 (たとえば、このモジュールの Skydoc ルール Sass ルールに依存する)に 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 マクロを用意してください。 外部依存関係が含まれます。そこでテストの依存関係を宣言せず、 必要があります。開発環境の依存関係を Terraform Registry に 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 は、24 時間以内に 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 でホストされた orgci.yaml は PR と main の commit ごとにテストを実行します。release.yaml は、リポジトリにタグを push するたびに実行されます。 詳細については、rules-template リポジトリ内のコメントをご覧ください。

リポジトリが bazelbuild 組織の下にある場合は、 追加するよう依頼して ci.bazel.build に追加します。

ドキュメント

詳しくは、Stardoc のドキュメント ドキュメントを生成できるようにルールにコメントを付ける方法 自動的に適用されます。

rules-template docs/ フォルダ docs/ フォルダ内の Markdown コンテンツを常に最新状態に維持する簡単な方法を示す図 Starlark ファイルの更新時に行われます。

よくある質問

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

Google では、できる限り Bazel リリースからルールを分離したいと考えています。明確である Bazel 開発者の負荷を軽減します。ユーザーにとって 分離することで、ルールの変更、アップグレード、ダウングレード、置き換えが容易になります。 ルールへの貢献は、Bazel への貢献よりも軽量です。 (対応するオブジェクトへの完全な送信アクセス権を含む) GitHub リポジトリ。Bazel 自体への送信アクセス権を取得する作業は、 プロセスです

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

以前は、すべてのルールが Bazel リポジトリ( //tools/build_rules//tools/build_defs など)。まだいくつかのルールがあります 残りのルールは削除する予定です。