aquery 指令可讓您查詢建構圖中的動作。
它會在事後分析設定的目標圖上運作，以及公開
動作、成果及其關係的相關資訊。
想查看動作/成果屬性時，aquery 就非常實用
從設定的目標圖表產生的結果例如，實際執行的指令及其輸入/輸出/助憶法。
這項工具可接受多個指令列選項。值得注意的是，aquery 指令會在一般 Bazel 建構作業上執行，並繼承建構期間可用的選項組合。
它支援傳統 query 可用的函式，但 siblings、buildfiles 和 tests 則不支援。
aquery 輸出內容範例 (不含詳細資料)：
$ bazel aquery 'deps(//some:label)' action 'Writing file some_file_name' Mnemonic: ... Target: ... Configuration: ... ActionKey: ... Inputs: [...] Outputs: [...]
基本語法
以下為 aquery 語法的簡單範例：
bazel aquery "aquery_function(function(//target))"
查詢運算式 (以引號括住) 包含下列項目：
# aquery examples:
# Get the action graph generated while building //src/target_a
$ bazel aquery '//src/target_a'
# Get the action graph generated while building all dependencies of //src/target_a
$ bazel aquery 'deps(//src/target_a)'
# Get the action graph generated while building all dependencies of //src/target_a
# whose inputs filenames match the regex ".*cpp".
$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'
使用 aquery 函式
有三個 aquery 函式：
inputs：依輸入內容篩選動作。outputs：按照輸出內容篩選動作mnemonic：依記憶法篩選動作
expr ::= inputs(word, expr)
inputs 運算子會傳回建構 expr 時產生的動作，其輸入檔案名稱會與 word 提供的規則運算式相符。
$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'
outputs 和 mnemonic 函式使用類似的語法。
您亦可結合函式以執行 AND 作業。例如：
$ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'
上述指令會找出與建構 //src/target_a 相關的所有操作。
其記憶法符合 "Cpp.*" 且輸入內容符合模式
".*cpp"和"foo.*"。
以下為語法錯誤的示例：
$ bazel aquery 'deps(inputs(".*cpp", //src/target_a))'
ERROR: aquery filter functions (inputs, outputs, mnemonic) produce actions,
and therefore can't be the input of other function types: deps
deps(inputs(".*cpp", //src/target_a))
選項
建構選項
aquery 會在一般 Bazel 建構作業上執行，因此會繼承建構期間可用的選項組合。
Aquery 選項
--output=(text|summary|proto|jsonproto|textproto), default=text
預設輸出格式 (text) 是人類可讀的格式，請使用 proto、textproto 或 jsonproto 來提供機器可讀的格式。Proto 訊息為 analysis.ActionGraphContainer。
--include_commandline, default=true
在輸出中包含動作指令列的內容 (可能很大)。
--include_artifacts, default=true
包括動作輸入和輸出內容的名稱 (可能很大)。
--include_aspects, default=true
是否要在輸出內容中加入 Aspect 產生的動作。
--include_param_files, default=false
加入指令中所用參數檔案的內容 (可能很大)。
--include_file_write_contents, default=false
針對 actions.write() 動作加入檔案內容，以及
SourceSymlinkManifest 動作的資訊清單檔案。檔案內容
以 --output=xxxproto 的 file_contents 欄位傳回。
使用 --output=text 時，輸出結果會
FileWriteContents: [<base64-encoded file contents>]
行
--skyframe_state, default=false
在不執行額外分析的情況下，從 Skyframe 轉儲動作圖。
其他工具和功能
針對 Skyframe 狀態執行查詢
SkyFrame 會評估並 Bazel 的增量模型。在 Bazel 伺服器的每個執行個體中，SkyFrame 都會儲存依附元件圖表 從先前「分析」階段執行時建構而成。
在某些情況下，在 Skyframe 上查詢動作圖表會很有幫助。應用情境範例如下：
- 執行
bazel build //target_a - 執行
bazel build //target_b - 已產生檔案
foo.out。
身為 Bazel 使用者，我想判斷 foo.out 是否從建構作業產生
//target_a 或 //target_b。
一個可以執行 bazel aquery 'outputs("foo.out", //target_a)'，並
bazel aquery 'outputs("foo.out", //target_b)'以便決定
建立 foo.out 並接收目標不過
之前建構的目標可以大於 2，這樣就能執行多個 aquery
省去麻煩
或者，您也可以使用 --skyframe_state 標記：
# List all actions on Skyframe's action graph
$ bazel aquery --output=proto --skyframe_state
# or
# List all actions on Skyframe's action graph, whose output matches "foo.out"
$ bazel aquery --output=proto --skyframe_state 'outputs("foo.out")'
在 --skyframe_state 模式下，aquery 會擷取 Skyframe 在 Bazel 例項上保留的動作圖形內容，並視需要對其執行篩選，然後輸出內容，而無須重新執行分析階段。
特殊注意事項
輸出格式
--skyframe_state 目前僅適用於 --output=proto
和--output=textproto
查詢運算式中未包含目標標籤
目前，--skyframe_state 會查詢 SkyFrame 上的整個動作圖表，
無論目標為何在查詢中指定目標標籤和 --skyframe_state 會造成語法錯誤：
# WRONG: Target Included
$ bazel aquery --output=proto --skyframe_state **//target_a**
ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.
# WRONG: Target Included
$ bazel aquery --output=proto --skyframe_state 'inputs(".*.java", **//target_a**)'
ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.
# CORRECT: Without Target
$ bazel aquery --output=proto --skyframe_state
$ bazel aquery --output=proto --skyframe_state 'inputs(".*.java")'
比較 Aquery 輸出結果
您可以使用 aquery_differ 工具比較兩個不同 aquery 呼叫的輸出內容。舉例來說，如果您對規則定義進行一些變更，並想驗證執行的命令列是否未變更，aquery_differ 是適當的工具。
您可以在 bazelbuild/bazel 存放區中使用這項工具。 如要使用它，請將存放區複製到本機電腦。使用範例：
$ bazel run //tools/aquery_differ -- \ --before=/path/to/before.proto \ --after=/path/to/after.proto \ --input_type=proto \ --attrs=cmdline \ --attrs=inputs
上述指令會傳回查詢輸出的 before 和 after 之間的差異：
有哪些動作出現在其中，但不是其他動作；這兩個動作不同
每個查詢輸出中的指令列/輸入內容...)。執行上述指令的結果如下：
Aquery output 'after' change contains an action that generates the following outputs that aquery output 'before' change doesn't:
...
/list of output files/
...
[cmdline]
Difference in the action that generates the following output(s):
/path/to/abc.out
--- /path/to/before.proto
+++ /path/to/after.proto
@@ -1,3 +1,3 @@
...
/cmdline diff, in unified diff format/
...
指令選項
--before, --after：要比較的 aquery 輸出檔案
--input_type=(proto|text_proto), default=proto：輸入格式
檔案。支援 proto 和 textproto aquery 輸出內容。
--attrs=(cmdline|inputs), default=cmdline：動作屬性
要比較的內容
切面上的切面
Aspects 可以彼此相疊。這些層面產生的動作的 aquery 輸出內容就會包含層面路徑，也就是套用至產生動作的目標的層面序列。
Aspect-on-Aspect 範例：
t0 ^ | <- a1 t1 ^ | <- a2 t2
讓 i 成為規則 ri 的目標，可套用切面 i 並提供給依附元件
假設 a2 套用至目標 t0 時會產生動作 X。模型會根據
動作 X 的 bazel aquery --include_aspects 'deps(//t2)' 會是：
action ...
Mnemonic: ...
Target: //my_pkg:t0
Configuration: ...
AspectDescriptors: [//my_pkg:rule.bzl%**a2**(foo=...)
-> //my_pkg:rule.bzl%**a1**(bar=...)]
...
這表示動作 X 是由套用至 a1(t0) 的面向 a2 產生，其中 a1(t0) 是套用至目標 t0 的面向 a1 的結果。
每個 AspectDescriptor 都有以下格式：
AspectClass([param=value,...])
AspectClass 可以是 Aspect 類別的名稱 (用於原生切面)，或
bzl_file%aspect_name (適用於 Starlark 切面)。AspectDescriptor 會依依附元件圖的拓樸順序排序。
與 JSON 設定檔建立連結
雖然 aquery 會提供在建構中執行的動作相關資訊 (執行原因、輸入/輸出)，但 JSON 設定檔會告知執行時間和執行時間長度。您可以透過動作的主要輸出，來結合這 2 組資訊。
如何納入動作JSON 設定檔輸出內容並產生設定檔
--experimental_include_primary_output --noexperimental_slim_json_profile。
精簡設定檔不相容於包含主要輸出內容的情況。動作的主要輸出內容
都包含在內
我們目前並未提供標準工具，無法合併這 2 個資料來源，但你可以 使用上述資訊建立您自己的指令碼。
已知問題
處理共用動作
有時候，動作會 共用 也不必面對設定的目標
在執行階段，系統會簡單地將這些共用動作視為單一動作，並只執行一次。不過，aquery 會針對執行前、分析後的動作圖表運作，因此會將這些動作視為個別動作，且輸出成果的構件具有完全相同的 execPath。因此，等效的構件會顯示為重複。
如需查詢問題/預定功能清單，請前往 GitHub。
常見問題
即使輸入檔案的內容有所變更，ActionKey 仍然不變。
在查詢中，ActionKey 是指從來源取得的 String
ActionAnalysisMetadata#getKey:
Returns a string encoding all of the significant behaviour of this Action that might affect the
output. The general contract of `getKey` is this: if the work to be performed by the
execution of this action changes, the key must change.
...
Examples of changes that should affect the key are:
- Changes to the BUILD file that materially affect the rule which gave rise to this Action.
- Changes to the command-line options, environment, or other global configuration resources
which affect the behaviour of this kind of Action (other than changes to the names of the
input/output files, which are handled externally).
- An upgrade to the build tools which changes the program logic of this kind of Action
(typically this is achieved by incorporating a UUID into the key, which is changed each
time the program logic of this action changes).
Note the following exception: for actions that discover inputs, the key must change if any
input names change or else action validation may falsely validate.
這不包括變更輸入檔案的內容，請勿混淆 RemoteCacheClient#ActionKey.
更新
如有任何問題或功能要求，請按這裡回報問題。