ルール
エイリアス
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias ルールは、ルールの別名を作成します。
エイリアス設定は、「通常の」ターゲットに対してのみ機能します。特に、package_group と test_suite はエイリアス設定できません。
エイリアス ルールには、独自の公開設定の宣言があります。その他の点では、参照するルールと同じように動作します（例: エイリアスの testonly は無視されます。参照されるルールの testonly-ness が使用されます）。
-
コマンドラインでエイリアスが指定されている場合、テストは実行されません。参照されるテストを実行するエイリアスを定義するには、
tests属性に単一のターゲットを指定したtest_suiteルールを使用します。 -
環境グループを定義するときに、
environmentルールのエイリアスはサポートされません。--target_environmentコマンドライン オプションでもサポートされていません。
例
filegroup(
name = "data",
srcs = ["data.txt"],
)
alias(
name = "other",
actual = ":data",
)
引数
| 属性 | |
|---|---|
name |
このターゲットの一意の名前。 |
actual
|
|
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 つ以外の追加の制約値を定義すると、プラットフォームは一致することに注意してください。
config_setting(
name = "64bit_glibc_2_25",
constraint_values = [
"@platforms//cpu:x86_64",
"//example:glibc_2_25",
]
)
上記のいずれの場合も、ビルド内で構成が変更される可能性があります。たとえば、ターゲットをその依存関係とは異なるプラットフォーム用にビルドする必要がある場合などです。つまり、config_setting がトップレベルのコマンドライン フラグと一致しない場合でも、一部のビルド ターゲットには一致する場合があります。
メモ
- 複数の
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 つを設定する必要があります。
引数
| 属性 | |
|---|---|
name |
このターゲットの一意の名前。 |
constraint_values
|
config_setting と照合するためにターゲット プラットフォームが指定する必要がある constraint_values の最小セット。（実行プラットフォームはここでは考慮しません）。プラットフォームに追加されている制約値は無視されます。詳細については、
構成可能なビルド属性をご覧ください。
2 つの |
define_values
|
values と同じですが、--define フラグに関するものです。
つまり、以下のようになります。
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",
})
|
flag_values
|
values と同じですが、
ユーザー定義のビルドフラグに関するものです。ユーザー定義のフラグはラベルとして参照され、組み込みフラグは任意の文字列として参照されるため、これは別の属性です。 |
values
|
このルールは、 便宜上、構成値はビルドフラグとして指定します（ フラグがコマンドラインで明示的に設定されていない場合は、デフォルト値が使用されます。キーが辞書に複数回出現する場合は、最後のインスタンスのみが使用されます。コマンドラインで複数回設定できるフラグ（
|
ファイルグループ
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 を使用して 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",
],
)
引数
| 属性 | |
|---|---|
name |
このターゲットの一意の名前。 |
srcs
|
|
data
|
|
output_group
|
「出力グループ」は、ルールの実装で指定された、ターゲットの出力アーティファクトのカテゴリです。 |
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 つ目は、genquery はクエリの推移的クロージャの外側にあるターゲットが出力に影響を与えないようにスコープを指定する必要があることと、BUILD ファイルがワイルドカード依存関係をサポートしていないためです（たとえば、deps=["//a/..."] は使用できません）。
決定論的な出力を適用するために、genquery の出力は --order_output=full を使用して並べ替えられます。
出力ファイルの名前はルールの名前です。
例
この例では、指定されたターゲットの推移的クロージャにあるラベルのリストをファイルに書き込みます。
genquery(
name = "kiwi-deps",
expression = "deps(//kiwi:kiwi_lib)",
scope = ["//kiwi:kiwi_lib"],
)
引数
| 属性 | |
|---|---|
name |
このターゲットの一意の名前。 |
expression
|
a/BUILD のこの属性のラベル :b は、ターゲット //:b を参照します。
|
opts
|
bazel query に渡すことができるコマンドライン オプションに対応しています。ここでは、一部のクエリ オプション（--keep_going、--query_file、--universe_scope、--order_results、--order_output）は使用できません。ここで指定されていないオプションには、bazel query のコマンドラインと同様に、デフォルト値が使用されます。 |
scope
|
|
strict
|
|
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 つ以上のファイルを生成します。
genrules は、タスクに特定のルールがない場合に使用できる汎用のビルドルールです。たとえば、Bash のワンライナーを実行できます。ただし、C++ ファイルをコンパイルする必要がある場合は、既存の cc_* ルールに従ってください。手間のかかる作業はすべて自動的に完了しています。
テストの実行に genrule を使用しないでください。テストとテスト結果については、キャッシュ ポリシーや環境変数など、特別な要件があります。通常、テストはビルドの完了後にターゲット アーキテクチャで実行する必要がありますが、genrules はビルド中とホスト アーキテクチャで実行されます（この 2 つは異なる場合があります）。汎用のテストルールが必要な場合は、sh_test を使用します。
クロスコンパイルに関する考慮事項
クロスコンパイルの詳細については、ユーザー マニュアルをご覧ください。
genrules がビルド中に実行され、その出力がビルド後にデプロイまたはテストに使用されることがよくあります。マイクロコントローラ用に C コードをコンパイルする例を考えてみましょう。コンパイラは、C ソースファイルを受け取って、マイクロコントローラ上で実行するコードを生成します。生成されたコードは、明らかにビルドに使用された CPU では実行できませんが、C コンパイラ（ソースからコンパイルされた場合）自体は実行する必要があります。
ビルドシステムは、ホスト構成を使用してビルドを実行するマシンを記述し、ターゲット構成を使用してビルドの出力が実行されるマシンを記述します。これらを構成するオプションが用意されており、競合を回避するために、対応するファイルを別々のディレクトリに分離します。
genrules の場合、ビルドシステムは依存関係が適切にビルドされていることを確認します。srcs は（必要に応じて）ターゲット構成用にビルドされ、tools はhost構成用にビルドされ、出力はターゲット構成用とみなされます。また、genrule コマンドが対応するツールに渡すことができる
Make 変数も用意されています。
genrule では deps 属性を定義しません。他の組み込みルールは、ルール間で渡される言語依存メタ情報を使用して、依存ルールの処理方法を自動的に決定しますが、genrule ではこのレベルの自動化はできません。genrules は、純粋にファイルレベルとランファイル レベルで機能します。
特殊なケース
ホストホスト コンパイル: 場合によっては、ビルド中に出力も実行できるように、ビルドシステムで genrules を実行する必要があります。たとえば、genrule がカスタム コンパイラをビルドして、後で別の genrule が使用する場合、最初の genrule でコンパイラが実行されるため、ホスト構成用の出力を生成する必要があります。この場合、ビルドシステムは正しい処理を自動的に行います。ターゲット構成ではなく、ホスト構成の最初の 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 はハードコードされた絶対パスに依存できません。 - 同じまたは非常に類似した genrules が複数の場所で使用されている場合に備えて、共通の 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 asls $(dirname $x), one must escape it thus:ls $$(dirname $$x).- シンボリック リンクとディレクトリは作成しないでください。Bazel は、genrules によって作成されたディレクトリ/symlink 構造をコピーせず、ディレクトリの依存関係チェックが正常に行われません。
- 他のルールで 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) > $@",
)
引数
| 属性 | |
|---|---|
name |
このターゲットの一意の名前。 このルールの名前は、他の BUILD ルールの srcs セクションまたは deps セクションで参照できます。ルールによってソースファイルが生成される場合は、srcs 属性を使用する必要があります。 |
srcs
|
この属性は、
ビルドシステムは、genrule コマンドを実行する前にこれらの前提条件を確実にビルドします。これらの前提条件は、元のビルド リクエストと同じ構成を使用してビルドされます。これらの前提条件のファイルの名前は、 |
outs
|
出力ファイルはパッケージの境界を越えてはなりません。 出力ファイル名は、パッケージを基準とする相対名として解釈されます。
genrule コマンドは、所定の場所に各出力ファイルを作成することを想定しています。この場所は、genrule 固有の「Make」変数（ |
cmd
|
$(location)
と「Make」変数の置換が適用されます。
cmd_bash、cmd_ps、cmd_bat のいずれも適用できない場合のフォールバックです。
コマンドラインの長さがプラットフォームの上限（Linux/macOS では 64 K、Windows では 8 K）を超えると、genrule はコマンドをスクリプトに書き込み、そのスクリプトを実行して回避します。これは、すべての cmd 属性（ |
cmd_bash
|
この属性は |
cmd_bat
|
この属性は、
|
cmd_ps
|
この属性は、
Powershell を使いやすくし、エラーが発生しないようにするため、genrule で Powershell コマンドを実行する前に、次のコマンドを実行して環境をセットアップします。
|
exec_tools
|
tools 属性とまったく同じように動作しますが、これらの依存関係は、ホスト構成ではなくルールの実行プラットフォーム用に構成されます。つまり、exec_tools の依存関係には、tools の依存関係と同じ制限は適用されません。特に、独自の推移的依存関係にホスト構成を使用する必要はありません。詳細については、tools をご覧ください。
Blaze チームは、 |
executable
|
このフラグを True に設定すると、出力が実行可能ファイルであり、 生成された実行可能ファイルのデータ依存関係を宣言することはできません。 |
local
|
True に設定すると、この
これは、local をタグ（ |
message
|
このビルドステップが実行されるときに出力される進行状況メッセージ。デフォルトでは、メッセージは「出力の生成」（またはそれと同じくらい平凡なもの）になりますが、より具体的なメッセージを指定することもできます。 |
output_licenses
|
common attributes
をご覧ください。 |
output_to_bindir
|
True に設定すると、出力ファイルは |
tools
|
ビルドシステムは、genrule コマンドを実行する前にこれらの前提条件を確実にビルドします。これらの前提条件は、host 構成を使用してビルドされます。これらのツールはビルドの一部として実行されるためです。個々の
|
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 展開」と呼びます）し、それらのターゲットをビルドしてテストします。
例
現在のパッケージ内のすべての小規模なテストを実行するためのテストスイート。
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"],
)
引数
| 属性 | |
|---|---|
name |
このターゲットの一意の名前。 |
tags
|
「-」文字で始まるタグは、負のタグと見なされます。先行する「-」はタグの一部とはみなされないため、スイートタグ「-small」はテストの「small」サイズと一致します。その他のタグはすべて正のタグと見なされます。 正のタグをさらに明示的にするために、タグの先頭に「+」文字を付けることもできます。この場合、プラス記号はタグのテキストの一部として評価されません。単に、肯定的と否定的な区別がわかりやすくなるだけです。 テストスイートに含まれるのは、すべての陽性タグに一致し、陰性タグには一致しないテストルールのみです。これは、除外されたテストの依存関係の確認エラー チェックがスキップされるという意味ではありません。スキップされたテストの依存関係は、正当である必要がある（可視性の制約によってブロックされていないなど）必要があります。
テストの
相互に排他的なタグを含むテスト（すべての小規模テストと中規模テストなど）を含む |
tests
|
ここでは、言語に関係なく、すべての
|