一般ルール

ルール

• 代替名
• config_setting
• ファイル グループ
• genquery
• genrule
• starlark_doc_extract
• test_suite

エイリアス

alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

alias ルールは、ルールを参照できる別の名前を作成します。

エイリアスは「通常」のターゲットにのみ適用されます。特に、package_group と test_suite にはエイリアスを設定できません。

エイリアスは、ターゲットの名前変更に多くのファイルの変更が必要となる大規模なリポジトリで役立ちます。複数のターゲットでそのロジックを再利用する場合は、エイリアス ルールを使用して select 関数呼び出しを保存することもできます。

エイリアス ルールには独自の公開設定があります。その他の点では、参照先のルールと同じように動作します（例: エイリアスの testonly は無視され、代わりに参照先のルールの testonly が使用されます）。ただし、いくつかの例外があります。

• コマンドラインにエイリアスが指定されている場合、テストは実行されません。参照されたテストを実行するエイリアスを定義するには、tests 属性に単一のターゲットを含む test_suite ルールを使用します。
• 環境グループを定義する場合、environment ルールのエイリアスはサポートされていません。--target_environment コマンドライン オプションでもサポートされていません。

例

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

引数

config_setting

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

構成可能な属性をトリガーするために、想定される構成状態（ビルドフラグまたはプラットフォームの制約として表現）と一致します。このルールの使用方法についてはselect をご覧ください。一般的な機能の概要については、 構成可能な属性をご覧ください。

例

次のパターンは、--compilation_mode=opt または -c opt を設定するビルド（コマンドラインで明示的に設定するか、.bazelrc ファイルから暗黙的に設定）に一致します。

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

以下は、ARM をターゲットとするすべてのビルドに一致し、カスタム定義 FOO=bar（bazel build --cpu=arm --define FOO=bar ... など）を適用します。

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

次のパターンは、ユーザー定義フラグ --//custom_flags:foo=1 を設定するビルド（コマンドラインで明示的に設定するか、.bazelrc ファイルから暗黙的に設定）に一致します。

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

次のパターンは、x86_64 アーキテクチャと glibc バージョン 2.25 のプラットフォームをターゲットとするビルドに一致します。これは、ラベル //example:glibc_2_25 の constraint_value が存在することを前提としています。プラットフォームがこれらの 2 つを超える制約値を定義している場合でも、プラットフォームは一致します。

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  

メモ

• 複数の config_setting が現在の構成状態と一致した場合の動作については、select をご覧ください。
• 省略形をサポートするフラグ（--compilation_mode と -c など）の場合、values の定義では完全な形式を使用する必要があります。これらは、どちらかの形式を使用して呼び出しを自動的に照合します。
• フラグが複数の値（--copt=-Da --copt=-Db やリスト型の Starlark フラグなど）を取る場合、values = { "flag": "a" } は、実際のリスト内の任意の場所に "a" が存在する場合に一致します。

  values = { "myflag": "a,b" } も同様に動作します。これは --myflag=a --myflag=b、--myflag=a --myflag=b --myflag=c、--myflag=a,b、--myflag=c,b,a と一致します。正確なセマンティクスは、フラグによって異なります。たとえば、--copt は同じインスタンス内の複数の値をサポートしていません。--copt=a,b は ["a,b"] を生成しますが、--copt=a --copt=b は ["a", "b"] を生成します（したがって、values = { "copt": "a,b" } は前者に一致しますが、後者には一致しません）。ただし、--ios_multi_cpus（Apple ルール用）は同じ結果になります。-ios_multi_cpus=a,b と ios_multi_cpus=a --ios_multi_cpus=b の両方で ["a", "b"] が生成されます。フラグの定義を確認し、条件を慎重にテストして、期待どおりの結果が得られていることを確認します。

