การค้นหากราฟการดำเนินการ (Aquery)

คำสั่ง 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_function(...): ฟังก์ชันเฉพาะสำหรับ aquery ดูรายละเอียดเพิ่มเติมได้ด้านล่าง
• function(...): functionsมาตรฐาน 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))'

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

        $ 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) เป็นรูปแบบที่มนุษย์อ่านได้ ใช้ proto, textproto หรือ jsonproto สำหรับรูปแบบที่เครื่องอ่านได้ ข้อความ Proto คือ analysis.ActionGraphContainer

--include_commandline, default=true

รวมเนื้อหาของบรรทัดคำสั่งการดำเนินการไว้ในเอาต์พุต (อาจมีขนาดใหญ่)

--include_artifacts, default=true

รวมชื่ออินพุตและเอาต์พุตการดําเนินการไว้ในเอาต์พุต (อาจมีขนาดใหญ่)

--include_aspects, default=true

ระบุว่าจะรวมการดำเนินการที่เกิดจากแง่มุมไว้ในเอาต์พุตหรือไม่

--include_param_files, default=false

รวมเนื้อหาของไฟล์พารามิเตอร์ที่ใช้ในคําสั่ง (อาจมีขนาดใหญ่)

--include_file_write_contents, default=false

ใส่เนื้อหาไฟล์สําหรับการดําเนินการ actions.write() และเนื้อหาของไฟล์ Manifest สําหรับการดําเนินการ SourceSymlinkManifest ระบบจะแสดงเนื้อหาไฟล์ในช่อง file_contents พร้อม --output=xxxproto เมื่อใช้ --output=text เอาต์พุตจะมี FileWriteContents: [<base64-encoded file contents>] บรรทัด

--skyframe_state, default=false

วางกราฟการกระทําจาก Skyframe โดยไม่ทําการวิเคราะห์เพิ่มเติม

เครื่องมือและฟีเจอร์อื่นๆ

การค้นหาสถานะของ Skyframe

Skyframe คือรูปแบบการประเมินและการเพิ่มของ Bazel ในอินสแตนซ์แต่ละรายการของเซิร์ฟเวอร์ Bazel นั้น Skyframe จะจัดเก็บกราฟความเกี่ยวข้องซึ่งสร้างขึ้นจากการเรียกใช้ระยะการวิเคราะห์ครั้งก่อนหน้า

ในบางกรณี การค้นหากราฟการดำเนินการใน Skyframe จะมีประโยชน์ ตัวอย่าง Use Case มีดังนี้

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คำสั่งหลายรายการเกิดความยุ่งยาก

หรือจะใช้ Flag --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 2 รายการที่แตกต่างกันได้โดยใช้เครื่องมือ aquery_differ เช่น เมื่อคุณทําการเปลี่ยนแปลงคําจํากัดความของกฎและต้องการยืนยันว่าบรรทัดคําสั่งที่กําลังทํางานไม่มีการเปลี่ยนแปลง 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

คำสั่งข้างต้นจะแสดงผลต่างระหว่างเอาต์พุต aquery before กับ after ซึ่งได้แก่ การดำเนินการที่มีอยู่ในรายการหนึ่งแต่ไม่มีในอีกรายการหนึ่ง การดำเนินการที่มีบรรทัดคำสั่ง/อินพุตต่างกันในเอาต์พุต aquery แต่ละรายการ ฯลฯ ผลลัพธ์ของการเรียกใช้คำสั่งข้างต้นจะเป็นดังนี้

  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: รูปแบบของไฟล์อินพุต รองรับเอาต์พุต aquery ของ proto และ textproto

--attrs=(cmdline|inputs), default=cmdline: แอตทริบิวต์ของการดำเนินการที่จะเปรียบเทียบ

การแสดงภาพซ้อนภาพ

แง่มุมอาจวางซ้อนกันได้ เอาต์พุต aquery ของการดำเนินการที่เกิดจากแง่มุมเหล่านี้จะมีเส้นทางแง่มุม ซึ่งเป็นลําดับของแง่มุมที่ใช้กับเป้าหมายซึ่งสร้างการดำเนินการ

