cquery
は、ビルドグラフに対する select()
とビルド オプションの効果を正しく処理する query
のバリアントです。
これは、これらの効果を統合する Bazel の分析フェーズの結果に対して実行することで実現されます。一方、query
は、オプションが評価される前に、Bazel の読み込みフェーズの結果に対して実行されます。
次に例を示します。
$ cat > tree/BUILD <<EOF sh_library( name = "ash", deps = select({ ":excelsior": [":manna-ash"], ":americana": [":white-ash"], "//conditions:default": [":common-ash"], }), ) sh_library(name = "manna-ash") sh_library(name = "white-ash") sh_library(name = "common-ash") config_setting( name = "excelsior", values = {"define": "species=excelsior"}, ) config_setting( name = "americana", values = {"define": "species=americana"}, ) EOF
# Traditional query: query doesn't know which select() branch you will choose, # so it conservatively lists all of possible choices, including all used config_settings. $ bazel query "deps(//tree:ash)" --noimplicit_deps //tree:americana //tree:ash //tree:common-ash //tree:excelsior //tree:manna-ash //tree:white-ash # cquery: cquery lets you set build options at the command line and chooses # the exact dependencies that implies (and also the config_setting targets). $ bazel cquery "deps(//tree:ash)" --define species=excelsior --noimplicit_deps //tree:ash (9f87702) //tree:manna-ash (9f87702) //tree:americana (9f87702) //tree:excelsior (9f87702)
各結果には、ターゲットをビルドする構成の一意の識別子 (9f87702)
が含まれます。
cquery
は構成済みのターゲット グラフで実行されるため、構成済みのターゲットではないため、ビルド アクションなどのアーティファクトに関する分析情報や test_suite
ルールへのアクセス権はありません。前者については、aquery
をご覧ください。
基本的な構文
単純な cquery
呼び出しは次のようになります。
bazel cquery "function(//target)"
クエリ式 "function(//target)"
は、次のものから構成されます。
function(...)
は、ターゲットで実行する関数です。cquery
は、query
の関数の大部分と、いくつかの新しい関数をサポートしています。//target
は、関数にフィードされる式です。この例では、式は単純なターゲットです。ただし、クエリ言語では関数のネストも可能です。例については、クエリガイドをご覧ください。
cquery
には、読み込みと分析フェーズを実行するターゲットが必要です。特に指定しない限り、cquery
はクエリ式にリストされているターゲットを解析します。最上位のビルド ターゲットの依存関係をクエリする方法については、--universe_scope
をご覧ください。
構成
次の行をご覧ください。
//tree:ash (9f87702)
//tree:ash
が ID 9f87702
の構成でビルドされたことを意味します。ほとんどのターゲットでは、これは構成を定義するビルド オプション値の不透明なハッシュです。
構成の完全な内容を表示するには、次のコマンドを実行します。
$ bazel config 9f87702
9f87702
は、完全な ID の接頭辞です。これは、完全な ID が SHA-256 ハッシュであり、長くて追跡が難しいためです。cquery
は、Git ショートハッシュと同様に、完全な ID の有効なプレフィックスを認識します。完全な ID を表示するには、$ bazel config
を実行します。
ターゲット パターンの評価
cquery
と query
では //foo
の意味が異なります。これは、cquery
が構成されたターゲットを評価し、ビルドグラフに //foo
の構成バージョンが複数存在する場合があるためです。
cquery
の場合、クエリ式のターゲット パターンは、そのパターンに一致するラベルを持つ構成済みのターゲットごとに評価されます。出力は確定的ですが、cquery
は、コアクエリの順序指定の範囲を超える順序を保証しません。
これにより、query
よりもクエリ式の結果が弱くなります。たとえば、以下では複数の結果を生成できます。
# Analyzes //foo in the target configuration, but also analyzes # //genrule_with_foo_as_tool which depends on an exec-configured # //foo. So there are two configured target instances of //foo in # the build graph. $ bazel cquery //foo --universe_scope=//foo,//genrule_with_foo_as_tool //foo (9f87702) //foo (exec)
クエリを実行するインスタンスを正確に宣言するには、config
関数を使用します。
ターゲット パターンの詳細については、query
のターゲット パターンのドキュメントをご覧ください。
関数
query
でサポートされている一連の関数のうち、cquery
は visible
、siblings
、buildfiles
、tests
を除くすべての関数をサポートします。
cquery
には、次の新しい関数も導入されています。
config
expr ::= config(expr, word)
config
演算子は、最初の引数で指定されたラベルと 2 番目の引数で指定された構成で示されるラベルに対して構成されたターゲットを見つけようとします。
2 番目の引数の有効な値は、null
またはカスタム構成ハッシュです。ハッシュは、$
bazel config
または以前の cquery
の出力から取得できます。
例:
$ bazel cquery "config(//bar, 3732cc8)" --universe_scope=//foo
$ bazel cquery "deps(//foo)" //bar (exec) //baz (exec) $ bazel cquery "config(//baz, 3732cc8)"
指定された構成で最初の引数の結果がすべて見つからない場合は、見つかった結果のみが返されます。指定された構成で結果が見つからない場合は、クエリは失敗します。
オプション
ビルド オプション
cquery
は通常の Bazel ビルドで実行されるため、ビルド中に使用できる一連のオプションを継承します。
cquery オプションの使用
--universe_scope
(カンマ区切りのリスト)
多くの場合、構成されたターゲットの依存関係は遷移を経て、依存関係の構成と異なる構成になります。このフラグを使用すると、ターゲットが別のターゲットの依存関係または推移的依存関係として作成されたかのように、ターゲットに対してクエリを実行できます。次に例を示します。
# x/BUILD genrule( name = "my_gen", srcs = ["x.in"], outs = ["x.cc"], cmd = "$(locations :tool) $< >$@", tools = [":tool"], ) cc_binary( name = "tool", srcs = ["tool.cpp"], )
genrules は exec 構成でツールを構成するため、次のクエリで次の出力が生成されます。
クエリ | ビルド済みターゲット | 出力 |
---|---|---|
bazel cquery "//x:ツール" | //x:tool | //x:tool(targetconfig) |
bazel cquery "//x:ツール" --universe_scope="x:my_gen" | //x:my_gen | //x:tool(execconfig) |
このフラグが設定されている場合、その内容はビルドされます。設定されていない場合、代わりにクエリ式に指定されているすべてのターゲットがビルドされます。ビルドされたターゲットの推移的クロージャがクエリの世界として使用されます。いずれの場合も、ビルドするターゲットはトップレベルでビルド可能(つまり、トップレベル オプションと互換性がある)である必要があります。cquery
は、これらのトップレベル ターゲットの推移的クロージャで結果を返します。
トップレベルのクエリ式ですべてのターゲットを作成することは可能ですが、そうしないほうが良い場合があります。たとえば、--universe_scope
を明示的に設定すると、不要な構成でターゲットが複数回ビルドされなくなる可能性があります。また、探しているターゲットの構成バージョンを指定するのにも役立ちます(現時点では、これ以外の方法では完全に指定できないため)。クエリ式が deps(//foo)
よりも複雑な場合は、このフラグを設定する必要があります。
--implicit_deps
(ブール値、デフォルト=True)
このフラグを false に設定すると、BUILD ファイルで明示的に設定されず、Bazel によって他の場所に設定された結果がすべて除外されます。これには、解決されたツールチェーンのフィルタリングが含まれます。
--tool_deps
(ブール値、デフォルト=True)
このフラグを false に設定すると、クエリされたターゲットからそれらのターゲットへのパスがターゲット構成とターゲット以外の構成間の移行をまたがるすべての構成済みターゲットが除外されます。クエリされたターゲットがターゲット構成内にある場合、--notool_deps
を設定すると、ターゲット構成にも存在するターゲットのみが返されます。クエリされたターゲットがターゲット以外の構成にある場合、--notool_deps
を設定すると、ターゲット以外の構成のターゲットのみが返されます。通常、この設定は解決済みのツールチェーンのフィルタリングには影響しません。
--include_aspects
(ブール値、デフォルト=True)
アスペクトによって追加された依存関係を含めます。
このフラグが無効になっている場合、X がアスペクトを通じてのみ依存している場合、cquery somepath(X, Y)
と cquery deps(X) | grep 'Y'
は Y を省略します。
出力形式
デフォルトでは、cquery はラベルと構成のペアを依存関係順に並べたリストを出力します。結果を公開する方法は他にもあります。
切り替え効果
--transitions=lite --transitions=full
構成の遷移は、トップレベル ターゲットの下にトップレベル ターゲットとは異なる構成でターゲットを構築するために使用されます。
たとえば、ターゲットが tools
属性のすべての依存関係に exec 構成への移行を課すことがあります。これらは属性遷移と呼ばれます。ルールでは、ルールクラスの遷移と呼ばれる独自の構成に遷移を適用することもできます。この出力形式では、移行のタイプやビルド オプションへの影響など、移行に関する情報が出力されます。
この出力形式は、デフォルトで NONE
に設定されている --transitions
フラグによってトリガーされます。FULL
モードまたは LITE
モードに設定できます。FULL
モードは、ルールクラスの遷移と属性の遷移に関する情報を出力します。この情報には、遷移前後のオプションの詳細な差分も含まれます。LITE
モードでは、同じ情報がオプション差分なしで出力されます。
プロトコル メッセージ出力
--output=proto
このオプションを使用すると、結果のターゲットがバイナリ プロトコル バッファ形式で出力されます。プロトコル バッファの定義は、src/main/protobuf/analysis_v2.proto で確認できます。
CqueryResult
は、cquery の結果を含むトップレベルのメッセージです。ConfiguredTarget
メッセージのリストと Configuration
メッセージのリストが含まれます。各 ConfiguredTarget
には、対応する Configuration
メッセージの id
フィールドの値と等しい configuration_id
があります。
--[no]proto:include_configurations
デフォルトでは、cquery の結果は、構成された各ターゲットの一部として構成情報を返します。この情報を省略して、クエリの proto 出力とまったく同じ形式の proto 出力を取得するには、このフラグを false に設定します。
proto 出力関連のオプションについては、クエリの proto 出力のドキュメントをご覧ください。
グラフ出力
--output=graph
このオプションは、Graphviz 互換の .dot ファイルとして出力を生成します。詳細については、query
のグラフ出力のドキュメントをご覧ください。cquery
は --graph:node_limit
と --graph:factored
もサポートしています。
ファイル出力
--output=files
このオプションは、bazel build
呼び出しの最後に出力されるリストと同様に、クエリに一致する各ターゲットによって生成された出力ファイルのリストを出力します。出力には、--output_groups
フラグによって決定された、リクエストされた出力グループでアドバタイズされたファイルのみが含まれます。これにはソースファイルが含まれます。
この出力形式で出力されるすべてのパスは、bazel info execution_root
で取得できる execroot からの相対パスです。bazel-out
のコンビニエンス シンボリック リンクが存在する場合、メイン リポジトリ内のファイルのパスもワークスペース ディレクトリからの相対パスで解決されます。
Starlark を使用して出力形式を定義する
--output=starlark
この出力形式は、クエリ結果に構成されたターゲットごとに Starlark 関数を呼び出し、呼び出しによって返された値を出力します。--starlark:file
フラグは、target
という単一のパラメータを持つ format
という関数を定義する Starlark ファイルの場所を指定します。この関数は、クエリ結果の Target ごとに呼び出されます。便宜上、--starlark:expr
フラグを使用して、def format(target): return expr
として宣言された関数の本文のみを指定することもできます。
「cquery」Starlark 言語
cquery Starlark 環境は、BUILD ファイルや .bzl ファイルとは異なります。これには、すべての Starlark の主要な組み込み定数と関数と、以下で説明する cquery 固有のものが含まれますが、glob
、native
、rule
などは含まれておらず、load ステートメントをサポートしていません。
build_options(target)
build_options(target)
は、キーがビルド オプション識別子(構成を参照)で、値が Starlark 値であるマップを返します。値が正規の Starlark 値ではないビルド オプションは、このマップから除外されます。
ターゲットが入力ファイルの場合、入力ファイルのターゲットの構成が null であるため、build_options(target)
は None を返します。
プロバイダ(ターゲット)
providers(target)
は、キーがプロバイダ("DefaultInfo"
など)の名前で、値が Starlark 値であるマップを返します。値が有効な Starlark 値ではないプロバイダは、このマップから除外されます。
例
//foo
によって生成されたすべてのファイルのベース名のスペース区切りリストを出力します。
bazel cquery //foo --output=starlark \ --starlark:expr="' '.join([f.basename for f in target.files.to_list()])"
//bar
とそのサブパッケージ内の rule ターゲットによって生成されたすべてのファイルのパスをスペース区切りのリストで出力します。
bazel cquery 'kind(rule, //bar/...)' --output=starlark \ --starlark:expr="' '.join([f.path for f in target.files.to_list()])"
//foo
によって登録されたすべてのアクションのニーモニックのリストを出力します。
bazel cquery //foo --output=starlark \ --starlark:expr="[a.mnemonic for a in target.actions]"
cc_library
//baz
によって登録されたコンパイル出力のリストを出力します。
bazel cquery //baz --output=starlark \ --starlark:expr="[f.path for f in target.output_groups.compilation_outputs.to_list()]"
//foo
をビルドするときに、コマンドライン オプション --javacopt
の値を出力します。
bazel cquery //foo --output=starlark \ --starlark:expr="build_options(target)['//command_line_option:javacopt']"
各ターゲットのラベルを 1 つだけ出力します。この例では、ファイルで定義された Starlark 関数を使用します。
$ cat example.cquery def has_one_output(target): return len(target.files.to_list()) == 1 def format(target): if has_one_output(target): return target.label else: return "" $ bazel cquery //baz --output=starlark --starlark:file=example.cquery
厳密に Python 3 である各ターゲットのラベルを出力します。この例では、ファイルで定義された Starlark 関数を使用します。
$ cat example.cquery def format(target): p = providers(target) py_info = p.get("PyInfo") if py_info and py_info.has_py3_only_sources: return target.label else: return "" $ bazel cquery //baz --output=starlark --starlark:file=example.cquery
ユーザー定義のプロバイダから値を抽出します。
$ cat some_package/my_rule.bzl MyRuleInfo = provider(fields={"color": "the name of a color"}) def _my_rule_impl(ctx): ... return [MyRuleInfo(color="red")] my_rule = rule( implementation = _my_rule_impl, attrs = {...}, ) $ cat example.cquery def format(target): p = providers(target) my_rule_info = p.get("//some_package:my_rule.bzl%MyRuleInfo'") if my_rule_info: return my_rule_info.color return "" $ bazel cquery //baz --output=starlark --starlark:file=example.cquery
cquery と query
cquery
と query
は互いに補完し合い、さまざまなニッチな分野に優れています。次の点を考慮して、どちらが適しているかを判断してください。
cquery
は特定のselect()
ブランチに従って、作成したグラフを正確にモデル化します。query
はビルドでどのブランチが選択されるか認識できないため、すべてのブランチを含めることで過剰近似します。cquery
の精度を得るには、query
よりも多くのグラフを作成する必要があります。具体的には、cquery
は構成済みのターゲットを評価しますが、query
はターゲットのみを評価します。この場合、処理に時間がかかり、メモリの使用量が増えます。cquery
によるクエリ言語の解釈により、query
が回避するあいまいさが生じます。たとえば、"//foo"
が 2 つの構成に存在する場合、cquery "deps(//foo)"
ではどちらを使用すればよいですか。これにはconfig
関数が役立ちます。- 新しいツールとして、
cquery
は特定のユースケースをサポートしていません。詳しくは、既知の問題をご覧ください。
既知の問題
cquery
が「ビルド」するすべてのターゲットは同じ構成である必要があります。
クエリを評価する前に、cquery
はビルド アクションが実行される直前までビルドをトリガーします。「ビルド」するターゲットは、デフォルトではクエリ式に出現するすべてのラベルから選択されます(これは --universe_scope
でオーバーライドできます)。これらは同じ構成である必要があります。
これらは通常、最上位の「ターゲット」構成を共有しますが、ルールは受信エッジ遷移により独自の構成を変更できます。この点で cquery
は不十分です。
回避策: 可能であれば、--universe_scope
をより厳密なスコープに設定します。次に例を示します。
# This command attempts to build the transitive closures of both //foo and # //bar. //bar uses an incoming edge transition to change its --cpu flag. $ bazel cquery 'somepath(//foo, //bar)' ERROR: Error doing post analysis query: Top-level targets //foo and //bar have different configurations (top-level targets with different configurations is not supported) # This command only builds the transitive closure of //foo, under which # //bar should exist in the correct configuration. $ bazel cquery 'somepath(//foo, //bar)' --universe_scope=//foo
--output=xml
はサポートされていません。
非確定的な出力。
cquery
は、前のコマンドからビルドグラフを自動的にワイプしないため、過去のクエリから結果を取得する可能性が高くなります。たとえば、genrule
は tools
属性で exec 移行を行います。つまり、exec 構成でツールを構成します。
この遷移の長引く影響を以下に示します。
$ cat > foo/BUILD <<<EOF genrule( name = "my_gen", srcs = ["x.in"], outs = ["x.cc"], cmd = "$(locations :tool) $< >$@", tools = [":tool"], ) cc_library( name = "tool", ) EOF $ bazel cquery "//foo:tool" tool(target_config) $ bazel cquery "deps(//foo:my_gen)" my_gen (target_config) tool (exec_config) ... $ bazel cquery "//foo:tool" tool(exec_config)
回避策: 起動オプションを変更して、構成済みのターゲットを強制的に再分析します。たとえば、ビルドコマンドに --test_arg=<whatever>
を追加します。
トラブルシューティング
再帰ターゲット パターン(/...
)
発生した場合:
$ bazel cquery --universe_scope=//foo:app "somepath(//foo:app, //foo/...)" ERROR: Error doing post analysis query: Evaluation failed: Unable to load package '[foo]' because package is not in scope. Check that all target patterns in query expression are within the --universe_scope of this query.
これは、パッケージ //foo
が --universe_scope=//foo:app
に含まれているにもかかわらず、そのスコープ外にあることを誤って示唆しています。これは、cquery
の設計上の制限によるものです。回避策として、ユニバース スコープに //foo/...
を明示的に含めます。
$ bazel cquery --universe_scope=//foo:app,//foo/... "somepath(//foo:app, //foo/...)"
それでもうまくいかない場合(たとえば、選択したビルドフラグで //foo/...
の一部のターゲットをビルドできない場合など)は、前処理クエリを使用してパターンを構成パッケージに手動でラップ解除します。
# Replace "//foo/..." with a subshell query call (not cquery!) outputting each package, piped into # a sed call converting "<pkg>" to "//<pkg>:*", piped into a "+"-delimited line merge. # Output looks like "//foo:*+//foo/bar:*+//foo/baz". # $ bazel cquery --universe_scope=//foo:app "somepath(//foo:app, $(bazel query //foo/... --output=package | sed -e 's/^/\/\//' -e 's/$/:*/' | paste -sd "+" -))"