動作圖查詢 (查詢)

7.3 · 7.2 · 7.1 · 7.0 · 6.5

aquery 指令可讓您查詢建構圖中的動作。這項工具會針對已完成分析的設定目標圖表運作,並揭露有關動作、構件和它們之間的關係的資訊。

當您對設定的目標圖表產生的動作/構件屬性感興趣時,aquery 就非常實用。例如,實際執行的指令及其輸入/輸出/助憶法。

這項工具接受多種指令列選項。值得注意的是,aquery 指令會在一般 Bazel 建構作業上執行,並繼承建構期間可用的選項組合。

它支援傳統 query 可用的函式,但 siblingsbuildfilestests 則不支援。

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_function(...):專屬於 aquery 的函式。詳情請參閱下方說明。
  • function(...):標準函式,如同傳統 query
  • //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 函式:

  • inputs:依輸入內容篩選動作。
  • outputs:按照輸出內容篩選動作
  • mnemonic:依記憶法篩選動作

expr ::= inputs(word, expr)

inputs 運算子會傳回建構 expr 時產生的動作,其輸入檔案名稱會與 word 提供的規則運算式相符。

$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'

outputsmnemonic 函式的語法很類似。

您也可以結合函式來執行 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 建構作業上執行,因此沿用建構期間可用的選項組合。

查詢選項

--output=(text|summary|proto|jsonproto|textproto), default=text

預設輸出格式 (text) 是人類可讀的格式,請使用 prototextprotojsonproto 來提供機器可讀的格式。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 動作的資訊清單檔案內容。系統會在 file_contents 欄位中傳回檔案內容,並在欄位內加上 --output=xxxproto。使用 --output=text 時,輸出內容會包含 FileWriteContents: [<base64-encoded file contents>]

--skyframe_state, default=false

在不執行額外分析的情況下,從 Skyframe 轉儲動作圖。

其他工具和功能

針對 Skyframe 狀態執行查詢

Skyframe 是 Bazel 的評估與漸進式模型。在 Bazel 伺服器的每個執行個體上,SkyFrame 會儲存之前透過分析階段執行時建構的依附元件圖。

在某些情況下,在 Skyframe 上查詢動作圖表會很有幫助。應用情境範例如下:

  1. 執行 bazel build //target_a
  2. 執行 bazel build //target_b
  3. 已產生檔案「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_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

上述指令會傳回 beforeafter 查詢輸出內容之間的差異:哪些動作存在,但其他動作在每項查詢輸出內容中會有不同的指令列/輸入內容。...執行上述指令的結果如下所示:

  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:要比較的查詢輸出檔案

--input_type=(proto|text_proto), default=proto:輸入檔案格式。系統會支援 prototextproto 查詢輸出內容。

--attrs=(cmdline|inputs), default=cmdline:要比較的動作屬性。

切面上的切面

切面可以相互套用。這些 Aspects 產生的動作查詢輸出會包含「Aspect path」,也就是產生動作的目標所套用的切面序列。

以下是「相對於相對於」的範例:

  t0
  ^
  | <- a1
  t1
  ^
  | <- a2
  t2

讓 ti 成為規則 ri 的目標,該規則會將特徵 ai 套用至其依附元件。

假設套用目標 t0 時 a2 產生動作 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 類別的名稱 (針對原生 Aspect) 或 bzl_file%aspect_name (針對 Starlark Aspect)。AspectDescriptor 是按照依附元件圖表的頂端順序排序。

連結 JSON 設定檔

查詢可以提供有關建構中執行動作的資訊 (包括執行的原因、輸入/輸出內容),但 JSON 設定檔會提供執行作業的時間和持續時間。您可以透過共同分母 (動作的主要輸出內容) 結合這兩組資訊。

如要在 JSON 設定檔中加入動作的輸出內容,請使用 --experimental_include_primary_output --noexperimental_slim_json_profile 產生設定檔。精簡設定檔與主要輸出內容不相容。根據預設,aquery 會納入動作的主要輸出內容。

我們目前沒有結合這 2 個資料來源的標準工具,但您應能夠使用上述資訊自行建構指令碼。

已知問題

處理共用動作

有時動作會在設定的目標之間共用

在執行階段中,這些共用動作只會視為一個動作,且只會執行一次。不過,查詢會在執行前的分析後動作圖表上運作,因此會將這些動作視為輸出 Artifact 具有相同 execPath 的個別動作。因此,等效的構件會顯示為重複。

如需查詢問題/預定功能清單,請前往 GitHub

常見問題

即使輸入檔案的內容有所變更,ActionKey 仍然不變。

在查詢中,ActionKey 是指從 ActionAnalysisMetadata#getKey 取得的 String

  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 混淆。

更新

如有任何問題或功能要求,請按這裡回報問題。