หน้านี้จะกล่าวถึงวิธีสร้างกฎของที่เก็บและแสดงตัวอย่างเพื่อดูรายละเอียดเพิ่มเติม
ที่เก็บข้อมูลภายนอกคือกฎที่ใช้ได้เฉพาะในไฟล์ WORKSPACE
และเปิดใช้การดำเนินการแบบไม่ปิดผนึกในระยะการโหลดของ Bazel กฎที่เก็บภายนอกแต่ละกฎจะสร้างพื้นที่ทำงานของตนเอง โดยมีไฟล์ BUILD
และอาร์ติแฟกต์ของตนเอง สามารถใช้เพื่อใช้ไลบรารีของบุคคลที่สาม (เช่น ไลบรารีที่แพ็กเกจ Maven) และยังใช้สร้างไฟล์ BUILD
สำหรับโฮสต์ที่ Bazel ทำงานอยู่โดยเฉพาะได้ด้วย
การสร้างกฎที่เก็บ
ในไฟล์ .bzl
ให้ใช้ฟังก์ชัน repository_rule เพื่อสร้างกฎใหม่ของที่เก็บข้อมูลและจัดเก็บไว้ในตัวแปรส่วนกลาง
คุณใช้กฎที่เก็บข้อมูลที่กำหนดเองได้เช่นเดียวกับกฎที่เก็บข้อมูลแบบเนทีฟ ไฟล์ดังกล่าวมีแอตทริบิวต์ name
ที่ต้องระบุ และเป้าหมายทั้งหมดที่อยู่ในไฟล์บิลด์จะอ้างอิงเป็น @<name>//package:target
โดยที่ <name>
คือค่าของแอตทริบิวต์ name
กฎจะโหลดเมื่อคุณสร้างอย่างชัดแจ้งหรือหากเป็นทรัพยากร Dependency ของบิลด์ ในกรณีนี้ 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
ซึ่งประกอบด้วยตรรกะที่แท้จริงของกฎ และจะดำเนินการในขั้นตอนการโหลดอย่างเคร่งครัด
ฟังก์ชันมีพารามิเตอร์อินพุต repository_ctx
เพียง 1 รายการ ฟังก์ชันนี้จะแสดงผล None
เพื่อบ่งบอกว่ากฎทำซ้ำได้เมื่อมีพารามิเตอร์ที่ระบุ หรือคำสั่งที่มีชุดพารามิเตอร์สำหรับกฎนั้นจะเปลี่ยนกฎดังกล่าวให้กลายเป็นที่เก็บเดียวกันซึ่งทำซ้ำได้ เช่น สําหรับกฎที่ติดตามที่เก็บ Git ผลลัพธ์ที่ได้คือตัวระบุการคอมมิตที่เฉพาะเจาะจงแทนสาขาลอยที่ระบุไว้ตั้งแต่แรก
พารามิเตอร์อินพุต 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
ค่าของตัวแปรสภาพแวดล้อมเหล่านี้สามารถกำหนดค่าไว้ล่วงหน้าในบรรทัดคำสั่งด้วย Flag--action_env
(แต่ Flag นี้จะทําให้การดำเนินการทั้งหมดของบิลด์เป็นโมฆะ) - เนื้อหาของไฟล์ที่ส่งไปยัง
read()
,execute()
และเมธอดที่คล้ายกันของrepository_ctx
ซึ่งอ้างอิงโดยป้ายกำกับ (เช่น//mypkg:label.txt
แต่ไม่ใช่mypkg/label.txt
) - เมื่อมีการเรียกใช้
bazel sync
repository_rule
มี 2 พารามิเตอร์ที่ควบคุมเวลาในการดึงข้อมูลพื้นที่เก็บข้อมูลอีกครั้ง ดังนี้
- หากตั้งค่า Flag
configure
ระบบจะดึงข้อมูลรีพอสิทอีกครั้งในbazel sync
เฉพาะเมื่อมีการส่งพารามิเตอร์--configure
ไปยังรีพอสิทเท่านั้น (หากไม่ได้ตั้งค่าแอตทริบิวต์ไว้ คำสั่งนี้จะไม่ทําให้ดึงข้อมูลอีกครั้ง) หากตั้งค่าแฟล็ก
local
นอกเหนือจากกรณีข้างต้น ระบบจะดึงข้อมูลที่เก็บอีกครั้งเมื่อเซิร์ฟเวอร์ Bazel รีสตาร์ท หรือเมื่อไฟล์ที่ส่งผลต่อการประกาศการเปลี่ยนแปลงที่เก็บ (เช่น ไฟล์WORKSPACE
หรือไฟล์ที่โหลดขึ้น) ไม่ว่าการเปลี่ยนแปลงจะส่งผลให้เกิดการเปลี่ยนแปลงการประกาศที่เก็บหรือโค้ดหรือไม่ระบบจะไม่ดึงข้อมูลรีโพซิทอรีที่ไม่ใช่ในเครื่องอีกครั้งในกรณีเหล่านี้ เนื่องจากระบบถือว่าที่เก็บเหล่านี้เชื่อมต่อกับเครือข่ายหรือมีต้นทุนสูง
กำลังรีสตาร์ทฟังก์ชันการใช้งาน
คุณเริ่มต้นฟังก์ชันการติดตั้งใช้งานใหม่ในขณะที่ระบบกำลังดึงข้อมูลที่เก็บ หากไม่มีทรัพยากร Dependency ที่ขอ ในกรณีนี้ การดำเนินการของฟังก์ชันการติดตั้งใช้งานจะหยุดลง ระบบจะแก้ไข Dependency ที่ขาดหายไป และระบบจะเรียกใช้ฟังก์ชันอีกครั้งหลังจากที่แก้ไข Dependency แล้ว เพื่อหลีกเลี่ยงการรีสตาร์ทที่ไม่จำเป็น (ซึ่งมีค่าใช้จ่ายสูง เนื่องจากอาจต้องทำซ้ำการเข้าถึงเครือข่าย) ระบบจะดึงข้อมูลอาร์กิวเมนต์ป้ายกำกับล่วงหน้า โดยหากฟังก์ชันดังกล่าวสามารถแก้ไขอาร์กิวเมนต์ป้ายกำกับทั้งหมดในไฟล์ที่มีอยู่ได้ โปรดทราบว่าการแก้ไขเส้นทางจากสตริงหรือป้ายกำกับที่สร้างในระหว่างการเรียกใช้ฟังก์ชันเท่านั้นอาจยังคงทําให้ระบบรีสตาร์ท
การบังคับให้ดึงข้อมูลที่เก็บข้อมูลภายนอกอีกครั้ง
บางครั้งที่เก็บข้อมูลภายนอกอาจล้าสมัยโดยที่ไม่มีการแก้ไขคำจำกัดความหรือข้อกำหนดที่เกี่ยวข้อง ตัวอย่างเช่น แหล่งที่มาของการดึงข้อมูลที่เก็บอาจติดตาม Branch เฉพาะของที่เก็บของบุคคลที่สาม และคอมมิตใหม่จะใช้ได้ใน Branch ดังกล่าว ในกรณีนี้ คุณขอให้ bazel ดึงข้อมูลที่เก็บภายนอกทั้งหมดอีกครั้งอย่างไม่มีเงื่อนไขได้โดยโทรหา bazel sync
นอกจากนี้ กฎบางข้อจะตรวจสอบเครื่องภายในและอาจล้าสมัยหากมีการอัปเกรดเครื่อง ในส่วนนี้ คุณสามารถขอให้ Bazel ดึงข้อมูลรีโพซิทอรี่ภายนอกเหล่านั้นอีกครั้งเฉพาะในกรณีที่คำจำกัดความ repository_rule
มีการตั้งค่าแอตทริบิวต์ configure
ให้ใช้ bazel sync --configure
ตัวอย่าง
เครื่องมือทางเทคนิคที่กําหนดค่า C++ โดยอัตโนมัติ: ใช้กฎที่เก็บเพื่อสร้างไฟล์การกําหนดค่า C++ สําหรับ Bazel โดยอัตโนมัติโดยมองหาคอมไพเลอร์ C++ ในพื้นที่ สภาพแวดล้อม และ Flag ที่คอมไพเลอร์ C++ รองรับ
ที่เก็บ Go ใช้
repository_rule
หลายรายการในการกำหนดรายการทรัพยากร Dependency ที่ต้องใช้กฎ Gorules_jvm_external สร้างที่เก็บภายนอกที่ชื่อ
@maven
โดยค่าเริ่มต้น ที่สร้างเป้าหมายบิลด์สำหรับอาร์ติแฟกต์ Maven ทุกรายการในทรีดีพึ่งทรานซิทีฟ