กฎที่เก็บ

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

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

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

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

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

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

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

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

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

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

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

• แอตทริบิวต์ที่ส่งผ่านไปยังการเรียกใช้กฎของที่เก็บ
• โค้ด Starlark ที่ประกอบด้วยการติดตั้งใช้งานกฎ repo
• ค่าของตัวแปรสภาพแวดล้อมที่ส่งไปยังเมธอด repository_ctx getenv() หรือประกาศด้วยแอตทริบิวต์ environ ของ repository_rule ค่าของตัวแปรสภาพแวดล้อมเหล่านี้สามารถกำหนดค่าในบรรทัดคำสั่งด้วยแฟล็ก --repo_env
• การมีอยู่ เนื้อหา และประเภทของเส้นทางใดๆ ที่watchในฟังก์ชันการใช้งาน ของกฎที่เก็บ
  • นอกจากนี้ วิธีอื่นๆ บางอย่างของ 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

ตัวอย่าง

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

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

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