• 組み込みのビルドフラグでモデル化されていない条件を定義する必要がある場合は、 Starlark で定義されたフラグを使用します。--define を使用することもできますが、サポートが弱いためおすすめしません。詳細については、こちらをご覧ください。
• 異なるパッケージで同じ config_setting 定義を繰り返さないでください。 代わりに、標準パッケージで定義されている共通の config_setting を参照します。
• values、define_values、constraint_values は、同じ config_setting で任意の組み合わせで使用できますが、特定の config_setting に対して少なくとも 1 つは設定する必要があります。

引数

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

filegroup

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

filegroup を使用して、単一のラベルの下にターゲット セットの出力を収集します。

filegroup は、コマンドラインまたは別のルールの属性でターゲットを一覧表示する代わりに使用できません。これは、ターゲットには出力以外の多くのプロパティがあり、それらは同じ方法で収集されないためです。ただし、genrule の srcs 属性や *_binary ルールの data 属性など、かなり多くのケースでは有用です。

ディレクトリを直接参照するのではなく、filegroup を使用することをおすすめします。ディレクトリを直接参照することは推奨されません。ビルドシステムはディレクトリ内のすべてのファイルを完全に把握していないため、これらのファイルが変更されたときに再ビルドされない可能性があります。filegroup を glob と組み合わせると、すべてのファイルがビルドシステムに明示的に認識されるようになります。

例

2 つのソースファイルで構成される filegroup を作成する手順は次のとおりです。

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "//a/library:target",
        "//a/binary:target",
    ],
)

または、glob を使用して testdata ディレクトリを完全にクロールします。

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

これらの定義を使用するには、任意のルールのラベルを使用して filegroup を参照します。

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

引数

genquery

