กฎที่เก็บ

รายงานปัญหา ดูแหล่งที่มา ตอนกลางคืน · 7.4 ที่ใช้เวลาเพียง 2 นาที 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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

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

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

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

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

Attributes

แอตทริบิวต์คืออาร์กิวเมนต์กฎที่ส่งผ่านเป็นพจนานุกรมไปยังอาร์กิวเมนต์กฎ attrs แอตทริบิวต์และประเภทของแอตทริบิวต์จะถูกระบุไว้เมื่อคุณกำหนด กฎที่เก็บ ตัวอย่างการกำหนดแอตทริบิวต์ url และ sha256 เป็น strings:

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

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

ระบบจะไม่ดึงข้อมูลรีโพซิทอรีที่ไม่ใช่ในเครื่องอีกครั้งในกรณีเหล่านี้ เนื่องจากระบบจะถือว่าที่เก็บเหล่านี้สื่อสารกับเครือข่ายหรือมีราคาแพง

การเริ่มฟังก์ชันการติดตั้งใช้งานอีกครั้ง

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

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

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