หน้านี้ครอบคลุมวิธีสร้างกฎของที่เก็บและมีตัวอย่างสำหรับรายละเอียดเพิ่มเติม
ที่เก็บภายนอกเป็นกฎที่ใช้ได้เฉพาะในไฟล์ WORKSPACE
เท่านั้น และเปิดใช้การดำเนินการที่ไม่ต่อเนื่องในขั้นตอนการโหลดของ Bazel กฎที่เก็บภายนอกแต่ละกฎจะสร้างพื้นที่ทำงานของตัวเอง โดยมีไฟล์และอาร์ติแฟกต์ BUILD
ของตัวเอง โดยอาจใช้เพื่ออ้างอิงไลบรารีของบุคคลที่สาม (เช่น ไลบรารีแพ็กเกจของ Maven) และเพื่อสร้างไฟล์ BUILD
สำหรับโฮสต์ Bazel ที่กำลังใช้งานโดยเฉพาะได้ด้วย
การสร้างกฎที่เก็บ
ในไฟล์ .bzl
ให้ใช้ฟังก์ชัน repository_rule เพื่อสร้างกฎที่เก็บใหม่และจัดเก็บไว้ในตัวแปรร่วม
คุณใช้กฎที่เก็บที่กำหนดเองได้เช่นเดียวกับกฎที่เก็บเนทีฟ โดยมีแอตทริบิวต์ name
ที่จำเป็นและทุกเป้าหมายที่แสดงในไฟล์บิลด์อาจเรียกว่า @<name>//package:target
โดยที่ <name>
คือค่าของแอตทริบิวต์ name
ระบบจะโหลดกฎเมื่อคุณสร้างเองอย่างชัดแจ้ง หรือกฎเป็นการอ้างอิงของบิลด์ ในกรณีนี้ Bazel จะเรียกใช้ฟังก์ชัน implementation
ฟังก์ชันนี้อธิบายวิธีสร้างที่เก็บ เนื้อหา และไฟล์ BUILD
Attributes
แอตทริบิวต์คืออาร์กิวเมนต์ของกฎที่ส่งผ่านเป็นคำสั่งไปยังอาร์กิวเมนต์ของกฎ attrs
ระบบจะกำหนดแอตทริบิวต์และประเภทแอตทริบิวต์เมื่อคุณกำหนดกฎที่เก็บ ตัวอย่างการกำหนดแอตทริบิวต์ url
และ sha256
เป็นสตริง
local_repository = repository_rule(
implementation=_impl,
local=True,
attrs={
"url": attr.string(mandatory=True)
"sha256": attr.string(mandatory=True)
}
)
หากต้องการเข้าถึงแอตทริบิวต์ภายในฟังก์ชันการใช้งาน ให้ใช้ repository_ctx.attr.<attribute_name>
ดังนี้
def _impl(repository_ctx):
url = repository_ctx.attr.url
checksum = repository_ctx.attr.sha256
repository_rule
ทั้งหมดมีแอตทริบิวต์ที่กำหนดไว้โดยปริยาย (เช่นเดียวกับกฎบิลด์) แอตทริบิวต์โดยนัย 2 รายการคือ name
(เหมือนกับกฎการสร้าง) และ repo_mapping
ชื่อของกฎที่เก็บจะเข้าถึงได้ด้วย repository_ctx.name
repo_mapping
มีความหมายเหมือนกับกฎที่เก็บเนทีฟ local_repository
และ new_local_repository
หากชื่อแอตทริบิวต์เริ่มต้นด้วย _
จะเป็นแบบส่วนตัวและผู้ใช้ไม่สามารถตั้งค่าได้
ฟังก์ชันการใช้งาน
กฎที่เก็บทั้งหมดต้องมีฟังก์ชัน implementation
ซึ่งมีตรรกะที่แท้จริงของกฎ และจะดำเนินการในขั้นตอนการโหลดเท่านั้น
ฟังก์ชันดังกล่าวมีพารามิเตอร์อินพุต 1 รายการเท่านั้น คือ repository_ctx
ฟังก์ชันจะแสดงผล None
เพื่อแสดงว่ากฎนั้นจำลองซ้ำได้เมื่อมีพารามิเตอร์ที่ระบุ หรือคำสั่งที่มีชุดพารามิเตอร์สำหรับกฎนั้นซึ่งจะเปลี่ยนกฎนั้นให้เป็นกฎที่จำลองซ้ำได้ซึ่งสร้างที่เก็บเดียวกัน ตัวอย่างเช่น สำหรับกฎที่ติดตามที่เก็บ Git ที่จะหมายถึงการแสดงผลตัวระบุคอมมิตที่เจาะจงแทนการแสดง Branch แบบลอยซึ่งระบุไว้ตั้งแต่แรก
พารามิเตอร์อินพุต repository_ctx
ใช้เพื่อเข้าถึงค่าแอตทริบิวต์และฟังก์ชันที่ไม่ใช่แบบผลัดเซลล์ได้ (ค้นหาไบนารี เรียกใช้ไบนารี สร้างไฟล์ในที่เก็บ หรือการดาวน์โหลดไฟล์จากอินเทอร์เน็ต) โปรดดูบริบทเพิ่มเติมในไลบรารี ตัวอย่าง
def _impl(repository_ctx):
repository_ctx.symlink(repository_ctx.attr.path, "")
local_repository = repository_rule(
implementation=_impl,
...)
ฟังก์ชันการติดตั้งใช้งานจะดำเนินการเมื่อใด
ฟังก์ชันการใช้งานของที่เก็บจะทำงานเมื่อ Bazel ต้องการเป้าหมายจากที่เก็บนั้น เช่น เมื่อเป้าหมายอื่น (ในที่เก็บอื่น) ขึ้นอยู่กับเป้าหมายดังกล่าวหรือมีการกล่าวถึงในบรรทัดคำสั่ง จากนั้นคาดหวังว่าฟังก์ชันการใช้งานจะสร้างที่เก็บในระบบไฟล์ ซึ่งเรียกว่า "การดึงข้อมูล" ที่เก็บ
ที่เก็บซึ่งแตกต่างจากเป้าหมายทั่วไป ไม่จำเป็นว่าต้องมีการดึงข้อมูลซ้ำเมื่อมีการเปลี่ยนแปลงบางอย่างที่จะทำให้ที่เก็บแตกต่างกัน เนื่องจากมีบางสิ่งที่ Bazel ไม่สามารถตรวจจับการเปลี่ยนแปลงได้ หรืออาจทำให้มีค่าใช้จ่ายมากเกินไปในทุกบิลด์ (เช่น สิ่งที่ดึงข้อมูลจากเครือข่าย) ดังนั้น ระบบจะดึงข้อมูลที่เก็บอีกครั้งเมื่อมีการเปลี่ยนแปลงอย่างใดอย่างหนึ่งต่อไปนี้
- พารามิเตอร์ที่ส่งไปยังการประกาศของที่เก็บในไฟล์
WORKSPACE
- โค้ด Starlark ประกอบด้วยการติดตั้งใช้งานที่เก็บ
- ค่าของตัวแปรสภาพแวดล้อมที่ประกาศด้วยแอตทริบิวต์
environ
ของrepository_rule
ค่าของตัวแปรสภาพแวดล้อมเหล่านี้สามารถเชื่อมต่อโดยตรงบนบรรทัดคำสั่งที่มีแฟล็ก--action_env
ได้ (แต่แฟล็กนี้จะทำให้การดำเนินการทั้งหมดของบิลด์ไม่ถูกต้อง) - เนื้อหาของไฟล์ที่ส่งไปยัง
read()
,execute()
และวิธีการที่คล้ายกันของrepository_ctx
ซึ่งอ้างถึงโดยป้ายกำกับ (เช่น//mypkg:label.txt
แต่ไม่ใช่mypkg/label.txt
) - เมื่อมีการเรียกใช้
bazel sync
มีพารามิเตอร์ 2 ตัวของ repository_rule
ที่ควบคุมเมื่อดึงข้อมูลที่เก็บอีกครั้ง ดังนี้
- หากตั้งค่าแฟล็ก
configure
ระบบจะดึงข้อมูลที่เก็บอีกครั้งในbazel sync
ก็ต่อเมื่อมีการส่งพารามิเตอร์--configure
ไปยังที่เก็บ (หากไม่ได้ตั้งค่าแอตทริบิวต์ คำสั่งนี้จะไม่ทำให้เกิดการดึงข้อมูลใหม่) หากมีการตั้งค่าแฟล็ก
local
นอกเหนือจากกรณีข้างต้นแล้ว ระบบจะดึงข้อมูลของที่เก็บอีกครั้งเมื่อเซิร์ฟเวอร์ Bazel รีสตาร์ท หรือเมื่อไฟล์ที่ส่งผลต่อการประกาศการเปลี่ยนแปลงของที่เก็บ (เช่น ไฟล์WORKSPACE
หรือไฟล์ที่โหลด) ไม่ว่าการเปลี่ยนแปลงดังกล่าวจะส่งผลให้เกิดการเปลี่ยนแปลงการประกาศที่เก็บหรือโค้ดของที่เก็บหรือไม่ก็ตามในกรณีเช่นนี้จะไม่มีการดึงข้อมูลที่เก็บที่ไม่ได้อยู่ในเครื่องอีกครั้ง ทั้งนี้เพราะที่เก็บเหล่านี้ถือว่าใช้เพื่อสื่อสารกับเครือข่ายหรือมีราคาแพง
รีสตาร์ทฟังก์ชันการใช้งาน
คุณเริ่มฟังก์ชันการใช้งานใหม่ได้ในขณะที่ระบบกำลังดึงข้อมูลที่เก็บหากทรัพยากร Dependency ไม่มีทรัพยากร Dependency ในกรณีนี้ การดำเนินการของฟังก์ชันการใช้งานจะหยุดทำงาน ทรัพยากร Dependency ที่ขาดหายไปจะได้รับการแก้ไข และฟังก์ชันจะทำงานอีกครั้งหลังจากแก้ปัญหาทรัพยากร Dependency แล้ว เพื่อหลีกเลี่ยงการรีสตาร์ทที่ไม่จำเป็น (ซึ่งมีค่าใช้จ่ายสูงเนื่องจากอาจต้องใช้การเข้าถึงเครือข่ายซ้ำๆ) ระบบจะดึงข้อมูลอาร์กิวเมนต์ป้ายกำกับล่วงหน้าในกรณีที่ระบบจะแก้ไขอาร์กิวเมนต์ป้ายกำกับทั้งหมดในไฟล์ที่มีอยู่ได้ โปรดทราบว่าการแก้ไขเส้นทางจากสตริงหรือป้ายกำกับที่สร้างขึ้นระหว่างการดำเนินการฟังก์ชันเท่านั้นอาจทำให้ต้องรีสตาร์ท
การบังคับให้ดึงข้อมูลที่เก็บภายนอกอีกครั้ง
บางครั้งที่เก็บภายนอกอาจล้าสมัยโดยไม่มีการเปลี่ยนแปลงใดๆ กับคำจำกัดความหรือทรัพยากร Dependency เช่น แหล่งที่มาการดึงข้อมูลที่เก็บอาจเป็นไปตามสาขาเฉพาะของที่เก็บของบุคคลที่สาม และคอมมิตใหม่จะมีอยู่ใน Branch นั้น ในกรณีนี้ คุณสามารถขอให้ Bazel ดึงข้อมูลที่เก็บภายนอกทั้งหมดอีกครั้งโดยไม่มีเงื่อนไขโดยเรียกใช้ bazel sync
นอกจากนี้ กฎบางข้อจะตรวจสอบเครื่องภายในและอาจล้าสมัยหากมีการอัปเกรดเครื่องภายใน ในส่วนนี้ คุณจะขอให้ Bazel ดึงข้อมูลเฉพาะที่เก็บภายนอกเหล่านั้นอีกครั้งได้ก็ต่อเมื่อคำจำกัดความ repository_rule
ตั้งค่าแอตทริบิวต์ configure
แล้ว ให้ใช้ bazel sync --configure
ตัวอย่าง
เครื่องมือ C++ ที่กำหนดค่าโดยอัตโนมัติ: ใช้กฎที่เก็บเพื่อสร้างไฟล์การกำหนดค่า C++ สำหรับ Bazel โดยอัตโนมัติ โดยมองหาคอมไพเลอร์ C++ ในเครื่อง สภาพแวดล้อม และแฟล็กที่คอมไพเลอร์ C++ รองรับ
ที่เก็บ Go ใช้
repository_rule
หลายรายการเพื่อกำหนดรายการทรัพยากร Dependency ที่จำเป็นสำหรับการใช้กฎ Gorules_jvm_external จะสร้างที่เก็บภายนอกชื่อ
@maven
โดยค่าเริ่มต้น เพื่อสร้างเป้าหมายบิวด์สำหรับอาร์ติแฟกต์ Maven ทั้งหมดในทรี Dependency แบบสลับ