Trang này được dịch bởi Cloud Translation API.

Truy vấn biểu đồ hành động (truy vấn)

Lệnh aquery cho phép bạn truy vấn các hành động trong biểu đồ bản dựng. Nó hoạt động trên Biểu đồ mục tiêu đã định cấu hình sau khi phân tích và hiển thị thông tin về Hành động, Cấu phần phần mềm và các mối quan hệ của chúng.

aquery rất hữu ích khi bạn quan tâm đến các thuộc tính của Thao tác/Cấu phần phần mềm được tạo từ Biểu đồ mục tiêu đã định cấu hình. Ví dụ: các lệnh thực tế chạy và đầu vào/đầu ra/bộ nhớ của các lệnh đó.

Công cụ này chấp nhận một số tuỳ chọn dòng lệnh. Đáng chú ý là lệnh aquery chạy trên bản dựng Bazel thông thường và kế thừa tập hợp các tuỳ chọn có sẵn trong quá trình tạo bản dựng.

API này hỗ trợ cùng một nhóm hàm hiện có sẵn cho query truyền thống nhưng siblings, buildfiles và tests.

Ví dụ về kết quả aquery (không có thông tin chi tiết cụ thể):

$ bazel aquery 'deps(//some:label)'
action 'Writing file some_file_name'
  Mnemonic: ...
  Target: ...
  Configuration: ...
  ActionKey: ...
  Inputs: [...]
  Outputs: [...]

Cú pháp cơ bản

Sau đây là ví dụ đơn giản về cú pháp cho aquery:

bazel aquery "aquery_function(function(//target))"

Biểu thức truy vấn (trong dấu ngoặc kép) bao gồm:

aquery_function(...): các hàm dành riêng cho aquery. Hãy xem thêm thông tin chi tiết bên dưới.
function(...): các hàm tiêu chuẩn như query truyền thống.
//target là nhãn cho mục tiêu quan tâm.

# 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))'

Sử dụng các hàm truy vấn

Có 3 hàm aquery:

inputs: lọc các hành động theo dữ liệu đầu vào.
outputs: lọc các hành động theo kết quả
mnemonic: lọc hành động theo ghi nhớ

expr ::= inputs(word, expr)

Toán tử inputs trả về các thao tác được tạo từ bản dựng expr, có tên tệp đầu vào khớp với biểu thức chính quy do word cung cấp.

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

Hàm outputs và mnemonic có cú pháp tương tự nhau.

Bạn cũng có thể kết hợp các hàm để thực hiện phép toán AND. Ví dụ:

  $ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'

Lệnh trên sẽ tìm thấy tất cả các hành động liên quan đến việc tạo //src/target_a, có hệ thống ghi nhớ khớp với "Cpp.*" và dữ liệu đầu vào khớp với các mẫu ".*cpp" và "foo.*".

Ví dụ về lỗi cú pháp gặp phải:

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

Tùy chọn

Tuỳ chọn tạo bản dựng

aquery chạy trên bản dựng Bazel thông thường, do đó kế thừa tập hợp các tuỳ chọn có sẵn trong quá trình tạo bản dựng.

Tùy chọn truy vấn

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

Định dạng đầu ra mặc định (text) là định dạng mà con người có thể đọc được. Hãy sử dụng proto, textproto hoặc jsonproto cho định dạng mà máy có thể đọc được. Thông báo proto là analysis.ActionGraphContainer.

`--include_commandline, default=true`

Bao gồm nội dung của các dòng lệnh hành động trong đầu ra (có thể lớn).

`--include_artifacts, default=true`

Bao gồm tên của các đầu vào và đầu ra hành động ở đầu ra (có thể lớn).

`--include_aspects, default=true`

Liệu có đưa các thao tác do Aspect tạo vào kết quả hay không.

`--include_param_files, default=false`

Bao gồm nội dung của các tệp thông số được dùng trong lệnh (có thể lớn).

`--include_file_write_contents, default=false`

