ดูข้อกําหนดทั้งหมดของ Build Event Protocol ได้ในคําจํากัดความของบัฟเฟอร์โปรโตคอล อย่างไรก็ตาม คุณอาจต้องลองใช้ก่อนดูข้อมูลจำเพาะ
ลองพิจารณาพื้นที่ทํางาน Bazel แบบง่ายที่มีสคริปต์เชลล์เปล่า 2 รายการ นั่นคือ foo.sh และ foo_test.sh รวมถึงไฟล์ BUILD ต่อไปนี้
sh_library(
name = "foo_lib",
srcs = ["foo.sh"],
)
sh_test(
name = "foo_test",
srcs = ["foo_test.sh"],
deps = [":foo_lib"],
)
เมื่อเรียกใช้ bazel test ... ในโปรเจ็กต์นี้ กราฟบิลด์ของเหตุการณ์บิลด์ที่สร้างขึ้นจะคล้ายกับกราฟด้านล่าง รูปลูกศรแสดงความสัมพันธ์หลักและย่อยที่กล่าวถึงข้างต้น โปรดทราบว่าเราได้ละเว้นเหตุการณ์การสร้างและฟิลด์ส่วนใหญ่ไว้เพื่อไม่ให้เนื้อหายาวเกินไป
รูปที่ 1 กราฟ BEP
ระบบจะเผยแพร่เหตุการณ์ BuildStarted รายการแรก เหตุการณ์นี้แจ้งให้เราทราบว่ามีการเรียกใช้บิลด์ผ่านคําสั่ง bazel test และประกาศเหตุการณ์ย่อย
OptionsParsedWorkspaceStatusCommandLineUnstructuredCommandLineBuildMetadataBuildFinishedPatternExpandedProgress
เหตุการณ์ 3 รายการแรกให้ข้อมูลเกี่ยวกับวิธีเรียกใช้ Bazel
เหตุการณ์การสร้าง PatternExpanded ให้ข้อมูลเชิงลึกเกี่ยวกับเป้าหมายที่เฉพาะเจาะจงซึ่งรูปแบบ ... ขยายไปถึง //foo:foo_lib และ //foo:foo_test โดยประกาศเหตุการณ์ TargetConfigured 2 รายการเป็นเหตุการณ์ย่อย โปรดทราบว่าเหตุการณ์ TargetConfigured ประกาศเหตุการณ์ Configuration เป็นเหตุการณ์ย่อย แม้ว่าจะมีการโพสต์ Configuration ก่อนเหตุการณ์ TargetConfigured
นอกจากความสัมพันธ์แบบพ่อแม่และลูกแล้ว เหตุการณ์ยังอาจอ้างอิงถึงกันโดยใช้ตัวระบุเหตุการณ์การสร้าง เช่น ในกราฟด้านบน เหตุการณ์ TargetComplete หมายถึงเหตุการณ์ NamedSetOfFiles ในช่อง fileSets
โดยปกติการสร้างเหตุการณ์ที่อ้างถึงไฟล์จะไม่ฝังชื่อไฟล์และเส้นทางในเหตุการณ์ แต่จะมีตัวระบุเหตุการณ์การสร้างของเหตุการณ์ NamedSetOfFiles ซึ่งจะมีชื่อและเส้นทางไฟล์จริง เหตุการณ์ NamedSetOfFiles ช่วยให้รายงานชุดไฟล์ได้เพียงครั้งเดียวและมีการอ้างอิงโดยเป้าหมายหลายรายการ โครงสร้างนี้มีความจําเป็น เนื่องจากในบางกรณี ขนาดเอาต์พุตของโปรโตคอลกิจกรรมบิลด์จะเพิ่มขึ้นตามจํานวนไฟล์ เหตุการณ์ NamedSetOfFiles อาจไม่ได้ฝังไฟล์ทั้งหมด แต่อ้างอิงเหตุการณ์ NamedSetOfFiles อื่นๆ ผ่านตัวระบุเหตุการณ์ของบิลด์แทน
ด้านล่างนี้คืออินสแตนซ์ของเหตุการณ์ TargetComplete สําหรับเป้าหมาย //foo:foo_lib จากกราฟด้านบน ซึ่งแสดงในรูปแบบ JSON ของบัฟเฟอร์โปรโตคอล
ตัวระบุเหตุการณ์การสร้างมีเป้าหมายเป็นสตริงทึบแสงและอ้างอิงเหตุการณ์ Configuration โดยใช้ตัวระบุเหตุการณ์การสร้าง เหตุการณ์จะไม่ประกาศเหตุการณ์ย่อย เพย์โหลดมีข้อมูลว่าเป้าหมายนี้สร้างสำเร็จหรือไม่ ชุดไฟล์เอาต์พุต และประเภทของเป้าหมายที่สร้าง
{
"id": {
"targetCompleted": {
"label": "//foo:foo_lib",
"configuration": {
"id": "544e39a7f0abdb3efdd29d675a48bc6a"
}
}
},
"completed": {
"success": true,
"outputGroup": [{
"name": "default",
"fileSets": [{
"id": "0"
}]
}],
"targetKind": "sh_library rule"
}
}
ผลลัพธ์ Aspect ใน BEP
บิลด์ทั่วไปจะประเมินการดำเนินการที่เชื่อมโยงกับคู่ (target, configuration) เมื่อสร้างโดยเปิดใช้แง่มุม Bazel จะประเมินเป้าหมายที่เชื่อมโยงกับไตรเทต (target, configuration,
aspect) เพิ่มเติมสำหรับแต่ละเป้าหมายที่ได้รับผลกระทบจากแง่มุมที่เปิดใช้
ผลการประเมินสำหรับแง่มุมจะแสดงใน BEP แม้ว่าจะไม่มีประเภทเหตุการณ์ที่เจาะจงแง่มุมก็ตาม สำหรับ (target, configuration) แต่ละคู่ที่มีแง่มุมที่เกี่ยวข้อง Bazel จะเผยแพร่เหตุการณ์ TargetConfigured และ TargetComplete เพิ่มเติมที่แสดงผลลัพธ์จากการใช้ลักษณะดังกล่าวกับเป้าหมาย ตัวอย่างเช่น หาก //:foo_lib สร้างด้วย --aspects=aspects/myaspect.bzl%custom_aspect เหตุการณ์นี้จะปรากฏใน BEP ด้วย
{
"id": {
"targetCompleted": {
"label": "//foo:foo_lib",
"configuration": {
"id": "544e39a7f0abdb3efdd29d675a48bc6a"
},
"aspect": "aspects/myaspect.bzl%custom_aspect"
}
},
"completed": {
"success": true,
"outputGroup": [{
"name": "default",
"fileSets": [{
"id": "1"
}]
}]
}
}
กำลังใช้ NamedSetOfFiles
การกำหนดรายการต่างๆ ที่สร้างขึ้นโดยเป้าหมาย (หรือแง่มุม) หนึ่งๆ เป็น Use Case ทั่วไปของ BEP ที่ทําได้อย่างมีประสิทธิภาพด้วยการเตรียมการบางอย่าง ส่วนนี้กล่าวถึงโครงสร้างที่แชร์แบบซ้ำซ้อนซึ่ง NamedSetOfFiles Event นำเสนอ ซึ่งตรงกับโครงสร้างของ Depset ของ Starlark
ผู้บริโภคต้องระมัดระวังในการหลีกเลี่ยงอัลกอริทึมกำลังสองเมื่อประมวลผลเหตุการณ์ NamedSetOfFiles เนื่องจากบิลด์ขนาดใหญ่อาจมีเหตุการณ์เช่นนี้หลายหมื่นรายการ จึงต้องมีการดำเนินการหลายร้อยล้านแบบในการข้ามผ่านที่มีความซับซ้อนอยู่ในกำลังสอง
รูปที่ 2 กราฟ BEP ของNamedSetOfFiles
เหตุการณ์ NamedSetOfFiles จะปรากฏในสตรีม BEP ก่อนเหตุการณ์ TargetComplete หรือ NamedSetOfFiles ที่อ้างอิงถึงเสมอ ซึ่งตรงข้ามกับความสัมพันธ์ของเหตุการณ์แบบ "หลักกับย่อย" ที่เหตุการณ์ทั้งหมดยกเว้นเหตุการณ์แรกจะปรากฏขึ้นหลังจากเหตุการณ์ที่ประกาศเหตุการณ์นั้นอย่างน้อย 1 รายการ เหตุการณ์ NamedSetOfFiles ได้รับการประกาศโดยเหตุการณ์ Progress ที่ไม่มีความหมาย
เนื่องด้วยข้อจำกัดในการสั่งซื้อและการแชร์เหล่านี้ ผู้บริโภคทั่วไปจึงต้องบัฟเฟอร์เหตุการณ์ NamedSetOfFiles ทั้งหมดจนกว่าสตรีม BEP จะหมดลง สตรีมเหตุการณ์ JSON และโค้ด Python ต่อไปนี้แสดงวิธีป้อนข้อมูลแผนที่จากเป้าหมาย/แง่มุมไปยังอาร์ติแฟกต์ที่สร้างขึ้นในกลุ่มเอาต์พุต "เริ่มต้น" และวิธีประมวลผลเอาต์พุตสําหรับเป้าหมาย/แง่มุมที่สร้างขึ้นบางส่วน
named_sets = {} # type: dict[str, NamedSetOfFiles]
outputs = {} # type: dict[str, dict[str, set[str]]]
for event in stream:
kind = event.id.WhichOneof("id")
if kind == "named_set":
named_sets[event.id.named_set.id] = event.named_set_of_files
elif kind == "target_completed":
tc = event.id.target_completed
target_id = (tc.label, tc.configuration.id, tc.aspect)
outputs[target_id] = {}
for group in event.completed.output_group:
outputs[target_id][group.name] = {fs.id for fs in group.file_sets}
for result_id in relevant_subset(outputs.keys()):
visit = outputs[result_id].get("default", [])
seen_sets = set(visit)
while visit:
set_name = visit.pop()
s = named_sets[set_name]
for f in s.files:
process_file(result_id, f)
for fs in s.file_sets:
if fs.id not in seen_sets:
visit.add(fs.id)
seen_sets.add(fs.id)