マクロを使ってカスタム動詞を作成する

問題を報告ソースを表示 Nightly · 7.4 . 7.3 7.2 7.1 7.0 6.5

Bazel の日常的な操作は、主に build、test、run の 3 つのコマンドで行います。しかし、時には限界を感じることもあります。パッケージをリポジトリに push する、エンドユーザー向けのドキュメントを公開する、 Kubernetes でアプリケーションをデプロイします。しかし、Bazel には publish や deploy コマンド – これらのアクションの位置付け

bazel run コマンド

Bazel は密閉性、再現性、インクリメンタリティを重視しているため、 build コマンドと test コマンドは、上記のタスクには役立ちません。これらのアクションネットワークアクセスが制限されたサンドボックスで実行されることがあり、セキュリティリスクが bazel build ごとに再実行します。

代わりに、実行するタスクの主力である bazel run に頼ってください。防ぐことができます。Bazel ユーザーは実行可能ファイルを作成するルールに慣れています。ルール作成者は、一般的なパターンに沿ってこれを「カスタム動詞」に拡張できます。

実環境: rules_k8s

たとえば rules_k8s について考えてみましょう。 Bazel に関する Kubernetes のルールです。次のターゲットがあるとします。

# BUILD file in //application/k8s
k8s_object(
    name = "staging",
    kind = "deployment",
    cluster = "testing",
    template = "deployment.yaml",
)

k8s_object ルールは、staging ターゲットで bazel build が使用されている場合に、標準の Kubernetes YAML ファイルをビルドします。ただし、追加のターゲットも k8s_object によって作成されます。マクロを staging.apply や :staging.delete などの名前で使用することはできません。これらのビルドは、これらのアクションを実行するスクリプトが用意されており、bazel run staging.apply で実行すると、これらは独自の bazel k8s-apply コマンドや bazel k8s-delete コマンドのように動作します。

別の例: ts_api_guardian_test

このパターンは Angular プロジェクトでも見ることができます。「 ts_api_guardian_test マクロ 2 つのターゲットが生成されます。1 つ目は標準の nodejs_test ターゲットで、「ゴールデン」パターンに対して生成された出力をファイル（つまり、このファイルに出力）。これは、通常の bazel test 呼び出しでビルドして実行できます。angular-cli では、このようなターゲット bazel test //etc/api:angular_devkit_core_api で。

時間が経つと、正当な理由でこのゴールデンファイルの更新が必要になることがあります。手動で更新するのは手間がかかり、エラーが発生しやすいため、比較の代わりにゴールデンファイルを更新する nodejs_binary ターゲット防ぐことができます。実際には、同じテストスクリプトを、呼び出し方法に応じて「検証」モードまたは「承認」モードで実行するように記述できます。これは、すでに学習したパターンと同じです。ネイティブの bazel test-accept コマンドはありませんが、bazel run //etc/api:angular_devkit_core_api.accept で同じ効果を得ることができます。

このパターンは非常に強力で、認識できるようになれば非常に一般的であることがわかります。

独自のルールを調整する

このパターンの中核となるのがマクロです。マクロは複数のターゲットを作成できます。通常は指定された名前で、メインのビルドアクションを実行するターゲット（たとえば、通常のバイナリ、Docker イメージ、またはソースコードのアーカイブをビルドします。このパターンでは、追加のターゲットが作成され、結果のバイナリの公開や想定されるテスト出力の更新など、プライマリターゲットの出力に基づいて副作用を実行するスクリプトが生成されます。

これを説明するために、Sphinx を使用してウェブサイトを生成する架空のルールをマクロでラップし、ユーザーが準備ができたときに公開できるように追加のターゲットを作成します。次の点を考慮してください。 Sphinx でウェブサイトを生成する既存のルール:

_sphinx_site = rule(
     implementation = _sphinx_impl,
     attrs = {"srcs": attr.label_list(allow_files = [".rst"])},
)

次に、次のようなルールを検討します。このスクリプトは、実行時に生成されたページを公開します。

_sphinx_publisher = rule(
    implementation = _publish_impl,
    attrs = {
        "site": attr.label(),
        "_publisher": attr.label(
            default = "//internal/sphinx:publisher",
            executable = True,
        ),
    },
    executable = True,
)

最後に、次のマクロを定義して、上記の両方のルールのターゲットを一緒に作成します。

def sphinx_site(name, srcs = [], **kwargs):
    # This creates the primary target, producing the Sphinx-generated HTML.
    _sphinx_site(name = name, srcs = srcs, **kwargs)
    # This creates the secondary target, which produces a script for publishing
    # the site generated above.
    _sphinx_publisher(name = "%s.publish" % name, site = name, **kwargs)

BUILD ファイルで、プライマリターゲットを作成する場合と同じようにマクロを使用します。

sphinx_site(
    name = "docs",
    srcs = ["index.md", "providers.md"],
)

この例では、マクロが標準の単一の Bazel ルールであるかのように、「docs」ターゲットが作成されます。ビルド時に、ルールはいくつかの構成を生成し、Sphinx を実行して HTML サイトを生成します。このサイトは手動検査の準備が整っています。ただし、サイトの公開用スクリプトをビルドする追加の「docs.publish」ターゲットも作成されます。プライマリターゲットの出力を確認したら、架空の bazel publish コマンドと同様に、bazel run :docs.publish を使用して一般公開できます。

_sphinx_publisher の実装が何であるかは、すぐにはわかりません。見てみましょう。多くの場合、このようなアクションではランチャーシェルスクリプトを作成します。この方法では通常、ctx.actions.expand_template を使用して非常にシンプルなシェルスクリプトを作成します。この場合、プライマリターゲットの出力パスを指定してパブリッシャーバイナリを呼び出します。これにより、パブリッシャーの実装は汎用性を維持し、_sphinx_site ルールは HTML のみを生成できます。この小さなスクリプトだけで、2 つを組み合わせることができます。

rules_k8s では、実際に .apply はこのように動作します。 expand_template 基礎となる非常にシンプルな Bash スクリプトを apply.sh.tpl, プライマリターゲットの出力を使用して kubectl を実行します。このスクリプトを bazel run :staging.apply でビルドして実行すると、k8s_object ターゲットに k8s-apply コマンドが効果的に提供されます。