ตัวอย่างของการแสดงผลแบบภาพซ้อนภาพ

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

สมมติให้ t_i เป็นเป้าหมายของกฎ r_i ซึ่งใช้แง่มุม a_i กับองค์ประกอบที่เกี่ยวข้อง

สมมติว่า a2 สร้างการดําเนินการ X เมื่อนําไปใช้กับเป้าหมาย t0 เอาต์พุตข้อความของ bazel aquery --include_aspects 'deps(//t2)' สําหรับการดําเนินการ X จะเป็นดังนี้

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

ซึ่งหมายความว่าการดําเนินการ X สร้างขึ้นโดยแง่มุม a2 ที่นําไปใช้กับ a1(t0) โดยที่ a1(t0) เป็นผลลัพธ์ของแง่มุม a1 ที่นําไปใช้กับเป้าหมาย t0

AspectDescriptor แต่ละรายการมีรูปแบบดังนี้

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

AspectClass อาจเป็นชื่อของคลาสแง่มุม (สำหรับแง่มุมแบบเนทีฟ) หรือ bzl_file%aspect_name (สำหรับแง่มุม Starlark) AspectDescriptor จะเรียงตามลําดับเชิงทอพอโลยีของกราฟทรัพยากร Dependency

การลิงก์กับโปรไฟล์ JSON

ขณะที่การค้นหาจะให้ข้อมูลเกี่ยวกับการดําเนินการที่กำลังทํางานในบิลด์ (เหตุผลที่ทํางาน อินพุต/เอาต์พุต) โปรไฟล์ JSON จะบอกเราถึงเวลาและระยะเวลาของการดำเนินการ คุณสามารถรวมข้อมูล 2 ชุดนี้เข้าด้วยกันผ่านตัวหารร่วม ซึ่งเป็นเอาต์พุตหลักของการดําเนินการ

หากต้องการรวมเอาต์พุตของการดำเนินการไว้ในโปรไฟล์ JSON ให้สร้างโปรไฟล์ด้วย --experimental_include_primary_output --noslim_profile โปรไฟล์แบบบางใช้ร่วมกับเอาต์พุตหลักไม่ได้ ผลลัพธ์หลักของการดำเนินการจะรวมอยู่ใน aquery โดยค่าเริ่มต้น

ปัจจุบันเราไม่มีเครื่องมือมาตรฐานในการรวมแหล่งข้อมูล 2 แหล่งนี้ แต่คุณควรสร้างสคริปต์ของคุณเองได้ด้วยข้อมูลข้างต้น

ปัญหาที่ทราบ

การจัดการการดำเนินการที่แชร์

บางครั้งระบบจะแชร์การกระทําระหว่างเป้าหมายที่กําหนดค่าไว้

ในเฟสการดำเนินการ ระบบจะถือว่าการดำเนินการที่แชร์เหล่านั้นเป็นการดำเนินการเดียวกันและจะดำเนินการเพียงครั้งเดียว อย่างไรก็ตาม aquery จะทํางานบนกราฟการดำเนินการก่อนการดําเนินการและหลังการวิเคราะห์ ดังนั้นจึงถือว่าการดำเนินการเหล่านี้เป็นการดำเนินการแยกต่างหากซึ่งมีอาร์ติแฟกต์เอาต์พุตที่มี execPath เหมือนกันทุกประการ ด้วยเหตุนี้ รายการต่างๆ จึงดูเหมือนซ้ำกัน

ดูรายการปัญหา/ฟีเจอร์ที่วางแผนไว้ของ aquery ได้ใน GitHub

คำถามที่พบบ่อย

โดย ActionKey จะยังคงเหมือนเดิมแม้ว่าเนื้อหาของไฟล์อินพุตจะเปลี่ยนแปลงไป

ในบริบทของ aquery 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

อัปเดต

หากมีปัญหา/ต้องการขอฟีเจอร์ใดๆ โปรดแจ้งปัญหาที่นี่