กฎที่เก็บ

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

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

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

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

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

ระบบจะโหลดกฎเมื่อคุณสร้างกฎอย่างชัดแจ้ง หรือหากกฎเป็นทรัพยากร Dependency ของบิลด์ ในกรณีนี้ 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 ในกราฟทรัพยากร Dependency (รวมถึงไฟล์ WORKSPACE เอง) จะทำให้ระบบเรียกใช้ฟังก์ชันการติดตั้งใช้งาน

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

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

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

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

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

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

ตัวอย่าง

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

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

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