一般規則

ルール

• エイリアス
• config_setting
• ファイルグループ
• genquery
• genrule
• test_suite

エイリアス

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

alias ルールにより、ルールの参照対象となる別の名前が作成されます。

エイリアスは「標準」のターゲットに対してのみ機能します。特に、package_group と test_suite をエイリアスにすることはできません。

エイリアス ルールには独自の可視性宣言があります。他のすべての点で、参照するルールと同じように動作します（例: エイリアス上の 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" },
  )
  

以下は、//example:glibc_2_25 ラベル constraint_value が存在すると仮定して、x86_64 アーキテクチャと glibc バージョン 2.25 を持つプラットフォームをターゲットとするビルドと一致します。2 つのプラットフォーム以外の 2 つの制約値は、プラットフォームで定義されていれば一致します。

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

メモ

• 複数のconfig_settingが現在の構成状態と一致した場合の処理については、をご覧ください。
• 省略形をサポートするフラグ（--compilation_mode と -c など）の場合、values 定義は完全な形式を使用する必要があります。これらは、どちらのフォームを使用した呼び出しも自動的に一致します。
• フラグが複数の値（--copt=-Da --copt=-Db やリスト型の スターラーク フラグなど）を受け取る場合、"a" が実際のリストのどこかに存在する場合、values = { "flag": "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(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

filegroup を使用して、ターゲットのコレクションにわかりやすい名前を付けます。これらは他のルールから参照できます。

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

例

2 つのソースファイルで構成される filegroup を作成するには、次のようにします。

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

または、glob を使用してテストデータ ディレクトリを表示します。

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, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

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

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

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

確定的出力を適用するため、genquery の出力は --order_output=full で順序付けされます。

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

例

この例では、指定されたターゲットの推移的クロージャにあるラベルのリストをファイルに書き込みます。

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, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

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

Genrule は、タスクに特定のルールがない場合に使用できる汎用のビルドルールです。たとえば、Bash の 1 行で実行できます。ただし、C++ ファイルをコンパイルする必要がある場合は、既存の cc_* ルールに従ってください。手間のかかる作業はすべて完了しています。

genrule には、コマンド引数を解釈するシェルが必要です。PATH で利用可能な任意のプログラムを参照するのも簡単ですが、このコマンドは非密閉型であり、再現できない場合があります。単一のツールのみを実行する場合は、代わりに run_binary を使用することを検討してください。

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

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

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

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

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

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

genrule では deps 属性が定義されません。他の組み込みルールでは、ルール間で渡される言語依存のメタ情報を使用して、依存ルールの処理方法を自動的に決定しますが、このレベルの自動化を genrule で行うことはできません。Genrules は、ファイルレベルとランファイル レベルでのみ機能します。

特殊なケース

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

JDK & C++ Tooling: JDK または C++ コンパイラ スイートのツールを使用するには、ビルドシステムが一連の変数を使用します。詳しくは、Make 変数をご覧ください。

Genrule 環境

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

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

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

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

一般的なアドバイス

• genrule により実行されるツールは、決定論的で密閉されていることを確認します。タイムスタンプを出力に書き込むのではなく、セットとマップに安定した順序付けを用い、絶対パスではなく、出力への相対ファイルパスのみを書き込みます。このルールに従わないと、予期しないビルド動作（Bazel が想定している genrule を再構築しない）が発生し、キャッシュのパフォーマンスが低下します。
• 出力、ツール、ソースには、$(location) を幅広く使用します。さまざまな構成の出力ファイルが分離されているため、genrule はハードコードされたパスや絶対パスに依存できません。
• 同じ / 非常に類似した 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 のラベルまたは個々の出力ファイルのラベルを使用できます。1 つのアプローチのほうが読みやすくなることもあります。別のアプローチでは、消費ルールの 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) > $@",
)

引数

test_suite

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

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

例

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

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"],
)

引数