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](/versions/6.5.0/reference/be/general#test_suite)
規則。如需前者,請參閱 [aquery](/versions/6.5.0/docs/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
主機設定會使用特殊 ID (HOST)
。非產生的來源檔案 (例如 srcs
中常見的來源檔案) 不需要設定特殊 ID (null)
(因為不需要設定)。
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 a host-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 (HOST)
如要精確宣告要查詢的執行個體,請使用 config
函式。
如要進一步瞭解目標模式,請參閱 query
的目標模式說明文件。
函式
在 query
支援的函式組合中,cquery
支援 visible
、siblings
、buildfiles
和 tests
以外的所有函式。
cquery
也會提供下列新函式:
config
expr ::= config(expr, word)
config
運算子會嘗試針對第一個引數指定的標籤,以及第二個引數指定的設定,尋找已設定的標籤。
第二個引數的有效值包括 target
、host
、null
或自訂設定雜湊。雜湊可以從 $
bazel config
或 cquery
先前的輸出內容中擷取。
例:
$ bazel cquery "config(//bar, host)" --universe_scope=//foo
$ bazel cquery "deps(//foo)" //bar (HOST) //baz (3732cc8) $ 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_library( name = "tool", )
Genrules 會在主機設定中設定工具,因此下列查詢會產生下列輸出內容:
查詢 | 已建構的目標 | 輸出內容 |
---|---|---|
bazel cquery "//x:tool" | //x:tool | //x:tool(targetconfig) |
bazel cquery "//x:tool" --universe_scope="//x:my_gen" | //x:my_gen | //x:tool(hostconfig) |
如果設定此標記,則會建構其內容。如未設定,系統會改為建構查詢運算式中提及的所有目標。而建構目標的遞移性會做為查詢的宇宙使用。無論您採用何種方式,要建構的目標都必須能在頂層建構(也就是與頂層選項相容)。cquery
會傳回這些頂層目標的遞移關閉結果。
即使您可以在頂層查詢運算式中建構所有目標,這麼做仍可能有所助益。舉例來說,明確設定 --universe_scope
可能會導致在您不關注的設定中,多次建立目標。這也能協助您指定所需目標的設定版本 (因為目前您無法透過任何其他方式完全指定)。如果您的查詢運算式比 deps(//foo)
更複雜,應設定此旗標。
--implicit_deps
(布林值,default=True)
將此標記設為 false,會篩除所有未在 BUILD 檔案中明確設定,而是 Bazel 在其他位置設定的所有結果。其中包括篩選已解析的工具鍊。
--tool_deps
(布林值,default=True)
將此標記設為 false 會篩除所有已設定的目標,且查詢目標與非目標設定之間的轉換會跨越目標設定的路徑。如果查詢的目標位於目標設定中,設定 --notool_deps
只會傳回同時位於目標設定中的目標。如果查詢的目標位於非目標設定中,設定 --notool_deps
只會傳回非目標設定中的目標。這項設定通常不會影響篩選已解析工具鍊。
--include_aspects
(布林值,default=True)
切面可以在版本中加入其他依附元件。根據預設,cquery
不會遵循切面,因為這會讓可查詢的圖表放大,並佔用較多記憶體。但遵循這些指令會產生更準確的結果。
如果您不擔心大型查詢的記憶體影響,請在 bazelrc 中預設啟用此標記。
如果查詢的切面已停用,您可能會遇到一個問題,也就是目標 X 在建構目標 Y 時會失敗,但 cquery somepath(Y, X)
和 cquery deps(Y) | grep 'X'
不會傳回結果,因為依附元件是透過切面發生。
輸出格式
根據預設,cquery 輸出會產生依依附元件排序的標籤和設定組合清單。您也可以透過其他選項查看結果。
轉場
--transitions=lite --transitions=full
設定轉換可用來在與頂層目標不同的設定下建構目標。
例如,目標可能會將 tools
屬性中所有依附元件的主機設定移轉到主機設定。這就是所謂的屬性轉換。規則也可以在自己的設定上強制執行轉換作業,稱為規則類別轉換。這個輸出格式會輸出這些轉場效果的相關資訊,例如轉換類型以及對建構選項的影響。
這個輸出格式是由 --transitions
旗標預設為 NONE
。可設為 FULL
或 LITE
模式。FULL
模式會輸出規則類別轉換和屬性轉換的相關資訊,包括轉換前後選項的詳細差異。LITE
模式會輸出相同的資訊,但沒有選項差異。
通訊協定訊息輸出
--output=proto
這個選項會讓產生的目標以二進位通訊協定緩衝區格式顯示。您可以在 src/main/protobuf/analysis.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
標記決定)。其中包含來源檔案。
使用 Starlark 定義輸出格式
--output=starlark
這個輸出格式會對查詢結果中的每個已設定的目標呼叫 Starlark 函式,然後輸出呼叫傳回的值。--starlark:file
標記指定 Starlark 檔案的位置,該檔案定義了名為 format
的函式,其中含有單一參數 target
。查詢結果中的每個目標都會呼叫這個函式。或者,為方便起見,您也可以使用 --starlark:expr
標記,僅指定宣告為 def format(target): return expr
的函式主體。
「cquery」星形方言
cquery Starlark 環境與 BUILD 或 .bzl 檔案不同。其中包含所有核心 Starlark 內建常數和函式,以及下述幾個 C 查詢專用的函式,但不支援 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 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']"
顯示只有一個輸出內容的目標標籤。這個範例使用檔案中定義的 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 和查詢
cquery
和 query
彼此相輔相成,適合各種分眾市場。請先考量下列幾點,再決定自己適合何者:
cquery
遵循特定的select()
分支版本,以模擬您建構的圖形模型。query
不知道版本選擇的是哪個分支版本,因此請加入所有分支版本過於接近。- 與
query
相比,cquery
的精確度需要建構更多圖表。具體來說,cquery
會評估設定的目標,而query
只會評估目標。這麼做需要較多時間,且會耗用較多記憶體。 cquery
對查詢語言的解讀會產生query
避免的不確定性。舉例來說,如果"//foo"
存在於兩種設定中,請問cquery "deps(//foo)"
應使用哪個設定?[config](#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
不會自動從先前的指令抹除建構圖表,因此較容易擷取過往查詢的結果。舉例來說,genquery
會在其 tools
屬性上公開主機轉換,也就是說,它會在主機設定中設定其工具。
您可以在下方查看轉換後的運作過程。
$ 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 (host_config) ... $ bazel cquery "//foo:tool" tool(host_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.
這錯誤顯示即使 --universe_scope=//foo:app
含有套件 //foo
,套件也不在範圍內。這是因為 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 "+" -))"