可設定的查詢 (cquery)

回報問題open_in_new 查看原始碼open_in_new

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 與 query 的 cquery 意義不同。這是因為 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 運算子會嘗試針對以第一個引數和第二個引數指定的設定所表示的標籤，尋找已設定的目標。

第二個引數的有效值是 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 在執行設定中設定其工具，因此下列查詢會產生下列輸出內容：

查詢	已建立目標	輸出內容
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 (布林值，default=True)

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

--include_aspects (布林值，default=True)

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

如果停用此標記，如果 X 僅透過切面依附，則 cquery somepath(X, Y) 和 cquery deps(X) | grep 'Y' 會省略 Y。

輸出格式

根據預設，cquery 輸出結果會產生標籤和設定組合的依依附元件排序清單。還有其他顯示結果的選項。

轉場

--transitions=lite
--transitions=full

設定轉換功能可在與頂層目標不同的設定下，在頂層目標底下建構目標。

舉例來說，目標可能會在其 tools 屬性中的所有依附元件上，執行轉換至執行設定。這就是所謂的屬性轉換。規則也可在自己的設定上實施轉換，也就是規則類別轉換。此輸出格式會輸出這些轉換的相關資訊，例如類型以及對建構選項的影響。

這個輸出格式是由 --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 檔案的位置，該檔案使用單一參數 target 定義名為 format 的函式。系統會針對查詢結果中的每個目標呼叫這個函式。或者，為了方便起見，您可以使用 --starlark:expr 標記，僅指定宣告為 def format(target): return expr 的函式主體。

Starlark 方言

查詢 Starlark 環境與 BUILD 或 .bzl 檔案不同。其中包含所有 Core Starlark 內建常數和函式，以及下方所述的一些 CPU 專屬常數 (例如，但不含 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 不知道版本選擇哪種分支版本，因此包含所有分支版本，以達到概略值。
• 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 不會自動從先前的指令抹除建構圖表，因此很容易從過往查詢中取得結果。舉例來說，genrule 會對其 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=<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 "+" -))"