คำสั่ง 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(...)
: ทำงานมาตรฐาน เช่นเดียวกับ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
มี 3 ประเภทดังนี้
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 ปกติ จึงรับชุดตัวเลือกที่ใช้ได้ในระหว่างการบิลด์
ตัวเลือกคำค้นหา
--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 Skyframe ในแต่ละอินสแตนซ์ของเซิร์ฟเวอร์ Bazel จะจัดเก็บกราฟทรัพยากร Dependency ที่สร้างขึ้นจากการเรียกใช้ก่อนหน้าของระยะการวิเคราะห์
ในบางกรณี การค้นหากราฟการดำเนินการใน 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")'
การเปรียบเทียบเอาต์พุตของคําค้นหา
คุณสามารถเปรียบเทียบเอาต์พุตของการเรียกใช้คำค้นหาที่แตกต่างกัน 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
: รูปแบบของไฟล์อินพุต การสนับสนุนสำหรับเอาต์พุตคำค้นหา proto
และ textproto
--attrs=(cmdline|inputs), default=cmdline
: แอตทริบิวต์ของการดำเนินการที่จะเปรียบเทียบ
การแสดงภาพซ้อนภาพ
แง่มุมอาจวางซ้อนกันได้ เอาต์พุต aquery ของการดำเนินการที่เกิดจากแง่มุมเหล่านี้จะมีเส้นทางแง่มุม ซึ่งเป็นลําดับของแง่มุมที่ใช้กับเป้าหมายซึ่งสร้างการดำเนินการ
ตัวอย่างของการแสดงผลแบบภาพซ้อนภาพ
t0 ^ | <- a1 t1 ^ | <- a2 t2
สมมติให้ ti เป็นเป้าหมายของกฎ ri ซึ่งใช้แง่มุม ai กับองค์ประกอบที่เกี่ยวข้อง
สมมติว่า 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
อาจเป็นชื่อของคลาส Aspect (สำหรับ Aspects แบบดั้งเดิม) หรือ bzl_file%aspect_name
(สำหรับ Starlark Aspects) AspectDescriptor
จะเรียงตามลําดับเชิงทอพอโลยีของกราฟทรัพยากร Dependency
การลิงก์กับโปรไฟล์ JSON
ขณะที่คำค้นหาจะให้ข้อมูลเกี่ยวกับการดำเนินการที่ทำงานอยู่ในบิลด์ (สาเหตุที่เรียกใช้ อินพุต/เอาต์พุต) โปรไฟล์ JSON จะบอกเวลาและระยะเวลาในการดำเนินการให้เราทราบ คุณสามารถรวมข้อมูล 2 ชุดนี้เข้าด้วยกันผ่านตัวหารร่วมได้ ซึ่งก็คือเอาต์พุตหลักของการดำเนินการ
หากต้องการรวมเอาต์พุตของการดำเนินการไว้ในโปรไฟล์ JSON ให้สร้างโปรไฟล์ด้วย
--experimental_include_primary_output --noslim_profile
โปรไฟล์แบบสลิมไม่สามารถใช้กับการรวมเอาต์พุตหลัก เอาต์พุตหลักของการดำเนินการจะรวมอยู่โดยค่าเริ่มต้นโดยค่าเริ่มต้น
ปัจจุบันเราไม่มีเครื่องมือมาตรฐานในการรวมแหล่งข้อมูล 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
อัปเดต
หากพบปัญหา/ต้องการขอฟีเจอร์ใดๆ โปรดแจ้งปัญหาที่นี่