Bao gồm nội dung tệp cho thao tác actions.write() và nội dung của tệp kê khai cho thao tác SourceSymlinkManifest. Nội dung tệp được trả về trong trường file_contents với --output=xxxproto. Với --output=text, kết quả sẽ có dòng FileWriteContents: [<base64-encoded file contents>]

`--skyframe_state, default=false`

Nếu không phân tích thêm, hãy kết xuất Biểu đồ hành động từ Skyframe.

Các công cụ và tính năng khác

Truy vấn dựa trên trạng thái Skyframe

Skyframe là mô hình đánh giá và gia tăng của Bazel. Trên mỗi thực thể của máy chủ Bazel, Skyframe lưu trữ biểu đồ phần phụ thuộc được tạo từ các lần chạy trước của Giai đoạn phân tích.

Trong một số trường hợp, bạn nên truy vấn Biểu đồ hành động trên Skyframe. Ví dụ về trường hợp sử dụng:

Chạy bazel build //target_a
Chạy bazel build //target_b
Đã tạo tệp foo.out.

Là người dùng Bazel, tôi muốn xác định xem foo.out được tạo từ bản dựng //target_a hay //target_b.

Người dùng có thể chạy bazel aquery 'outputs("foo.out", //target_a)' và bazel aquery 'outputs("foo.out", //target_b)' để tìm ra hành động chịu trách nhiệm tạo foo.out và từ đó tìm ra mục tiêu. Tuy nhiên, số lượng mục tiêu khác nhau đã tạo trước đây có thể lớn hơn 2, điều này khiến việc chạy nhiều lệnh aquery trở nên phức tạp.

Thay vào đó, bạn có thể sử dụng cờ --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")'

Với chế độ --skyframe_state, aquery lấy nội dung của Biểu đồ hành động mà Skyframe giữ trên thực thể của Bazel (không bắt buộc) thực hiện việc lọc trên đó và xuất nội dung mà không cần chạy lại giai đoạn phân tích.

Các điểm cần cân nhắc đặc biệt

Định dạng đầu ra

--skyframe_state hiện chỉ dành cho --output=proto và --output=textproto

Không bao gồm nhãn mục tiêu trong biểu thức truy vấn

Hiện tại, --skyframe_state truy vấn toàn bộ biểu đồ hành động tồn tại trên Skyframe, bất kể mục tiêu là gì. Việc chỉ định nhãn mục tiêu trong truy vấn cùng với --skyframe_state sẽ bị coi là lỗi cú pháp:

  # 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")'

So sánh kết quả của một truy vấn

Bạn có thể so sánh kết quả của 2 lệnh gọi aquery khác nhau bằng công cụ aquery_differ. Ví dụ: khi bạn thực hiện một số thay đổi đối với định nghĩa quy tắc và muốn xác minh rằng các dòng lệnh đang chạy không thay đổi. aquery_differ chính là công cụ giúp bạn làm việc đó.

Công cụ này có trong kho lưu trữ bazelbuild/bazel. Để sử dụng, hãy sao chép kho lưu trữ vào máy cục bộ. Ví dụ về cách sử dụng:

  $ bazel run //tools/aquery_differ -- \
  --before=/path/to/before.proto \
  --after=/path/to/after.proto \
  --input_type=proto \
  --attrs=cmdline \
  --attrs=inputs

Lệnh trên trả về sự khác biệt giữa kết quả truy vấn before và after: những hành động nào có trong một mà không phải là hành động khác, hành động nào có dòng lệnh/đầu vào khác nhau trong mỗi đầu ra của truy vấn, ...). Kết quả chạy lệnh trên sẽ là:

  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/
    ...

Tuỳ chọn lệnh

--before, --after: Các tệp đầu ra của truy vấn cần so sánh

--input_type=(proto|text_proto), default=proto: định dạng của tệp đầu vào. Hỗ trợ đầu ra truy vấn proto và textproto.

--attrs=(cmdline|inputs), default=cmdline: các thuộc tính của các hành động cần so sánh.

