กฎที่เก็บ

หน้านี้ครอบคลุมวิธีสร้างกฎของที่เก็บและมีตัวอย่างสำหรับรายละเอียดเพิ่มเติม

ที่เก็บภายนอกเป็นกฎที่ใช้ได้เฉพาะในไฟล์ WORKSPACE เท่านั้น และเปิดใช้การดำเนินการที่ไม่ต่อเนื่องในขั้นตอนการโหลดของ Bazel กฎที่เก็บภายนอกแต่ละกฎจะสร้างพื้นที่ทำงานของตัวเอง โดยมีไฟล์และอาร์ติแฟกต์ BUILD ของตัวเอง โดยอาจใช้เพื่ออ้างอิงไลบรารีของบุคคลที่สาม (เช่น ไลบรารีแพ็กเกจของ Maven) และเพื่อสร้างไฟล์ BUILD สำหรับโฮสต์ Bazel ที่กำลังใช้งานโดยเฉพาะได้ด้วย

การสร้างกฎที่เก็บ

ในไฟล์ .bzl ให้ใช้ฟังก์ชัน repository_rule เพื่อสร้างกฎที่เก็บใหม่และจัดเก็บไว้ในตัวแปรร่วม

คุณใช้กฎที่เก็บที่กำหนดเองได้เช่นเดียวกับกฎที่เก็บเนทีฟ โดยมีแอตทริบิวต์ name ที่จำเป็นและทุกเป้าหมายที่แสดงในไฟล์บิลด์อาจเรียกว่า @<name>//package:target โดยที่ <name> คือค่าของแอตทริบิวต์ name

ระบบจะโหลดกฎเมื่อคุณสร้างเองอย่างชัดแจ้ง หรือกฎเป็นการอ้างอิงของบิลด์ ในกรณีนี้ Bazel จะเรียกใช้ฟังก์ชัน implementation ฟังก์ชันนี้อธิบายวิธีสร้างที่เก็บ เนื้อหา และไฟล์ BUILD

Attributes

แอตทริบิวต์คืออาร์กิวเมนต์ของกฎ เช่น url หรือ sha256 คุณต้องระบุแอตทริบิวต์และประเภทเมื่อกำหนดกฎที่เก็บ

local_repository = repository_rule(
    implementation=_impl,
    local=True,
    attrs={"path": attr.string(mandatory=True)})

หากต้องการเข้าถึงแอตทริบิวต์ ให้ใช้ repository_ctx.attr.<attribute_name>

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,
    ...)

ฟังก์ชันการติดตั้งใช้งานจะดำเนินการเมื่อใด

หากที่เก็บได้รับการประกาศเป็น local การเปลี่ยนแปลงทรัพยากร Dependency ในกราฟการอ้างอิง (รวมถึงไฟล์ WORKSPACE เอง) จะทำให้มีการดำเนินการฟังก์ชันการติดตั้งใช้งาน

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

สุดท้าย สำหรับที่เก็บที่ไม่ใช่ local การเปลี่ยนแปลงการอ้างอิงต่อไปนี้เท่านั้นอาจทำให้มีการรีสตาร์ท

• ต้องมี .bzl ไฟล์เพื่อกำหนดกฎของที่เก็บ
• การประกาศกฎที่เก็บในไฟล์ WORKSPACE
• ค่าของตัวแปรสภาพแวดล้อมที่ประกาศด้วยแอตทริบิวต์ environ ของฟังก์ชัน repository_rule ค่าของตัวแปรสภาพแวดล้อมเหล่านั้นสามารถบังคับใช้จากบรรทัดคำสั่งด้วยแฟล็ก --action_env (แต่แฟล็กนี้จะทำให้การดำเนินการทั้งหมดของบิลด์ไม่ถูกต้อง)
• เนื้อหาของไฟล์ที่ใช้และอ้างถึงโดยป้ายกำกับ (เช่น //mypkg:label.txt ไม่ใช่ mypkg/label.txt)

การบังคับให้ดึงข้อมูลที่เก็บภายนอกอีกครั้ง

บางครั้งที่เก็บภายนอกอาจล้าสมัยโดยไม่มีการเปลี่ยนแปลงใดๆ กับคำจำกัดความหรือทรัพยากร Dependency เช่น แหล่งที่มาการดึงข้อมูลที่เก็บอาจเป็นไปตามสาขาเฉพาะของที่เก็บของบุคคลที่สาม และคอมมิตใหม่จะมีอยู่ใน Branch นั้น ในกรณีนี้ คุณสามารถขอให้ Bazel ดึงข้อมูลที่เก็บภายนอกทั้งหมดอีกครั้งโดยไม่มีเงื่อนไขโดยเรียกใช้ bazel sync

นอกจากนี้ กฎบางข้อจะตรวจสอบเครื่องภายในและอาจล้าสมัยหากมีการอัปเกรดเครื่องภายใน ในส่วนนี้ คุณจะขอให้ Bazel ดึงข้อมูลเฉพาะที่เก็บภายนอกเหล่านั้นอีกครั้งได้ก็ต่อเมื่อคำจำกัดความ repository_rule ตั้งค่าแอตทริบิวต์ configure แล้ว ให้ใช้ bazel sync --configure

ตัวอย่าง

• เครื่องมือ C++ ที่กำหนดค่าโดยอัตโนมัติ: ใช้กฎที่เก็บเพื่อสร้างไฟล์การกำหนดค่า C++ สำหรับ Bazel โดยอัตโนมัติ โดยมองหาคอมไพเลอร์ C++ ในเครื่อง สภาพแวดล้อม และแฟล็กที่คอมไพเลอร์ C++ รองรับ

• ที่เก็บ Go ใช้ repository_rule หลายรายการเพื่อกำหนดรายการทรัพยากร Dependency ที่จำเป็นสำหรับการใช้กฎ Go

• rules_jvm_external จะสร้างที่เก็บภายนอกชื่อ @maven โดยค่าเริ่มต้น เพื่อสร้างเป้าหมายบิวด์สำหรับอาร์ติแฟกต์ Maven ทั้งหมดในทรี Dependency แบบสลับ