cquery 是 query 的變體，可正確處理 select() 和建構選項對建構圖形的影響。
方法是針對 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)
每項結果都包含專屬 ID (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可瞭解完整 ID 的任何有效前置字元，類似於 Git 短雜湊。
如要查看完整 ID，請執行 $ bazel config。
目標模式評估
//foo 對 cquery 和 query 而言，這是因為 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 支援所有函式，但 allrdeps、buildfiles、rbuildfiles、siblings、tests 和 visible 除外。
cquery 也推出下列新函式：
config
expr ::= config(expr, word)
config 運算子會嘗試找出第一個引數標示的標籤所設定的目標，以及第二個引數指定的設定。
第二個引數的有效值為 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"],
)
Genrule 會在執行設定中設定工具，因此下列查詢會產生下列輸出內容：
| 查詢 | 已建構目標 | 輸出 |
|---|---|---|
| bazel cquery "//x:tool" | //x:tool | //x:tool(targetconfig) |
| bazel cquery "//x:tool" --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)
包含 aspect 新增的依附元件。
如果停用這個標記，且 X 只透過某個層面依附於 Y，則 cquery somepath(X, Y) 和 cquery deps(X) | grep 'Y' 會省略 Y。
輸出格式
根據預設，cquery 會輸出結果，並以依附元件順序排列標籤和設定配對的清單。您也可以使用其他選項公開結果。
轉場
--transitions=lite --transitions=full
設定轉換可用於在不同設定中，建構頂層目標下方的目標，而非頂層目標。
舉例來說，目標可能會對 tools 屬性中的所有依附元件強制轉換為 exec 設定。這就是所謂的屬性轉換。規則也可以對自身的設定強制執行轉換，這稱為規則類別轉換。這個輸出格式會輸出這些轉換的相關資訊，例如轉換類型，以及轉換對建構選項的影響。
這個輸出格式是由 --transitions 標記觸發，該標記預設設為 NONE。可以設為 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 旗標決定。但包含來源檔案。
這個輸出格式發出的所有路徑都與 execroot 相關，可透過 bazel info execution_root 取得。如果 bazel-out 便利符號連結存在，主要存放區中檔案的路徑也會相對於工作區目錄解析。
使用 Starlark 定義輸出格式
--output=starlark
這個輸出格式會為查詢結果中每個已設定的目標呼叫 Starlark 函式，並列印呼叫傳回的值。--starlark:file 標記會指定 Starlark 檔案的位置，該檔案定義了名為 format 的函式，並包含單一參數 target。系統會針對查詢結果中的每個 Target 呼叫這個函式。或者，為方便起見，您可以使用 --starlark:expr 旗標，只指定以 def format(target): return expr 宣告的函式主體。
「cquery」Starlark 方言
cquery Starlark 環境與 BUILD 或 .bzl 檔案不同。這包括所有核心 Starlark 內建常數和函式，以及下文所述的幾個 cquery 專屬常數和函式，但不包括 (例如) glob、native 或 rule，也不支援載入陳述式。
build_options(target)
build_options(target) 會傳回對應項，其鍵為建構選項 ID (請參閱「設定」)，值則為 Starlark 值。系統會從這個對應中省略值不是合法的 Starlark 值的建構選項。
如果目標是輸入檔案，build_options(target) 會傳回 None，因為輸入檔案目標的設定為空值。
提供者(目標)
providers(target) 會傳回對應，其中的鍵是供應器的名稱 (例如 "DefaultInfo")，值則是 Starlark 值。如果供應商的值不是合法的 Starlark 值，系統會從這個對應中省略供應商。
範例
列印 //foo 產生的所有檔案基本名稱清單 (以空格分隔)：
bazel cquery //foo --output=starlark \
--starlark:expr="' '.join([f.basename for f in providers(target)['DefaultInfo'].files.to_list()])"
在 //bar 和子封裝中，列印 rule 目標產生的所有檔案路徑 (以空格分隔)：
bazel cquery 'kind(rule, //bar/...)' --output=starlark \
--starlark:expr="' '.join([f.path for f in providers(target)['DefaultInfo'].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']"
為每個目標列印標籤，且每個目標只能有一個輸出內容。這個範例使用檔案中定義的 Starlark 函式。
$ cat example.cquery
def has_one_output(target):
return len(providers(target)["DefaultInfo"].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"存在於兩項設定中，cquery "deps(//foo)"應使用哪一項？config函式可協助您完成這項操作。
非決定性輸出
cquery 不會自動清除先前指令的建構圖。因此容易從先前的查詢中選取結果。
舉例來說，genrule 會對其 tools 屬性施加 exec 轉換，也就是在 exec 設定中設定工具。
下方顯示的圖表，就是這項轉換的後續影響。
$ cat > foo/BUILD <<
視您要評估的內容而定，這可能是您想要的行為，也可能不是。
如要停用這項功能，請在 cquery 前執行 blaze clean，確保分析圖表是最新狀態。
疑難排解
遞迴目標模式 (/...)
如果遇到下列情況：
$ 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 "+" -))"