可設定的查詢 (cquery)

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

cqueryquery 的變化版本,可正確處理 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

目標模式評估

//foocqueryquery 中的含義不同。這是因為 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 支援所有函式,但不支援 visiblesiblingsbuildfilestests

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"],
)

Genrules 會在 exec 設定中設定工具,因此下列查詢會產生下列輸出內容:

查詢 已建構的目標 輸出
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 (布林值,default=True)

將此標記設為 false 可篩除所有未在 BUILD 檔案中明確設定,而是由 Bazel 在其他位置設定的結果。其中包括篩選已解析的工具鍊。

--tool_deps (布林值,預設值為 True)

將此標記設為 false 可篩除所有已設定的目標,這些目標的路徑從查詢的目標跨越目標設定和非目標設定之間的轉換。如果查詢的目標位於目標設定中,設定 --notool_deps 只會傳回同時位於目標設定中的目標。如果查詢的目標位於非目標設定中,設定 --notool_deps 只會傳回非目標設定中的目標。這項設定通常不會影響篩選已解析工具鍊。

--include_aspects (布林值,預設值為 True)

包含由切面新增的依附元件。

如果這個標記停用,cquery somepath(X, Y)cquery deps(X) | grep 'Y' 會略過 Y,如果 X 只透過某個面向依附於 Y。

輸出格式

根據預設,cquery 會以標籤和設定組合的依附元件排序清單輸出結果。您也可以透過其他選項查看結果。

轉場

--transitions=lite
--transitions=full

設定轉換可用於在頂層目標下方,以不同於頂層目標的設定建構目標。

例如,目標可能會將 tools 屬性中所有依附元件的執行設定轉換到執行設定。這就是所謂的屬性轉換。規則也可以在自己的設定上強制執行轉換作業,稱為規則類別轉換。這個輸出格式會輸出這些轉場的相關資訊,例如轉場類型和對建構選項的影響。

這個輸出格式是由 --transitions 旗標預設為 NONE。可設為 FULLLITE 模式。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。查詢結果中的每個目標都會呼叫這個函式。或者,為方便起見,您可以使用 --starlark:expr 標記,只指定宣告為 def format(target): return expr 的函式主體。

「cquery」星形方言

cquery Starlark 環境與 BUILD 或 .bzl 檔案不同。其中包含所有核心 Starlark 內建常數和函式,以及下述幾個 C 查詢專用的函式,但不支援 globnativerule,且不支援載入陳述式。

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()])"

列印 //barrule 目標產生的所有檔案路徑清單 (以空格分隔) 及其子套件:

  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 和查詢

cqueryquery 相輔相成,各自在不同的利基市場表現出色。請考量以下因素,決定適合您的選項:

  • cquery 遵循特定的 select() 分支版本,以模擬您建構的圖形模型。query 不知道建構作業選擇哪個分支,因此會納入所有分支來進行過度近似處理。
  • cquery 的準確度需要建構比 query 更多的圖表。具體來說,cquery 會評估已設定的目標,而 query 只會評估目標。這會耗費更多時間和記憶體。
  • cquery查詢語言的解讀會導致模糊不清,而 query 則可避免這種情況。舉例來說,如果 "//foo" 存在於兩種設定中,請問 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 不會自動從先前的指令抹除建構圖表,因此較容易擷取過往查詢的結果。舉例來說,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 (exec_config)
...

    $ bazel cquery "//foo:tool"
tool(exec_config)

解決方法:變更任何啟動選項,強制重新分析已設定的目標。例如,將 --test_arg=&lt;whatever&gt; 加入建構指令。

疑難排解

遞迴目標模式 (/...)

如果遇到以下狀況:

$ 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 "+" -))"