genquery(name, deps, data, compatible_with, compressed_output, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery() は、Bazel クエリ言語で指定されたクエリを実行し、結果をファイルにダンプします。

ビルドの整合性を保つため、クエリでアクセスが許可されるのは、scope 属性で指定されたターゲットの推移的クロージャに限られます。strict が未指定または true の場合、このルールに違反するクエリは実行中に失敗します（strict が false の場合、スコープ外のターゲットは単にスキップされ、警告が表示されます）。これを回避する最も簡単な方法は、クエリ式と同じラベルをスコープに指定することです。

ここで許可されるクエリとコマンドラインで許可されるクエリの唯一の違いは、ワイルドカード ターゲット仕様（//pkg:* や //pkg:all など）を含むクエリがここでは許可されないことです。これには 2 つの理由があります。1 つ目は、genquery がクエリの推移的クロージング外のターゲットが出力に影響しないようにスコープを指定する必要があるためです。2 つ目は、BUILD ファイルがワイルドカード依存関係をサポートしていない（例: deps=["//a/..."] は許可されない）ことです。

genquery の出力は、--output=graph|minrank|maxrank を除き、または somepath がトップレベル関数として使用されている場合を除き、確定的な出力を適用するために辞書順に並べ替えられます。

出力ファイルの名前はルールの名前です。

例

この例では、指定したターゲットの推移閉包内のラベルのリストをファイルに書き込みます。

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

引数

genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule は、ユーザー定義の Bash コマンドを使用して 1 つ以上のファイルを生成します。

Genrules は、タスクに特定のルールがない場合に使用できる汎用のビルドルールです。たとえば、Bash のワンライナーを実行できます。ただし、C++ ファイルをコンパイルする必要がある場合は、煩雑な作業がすべてすでに完了しているため、既存の cc_* ルールに従います。

なお、genrule にはコマンド引数を解釈するためのシェルが必要です。PATH で使用可能な任意のプログラムを参照することも簡単ですが、この場合、コマンドは非ヘルメティックになり、再現できない可能性があります。1 つのツールを実行するだけの場合は、代わりに run_binary を使用することを検討してください。

他のすべてのアクションと同様に、genrules によって作成されたアクションは、作業ディレクトリについて何も想定しない必要があります。Bazel が保証するのは、宣言された入力が、$(location) がラベルに対して返すパスで使用できることのみです。たとえば、アクションがサンドボックスまたはリモートで実行される場合、作業ディレクトリはサンドボックスまたはリモート実行の実装によって決まります。standalone 戦略を使用して直接実行すると、作業ディレクトリは実行ルート（bazel info execution_root の結果）になります。

テストの実行に genrule を使用しないでください。テストとテスト結果には、キャッシュ ポリシーや環境変数など、特別な例外があります。通常、テストはビルドの完了後にターゲット アーキテクチャで実行する必要がありますが、genrule はビルド中に実行され、実行アーキテクチャで実行されます（2 つは異なる場合があります）。汎用のテストルールが必要な場合は、sh_test を使用します。

クロスコンパイルに関する考慮事項

クロスコンパイルの詳細については、ユーザー マニュアルをご覧ください。

genrule はビルド中に実行されますが、その出力はビルド後にデプロイやテストに使用されることがよくあります。マイクロコントローラの C コードをコンパイルする場合を考えてみます。コンパイラは C ソースファイルを受け入れ、マイクロコントローラで実行されるコードを生成します。生成されたコードはビルドに使用された CPU では実行できませんが、C コンパイラ（ソースからコンパイルされた場合）自体は実行する必要があります。

ビルドシステムは、exec 構成を使用してビルドを実行するマシンを記述し、ターゲット構成を使用してビルドの出力を実行するマシンを記述します。これらのそれぞれを構成するオプションが用意されており、競合を回避するために対応するファイルが個別のディレクトリに分離されます。

genrules の場合、ビルドシステムは依存関係が適切にビルドされるようにします。srcs は（必要に応じて）target 構成用にビルドされ、tools は exec 構成用にビルドされ、出力は target 構成用と見なされます。また、genrule コマンドが対応するツールに渡すことができる 「Make」変数も提供します。

genrule で deps 属性を定義しないという意図があります。他の組み込みルールは、ルール間で渡された言語依存のメタ情報を使用して、依存ルールの処理方法を自動的に決定しますが、genrule ではこのレベルの自動化は不可能です。genrule はファイル レベルとランファイル レベルでのみ機能します。

特別なケース

Exec-exec コンパイル: ビルドシステムで、出力をビルド中に実行できるように genrules を実行する必要がある場合があります。たとえば、genrule がカスタム コンパイラをビルドし、それが別の genrule で使用される場合、最初の genrule は exec 構成の出力を生成する必要があります。これは、コンパイラが他の genrule で実行される場所だからです。この場合、ビルドシステムは適切な処理を自動的に行います。つまり、ターゲット構成ではなく、exec 構成に対して最初の genrule の srcs と outs をビルドします。詳しくは、ユーザー マニュアルをご覧ください。

JDK と C++ のツール: JDK または C++ コンパイラ スイートのツールを使用するために、ビルドシステムには、使用可能な一連の変数が用意されています。詳細については、「Make」変数をご覧ください。

Genrule 環境

genrule コマンドは、set -e -o pipefail を使用してコマンドまたはパイプラインが失敗した場合に失敗するように構成された Bash シェルで実行されます。

ビルドツールは、PATH、PWD、TMPDIR などのコア変数のみを定義するサニタイズされたプロセス環境で Bash コマンドを実行します。ビルドが再現可能であることを確認するため、ユーザーのシェル環境で定義されたほとんどの変数は、genrule のコマンドに渡されません。ただし、Bazel は（Blaze ではなく）ユーザーの PATH 環境変数の値を渡します。 PATH の値を変更すると、Bazel は次のビルドでコマンドを再実行します。

genrule コマンドでは、コマンド自体の子プロセスを接続する場合を除き、ネットワークにアクセスできません。ただし、これは現在は適用されていません。

ビルドシステムは既存の出力ファイルを自動的に削除しますが、genrule を実行する前に必要な親ディレクトリを作成します。また、失敗した場合の出力ファイルも削除されます。

一般的なアドバイス

• genrule によって実行されるツールが確定的かつ完全密閉であることを確認してください。出力にはタイムスタンプを書き込まないでください。また、セットとマップには安定した順序を使用します。また、絶対パスではなく、出力への相対ファイルパスのみを書き出す必要があります。このルールに従わないと、予期しないビルド動作（Bazel が予想した genrule を再構築しない）が発生し、キャッシュのパフォーマンスが低下します。
• 出力、ツール、ソースに $(location) を幅広く使用します。異なる構成の出力ファイルが分離されているため、genrules はハードコードされたパスや絶対パスに依存できません。
• 同じまたは非常に類似した genrule が複数の場所で使用される場合は、共通の Starlark マクロを記述します。genrule が複雑な場合は、スクリプトまたは Starlark ルールとして実装することを検討してください。これにより、読みやすさとテストのしやすさが向上します。
• 終了コードが genrule の成功または失敗を正しく示していることを確認してください。
• stdout または stderr に情報メッセージを書き込まないでください。これはデバッグに役立ちますが、ノイズになりやすいため、成功した genrule はサイレントである必要があります。一方、genrule が失敗すると、適切なエラー メッセージが出力されます。
• $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x)。
• シンボリック リンクとディレクトリを作成しないようにします。Bazel は、genrules によって作成されたディレクトリ/シンボリック リンク構造をコピーせず、ディレクトリの依存関係チェックは正常に機能しません。
• 他のルールで genrule を参照する場合は、genrule のラベルまたは個々の出力ファイルのラベルを使用できます。どちらのアプローチが読みやすいかは状況によって異なります。コンシューマ ルールの srcs で出力を名前で参照すると、genrule の他の出力を意図せず取得するのを回避できますが、genrule が出力を多数生成する場合は面倒な作業になる可能性があります。

