กฎที่เก็บ

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

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

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

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

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

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

Attributes

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

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 ซึ่งมี ตรรกะที่แท้จริงของกฎและจะดำเนินการอย่างเคร่งครัดในระยะการโหลด

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

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

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

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

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

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

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

• พารามิเตอร์ที่ส่งไปยังการประกาศที่เก็บในไฟล์ WORKSPACE
• โค้ด Starlark ที่ประกอบด้วยการติดตั้งใช้งานที่เก็บ
• ค่าของตัวแปรสภาพแวดล้อมที่ส่งไปยังเมธอด repository_ctx getenv() หรือประกาศด้วยแอตทริบิวต์ environ ของ repository_rule ค่า ของตัวแปรสภาพแวดล้อมเหล่านี้สามารถกำหนดค่าไว้ในบรรทัดคำสั่งด้วยแฟล็ก --repo_env
• เนื้อหาของไฟล์ที่ส่งไปยัง read(), execute() และเมธอดที่คล้ายกัน ของ repository_ctx ซึ่งอ้างอิงโดยป้ายกำกับ (เช่น //mypkg:label.txt แต่ไม่ใช่ mypkg/label.txt)
• เมื่อมีการเรียกใช้ bazel sync

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

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

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

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

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

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

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

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

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

ตัวอย่าง

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

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

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