ルール
エイリアス
alias(name, actual, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)
alias
ルールは、ルールの別名を作成します。
エイリアス設定は、「通常の」ターゲットに対してのみ機能します。特に、package_group
と test_suite
にエイリアスを設定することはできません。
エイリアス ルールには、独自の公開設定に関する宣言があります。その他の点では、参照するルールと同じように動作します(たとえば、エイリアスの testonly が無視され、参照されるルールの testonly-ness が使用されます)。
-
コマンドラインにエイリアスが指定されていると、テストは実行されません。参照されるテストを実行するエイリアスを定義するには、
tests
属性に 1 つのターゲットを指定して、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" }, )
以下は、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
がトップレベルのコマンドライン フラグと一致しない場合でも、一部のビルド ターゲットと一致する可能性があります。
メモ
- 複数の
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
|
constraint_values の最小セット。この config_setting に一致するためにターゲット プラットフォームが指定する必要があります。(実行プラットフォームはここでは考慮しません)。プラットフォームに追加の制約値は無視されます。詳しくは、
構成可能なビルド属性をご覧ください。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
が出力に影響を与えるためにクエリの推移的クロージャの外部にあるターゲットを防ぐためにスコープを指定する必要があるためです。2 つ目は、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 の 1 行コピーを実行できます。ただし、C++ ファイルをコンパイルする必要がある場合は、既存の cc_*
ルールを使用してください。複雑な作業はすべてすでに完了しています。
テストの実行に genrule を使用しないでください。テストとテスト結果については、キャッシュ ポリシーや環境変数など、特別な条件があります。通常、テストはビルドの完了後にターゲット アーキテクチャで実行する必要がありますが、genrules はビルド中とホスト アーキテクチャで実行されます(この 2 つは異なる場合があります)。汎用のテストルールが必要な場合は、sh_test
を使用します。
クロスコンパイルに関する考慮事項
クロスコンパイルの詳細については、ユーザー マニュアルをご覧ください。
genrules はビルド中に実行されますが、その出力は多くの場合、ビルド後にデプロイやテストに使用されます。マイクロコントローラ用に C コードをコンパイルする例を考えてみましょう。コンパイラは C ソースファイルを受け取り、マイクロコントローラで実行するコードを生成します。生成されたコードは、ビルドに使用された CPU では実行できないことは明らかですが、C コンパイラ(ソースからコンパイルされた場合)自体は実行する必要があります。
ビルドシステムは、ホスト構成を使用してビルドを実行するマシンを記述し、ターゲット構成を使用してビルドの出力を実行するマシンを記述します。それぞれのオプションを構成するオプションが用意されており、競合を避けるため、対応するファイルを別々のディレクトリに分離します。
genrules の場合、ビルドシステムは依存関係が適切にビルドされるようにします。srcs
は(必要に応じて)ターゲット構成に対してビルドされ、tools
は host 構成に対してビルドされ、出力はターゲット構成に対するものとみなされます。また、genrule コマンドが対応するツールに渡すことができる
「Make」変数も用意されています。
genrule では deps
属性を定義しません。他の組み込みルールでは、ルール間で渡される言語依存メタ情報を使用して、依存ルールの処理方法を自動的に決定しますが、genrules でこのレベルの自動化はできません。genrules は純粋にファイルレベルと runfile レベルで機能します。
特殊なケース
ホストホスト コンパイル: 場合によっては、ビルド中に出力も実行できるように、ビルドシステムで genrules を実行する必要があります。たとえば、genrule がカスタム コンパイラをビルドして、その後別の 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 では 64K、Windows では 8K、Windows では 8K)を超えると、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 コマンドを実行する前にこれらの前提条件を確実にビルドします。これらのツールはビルドの一部として実行されるため、ホスト構成を使用してビルドされます。個々の
|
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"], )
引数
属性 | |
---|---|
name |
このターゲットの一意の名前。 |
tags
|
「-」文字で始まるタグは、負タグと見なされます。先頭の「-」はタグの一部とはみなされないため、「-small」のスイートタグはテストの「small」サイズと一致します。その他のタグはすべて正タグと見なされます。 必要に応じて、正のタグを明確にするために、タグの先頭に「+」文字を付けることもできます。「+」はタグのテキストの一部として評価されません。単に肯定的と否定的な区別が読みやすくなるだけです。 テストスイートに含まれるのは、すべての正タグに一致し、負タグのいずれにも一致しないテストルールのみです。これは、除外されたテストの依存関係のエラーチェックがスキップされることを意味するものではありません。スキップされたテストの依存関係は、そのまま正しい(可視性の制約によってブロックされていないなど)である必要があります。
テストの
相互に排他的なタグを持つテスト(すべての小規模テストと中規模テストなど)を含む |
tests
|
ここでは言語に関係なくすべての
|