例

この例では、foo.h が生成されます。このコマンドは入力を取らないため、ソースはありません。このコマンドで実行される「バイナリ」は、genrule と同じパッケージ内の Perl スクリプトです。

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

次の例は、filegroup の使用方法と、別の genrule の出力を示しています。明示的な $(location) ディレクティブの代わりに $(SRCS) を使用することもできます。この例では、デモのために後者を使用しています。

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

引数

starlark_doc_extract

starlark_doc_extract(name, deps, src, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, render_main_repo_name, restricted_to, symbol_names, tags, target_compatible_with, testonly, visibility)

starlark_doc_extract() は、特定の .bzl ファイルまたは .scl ファイルで定義または再エクスポートされたルール、関数（マクロを含む）、アスペクト、プロバイダのドキュメントを抽出します。このルールの出力は、Bazel ソースツリーの stardoc_output.proto で定義されている ModuleInfo バイナリ proto です。

暗黙的な出力ターゲット

• name.binaryproto（デフォルト出力）: ModuleInfo バイナリ proto。
• name.textproto（明示的にリクエストされた場合にのみビルドされます）: name.binaryproto のテキスト proto バージョン。

警告: このルールの出力形式は、必ずしも安定しているとは限りません。これは、主に Stardoc による内部使用を想定しています。

引数

test_suite

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite は、人間にとって「有用」と見なされる一連のテストを定義します。これにより、プロジェクトで「チェックイン前に実行する必要があるテスト」、「プロジェクトのストレステスト」、「すべて小規模なテスト」などの一連のテストを定義できます。bazel test コマンドは、このような組織を尊重します。bazel test //some/test:suite などの呼び出しの場合、Bazel はまず //some/test:suite ターゲットに帰属するすべてのテスト ターゲットを列挙します（これを「test_suite 拡張」と呼びます）。次に、それらのターゲットをビルドしてテストします。

例

現在のパッケージ内のすべての小規模なテストを実行するテストスイート。

test_suite(
    name = "small_tests",
    tags = ["small"],
)

指定された一連のテストを行うテストスイート:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

現在のパッケージ内の不安定でないすべてのテストを実行するテストスイート。

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

引数