กฎที่เก็บ

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

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

การกำหนดกฎที่เก็บ

ในไฟล์ .bzl ให้ใช้ฟังก์ชัน repository_rule เพื่อกำหนดกฎที่เก็บ ใหม่และจัดเก็บไว้ในตัวแปรส่วนกลาง หลังจากกำหนดกฎที่เก็บแล้ว คุณจะเรียกใช้กฎดังกล่าวเป็นฟังก์ชันเพื่อกำหนดที่เก็บได้ โดยปกติแล้วการเรียกใช้จะดำเนินการจากภายในฟังก์ชันการติดตั้งใช้งาน ส่วนขยายโมดูล

องค์ประกอบหลัก 2 อย่างของการกำหนดกฎที่เก็บคือสคีมาแอตทริบิวต์และฟังก์ชันการติดตั้งใช้งาน สคีมาแอตทริบิวต์จะกำหนดชื่อและประเภทของแอตทริบิวต์ที่ส่งผ่านไปยังการเรียกใช้กฎที่เก็บ และระบบจะเรียกใช้ฟังก์ชันการติดตั้งใช้งานเมื่อต้องดึงข้อมูลที่เก็บ

Attributes

แอตทริบิวต์คืออาร์กิวเมนต์ที่ส่งผ่านไปยังการเรียกใช้กฎที่เก็บ คุณระบุสคีมาของแอตทริบิวต์ที่กฎที่เก็บยอมรับได้โดยใช้อาร์กิวเมนต์ attrs เมื่อกำหนดกฎที่เก็บด้วยการเรียกใช้ repository_rule ตัวอย่างการกำหนดแอตทริบิวต์ url และ sha256 เป็นสตริง

http_archive = repository_rule(
    implementation=_impl,
    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 ทั้งหมดมีแอตทริบิวต์ name ที่กำหนดไว้โดยนัย แอตทริบิวต์นี้เป็นแอตทริบิวต์สตริงที่มีลักษณะการทำงานที่ค่อนข้างพิเศษ กล่าวคือ เมื่อระบุเป็นอินพุตในการเรียกใช้กฎที่เก็บ แอตทริบิวต์นี้จะใช้ชื่อที่เก็บที่เห็นได้ชัด แต่เมื่ออ่านจากฟังก์ชันการติดตั้งใช้งานของกฎที่เก็บโดยใช้ repository_ctx.attr.name แอตทริบิวต์นี้จะแสดงชื่อที่เก็บ Canonical

ฟังก์ชันการติดตั้งใช้งาน

กฎที่เก็บทุกรายการต้องมีฟังก์ชัน implementation ฟังก์ชันนี้มีตรรกะที่แท้จริงของกฎและจะดำเนินการในระยะการโหลดเท่านั้น

ฟังก์ชันนี้มีพารามิเตอร์อินพุต 1 รายการเท่านั้นคือ repository_ctx ฟังก์ชันจะแสดงผล None เพื่อระบุว่ากฎสามารถทำซ้ำได้เมื่อกำหนดพารามิเตอร์ หรือแสดงผลพจนานุกรมที่มีชุดพารามิเตอร์สำหรับกฎนั้นๆ ซึ่งจะทำให้กฎนั้นสามารถทำซ้ำได้และสร้างที่เก็บเดียวกัน ตัวอย่างเช่น สำหรับกฎที่ติดตามที่เก็บ Git นั่นหมายถึงการแสดงผลตัวระบุคอมมิตที่เฉพาะเจาะจงแทนที่จะเป็น Branch แบบลอยที่ระบุไว้แต่เดิม

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

def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)

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

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

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

• แอตทริบิวต์ที่ส่งผ่านไปยังการเรียกใช้กฎที่เก็บ
• โค้ด Starlark ที่ประกอบขึ้นเป็นฟังก์ชันการติดตั้งใช้งานของกฎที่เก็บ
• ค่าของตัวแปรสภาพแวดล้อมที่ส่งผ่านไปยัง repository_ctx's getenv() เมธอด หรือประกาศด้วยแอตทริบิวต์ environ ของ repository_rule คุณสามารถกำหนดค่าของ ตัวแปรสภาพแวดล้อมเหล่านี้ไว้ในบรรทัดคำสั่งด้วย --repo_envแฟล็ก
• การมีอยู่ เนื้อหา และประเภทของเส้นทางที่ watched ในการติดตั้งใช้งาน ฟังก์ชันของกฎที่เก็บ
  • เมธอดอื่นๆ บางรายการของ repository_ctx ที่มีพารามิเตอร์ watch เช่น read() execute() และ extract() ก็อาจทำให้ระบบดูเส้นทางได้เช่นกัน
  • ในทำนองเดียวกัน repository_ctx.watch_tree และ path.readdir อาจทำให้ระบบดูเส้นทาง ได้ด้วยวิธีอื่นๆ
• เมื่อมีการเรียกใช้ bazel fetch --force

repository_rule มีพารามิเตอร์ 2 รายการที่ควบคุมเวลาที่ระบบจะดึงข้อมูลที่เก็บอีกครั้ง ดังนี้

• หากตั้งค่าแฟล็ก configure ไว้ ระบบจะดึงข้อมูลที่เก็บอีกครั้งเมื่อมีการเรียกใช้ bazel fetch --force --configure (ระบบจะไม่ดึงข้อมูลที่เก็บที่ไม่ใช่ configure อีกครั้ง)
• หากตั้งค่าแฟล็ก local ไว้ นอกเหนือจากกรณีข้างต้นแล้ว ระบบจะดึงข้อมูลที่เก็บอีกครั้งเมื่อเซิร์ฟเวอร์ Bazel รีสตาร์ทด้วย

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

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

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

ตัวอย่าง

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

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

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