Góc nhìn

Có thể áp dụng các Khung hình chồng lên nhau. Khi đó, kết quả truy vấn của thao tác do các Aspect này tạo ra sẽ bao gồm Đường dẫn Aspect. Đây là trình tự của các Aspect được áp dụng cho mục tiêu đã tạo ra thao tác.

Ví dụ về chế độ Aspect-on-Aspect:

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

Đặt t_i là mục tiêu của quy tắc r_i, quy tắc này sẽ áp dụng một Aspect a_i cho các phần phụ thuộc.

Giả sử rằng a2 tạo ra một hành động X khi được áp dụng cho mục tiêu t0. Đầu ra văn bản của bazel aquery --include_aspects 'deps(//t2)' cho hành động X sẽ là:

  action ...
  Mnemonic: ...
  Target: //my_pkg:t0
  Configuration: ...
  AspectDescriptors: [//my_pkg:rule.bzl%**a2**(foo=...)
    -> //my_pkg:rule.bzl%**a1**(bar=...)]
  ...

Điều này có nghĩa là thao tác X được tạo bởi Aspect a2 được áp dụng trên a1(t0), trong đó a1(t0) là kết quả của Aspect a1 được áp dụng cho t0.

Mỗi AspectDescriptor đều có định dạng sau:

  AspectClass([param=value,...])

AspectClass có thể là tên của lớp Aspect (đối với Aspects gốc) hoặc bzl_file%aspect_name (đối với Starlark Aspect). AspectDescriptor được sắp xếp theo thứ tự cấu trúc liên kết của biểu đồ phần phụ thuộc.

Liên kết với hồ sơ JSON

Mặc dù truy vấn cung cấp thông tin về các hành động đang được chạy trong một bản dựng (lý do các hành động đó được chạy, dữ liệu đầu vào/đầu ra của chúng), nhưng hồ sơ JSON sẽ cho chúng ta biết thời gian và thời lượng thực thi các hành động đó. Có thể kết hợp 2 tập thông tin này thông qua một mẫu số chung: đầu ra chính của một hành động.

Để đưa kết quả của các thao tác vào hồ sơ JSON, hãy tạo hồ sơ bằng --experimental_include_primary_output --noexperimental_slim_json_profile. Hồ sơ mỏng không tương thích với việc thêm dữ liệu đầu ra chính. Theo mặc định, một truy vấn sẽ đưa vào đầu ra chính của một hành động.

Chúng tôi hiện không cung cấp công cụ chuẩn hoá để kết hợp 2 nguồn dữ liệu này, nhưng bạn có thể xây dựng tập lệnh của riêng mình với thông tin trên.

Vấn đề đã biết

Xử lý hành động được chia sẻ

Đôi khi, các thao tác được chia sẻ giữa các mục tiêu đã định cấu hình.

Trong giai đoạn thực thi, những hành động chung đó chỉ được coi là một và chỉ được thực thi một lần. Tuy nhiên, truy vấn hoạt động trên biểu đồ hành động trước khi thực thi và sau khi phân tích. Do đó, truy vấn này sẽ coi các hành động này giống như những hành động riêng biệt mà Cấu phần phần mềm đầu ra có cùng execPath. Do đó, các Cấu phần phần mềm tương đương sẽ bị trùng lặp.

Bạn có thể tìm thấy danh sách các vấn đề về truy vấn/tính năng theo kế hoạch trên GitHub.

Câu hỏi thường gặp

ActionKey vẫn giữ nguyên ngay cả khi nội dung của tệp nhập đã thay đổi.

Trong ngữ cảnh của truy vấn, ActionKey đề cập đến String nhận được từ 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.

Thao tác này sẽ loại trừ các thay đổi đối với nội dung của tệp đầu vào và bạn không nên nhầm lẫn với RemoteCacheClient#ActionKey.

Bản cập nhật

Nếu bạn có vấn đề/yêu cầu về tính năng, vui lòng báo cáo vấn đề tại đây.