รีจิสทรี Bazel

Bazel จะค้นพบทรัพยากร Dependency โดยขอข้อมูลจากรีจิสทรี ของ Bazel ซึ่งเป็นฐานข้อมูลของโมดูล Bazel Bazel รองรับรีจิสทรีเพียงประเภทเดียวเท่านั้น นั่นคือ รีจิสทรีดัชนี ซึ่งเป็นไดเรกทอรีในเครื่องหรือเซิร์ฟเวอร์ HTTP แบบคงที่ที่ใช้รูปแบบเฉพาะ

รีจิสทรีดัชนี

รีจิสทรีดัชนีคือไดเรกทอรีในเครื่องหรือเซิร์ฟเวอร์ HTTP แบบคงที่ที่มีข้อมูลเกี่ยวกับรายการโมดูล ซึ่งรวมถึงหน้าแรก ผู้ดูแล ไฟล์ MODULE.bazel ของแต่ละเวอร์ชัน และวิธีดึงข้อมูลซอร์สของแต่ละเวอร์ชัน โปรดทราบว่ารีจิสทรี ไม่จำเป็นต้องให้บริการที่เก็บถาวรของซอร์สเอง

รีจิสทรีดัชนีต้องมีรูปแบบดังนี้

• /bazel_registry.json: ไฟล์ JSON ที่ไม่บังคับซึ่งมีข้อมูลเมตาสำหรับรีจิสทรี
• /modules: ไดเรกทอรีที่มีไดเรกทอรีย่อยสำหรับแต่ละโมดูลในรีจิสทรีนี้
• /modules/$MODULE: ไดเรกทอรีที่มีไดเรกทอรีย่อยสำหรับแต่ละเวอร์ชัน ของโมดูลที่ชื่อ $MODULE รวมถึงไฟล์ metadata.json ที่มีข้อมูลเมตาสำหรับโมดูลนี้
• /modules/$MODULE/$VERSION: ไดเรกทอรีที่มีไฟล์ต่อไปนี้
  • MODULE.bazel: ไฟล์ MODULE.bazel ของโมดูลเวอร์ชันนี้ โปรดทราบ ว่านี่คือไฟล์ MODULE.bazel ที่อ่านระหว่างการแก้ปัญหาทรัพยากร Dependency ภายนอก ของ Bazel ไม่ใช่ไฟล์จากที่เก็บถาวรของซอร์ส (ยกเว้น ในกรณีที่มีการ ลบล้างที่ไม่ใช่รีจิสทรี) นอกจากนี้ โปรดทราบว่าควรใช้ไฟล์นี้เพื่อตั้งค่าเวอร์ชันของการเผยแพร่และหลีกเลี่ยงการดำเนินการดังกล่าวในไฟล์ MODULE.bazel ที่เก็บถาวรของซอร์ส ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดเวอร์ชันของโมดูล ได้ที่คำถามที่พบบ่อย
  • source.json: ไฟล์ JSON ที่มีข้อมูลเกี่ยวกับวิธีดึงข้อมูลซอร์สของโมดูลเวอร์ชันนี้
  • patches/: ไดเรกทอรีที่ไม่บังคับซึ่งมีไฟล์แพตช์ โดยจะใช้ก็ต่อเมื่อ source.json มีประเภท "archive"
  • overlay/: ไดเรกทอรีที่ไม่บังคับซึ่งมีไฟล์ซ้อนทับ โดยจะใช้ก็ต่อเมื่อ source.json มีประเภท "archive"

bazel_registry.json

bazel_registry.json เป็นไฟล์ที่ไม่บังคับซึ่งระบุข้อมูลเมตาที่ใช้กับรีจิสทรีทั้งหมด โดยสามารถมีช่องต่อไปนี้

• mirrors: อาร์เรย์ของสตริงที่ระบุรายการมิเรอร์ที่จะใช้สำหรับที่เก็บถาวรของซอร์ส
  • URL ที่มิเรอร์คือการรวมกันของมิเรอร์เองและ URL ซอร์สของโมดูลที่ระบุโดยไฟล์ source.json โดยไม่มีโปรโตคอล ตัวอย่างเช่น หาก URL ซอร์สของโมดูลคือ https://foo.com/bar/baz และ mirrors มี ["https://mirror1.com/", "https://example.com/mirror2/"] จากนั้น URL ที่ Bazel จะลองตามลำดับคือ https://mirror1.com/foo.com/bar/baz, https://example.com/mirror2/foo.com/bar/baz และสุดท้ายคือ URL ซอร์สเดิม https://foo.com/bar/baz
• module_base_path: สตริงที่ระบุเส้นทางฐานสำหรับโมดูลที่มีประเภท local_path ในไฟล์ source.json

metadata.json

metadata.json เป็นไฟล์ JSON ที่ไม่บังคับซึ่งมีข้อมูลเกี่ยวกับโมดูล โดยมีช่องต่อไปนี้

• versions: อาร์เรย์ของสตริง ซึ่งแต่ละสตริงจะระบุเวอร์ชันของโมดูลที่พร้อมใช้งานในรีจิสทรีนี้ อาร์เรย์นี้ควรตรงกับรายการย่อยของไดเรกทอรีโมดูล
• yanked_versions: ออบเจ็กต์ JSON ที่ระบุเวอร์ชัน yanked ของโมดูลนี้ คีย์ควรเป็นเวอร์ชันที่จะ yank และค่าควรเป็นคำอธิบายว่าทำไมจึง yank เวอร์ชันดังกล่าว โดยควรมีลิงก์ไปยังข้อมูลเพิ่มเติม

โปรดทราบว่า BCR ต้องการข้อมูลเพิ่มเติมในไฟล์ metadata.json

source.json

source.json เป็นไฟล์ JSON ที่จำเป็นซึ่งมีข้อมูลเกี่ยวกับวิธีดึงข้อมูลโมดูลเวอร์ชันที่เฉพาะเจาะจง สคีมาของไฟล์นี้ขึ้นอยู่กับช่อง type ซึ่งมีค่าเริ่มต้นเป็น archive

• หาก type เป็น archive (ค่าเริ่มต้น) โมดูลเวอร์ชันนี้จะได้รับการสนับสนุนโดยกฎของ repo http_archive โดยจะดึงข้อมูล ด้วยการดาวน์โหลดที่เก็บถาวรจาก URL ที่ระบุและแยกเนื้อหา โดยรองรับช่องต่อไปนี้
  • url: สตริง ซึ่งเป็น URL ของที่เก็บถาวรของซอร์ส
  • mirror_urls: รายการสตริง ซึ่งเป็น URL ที่มิเรอร์ของที่เก็บถาวรของซอร์ส ระบบจะลองใช้ URL ตามลำดับหลังจาก url เป็นข้อมูลสำรอง
  • integrity: สตริง ซึ่งเป็นเช็คซัม Subresource Integrity ของที่เก็บถาวร
  • strip_prefix: สตริง ซึ่งเป็นคำนำหน้าไดเรกทอรีที่จะนำออกเมื่อแยกที่เก็บถาวรของซอร์ส
  • overlay: ออบเจ็กต์ JSON ที่มีไฟล์ซ้อนทับเพื่อวางไว้เหนือที่เก็บถาวรที่แยกออกมา ไฟล์แพตช์จะอยู่ในไดเรกทอรี /modules/$MODULE/$VERSION/overlay คีย์คือชื่อไฟล์ซ้อนทับ และค่าคือเช็คซัม Integrity ของไฟล์ซ้อนทับ ระบบจะใช้การซ้อนทับก่อนไฟล์แพตช์
  • patches: ออบเจ็กต์ JSON ที่มีไฟล์แพตช์ที่จะใช้กับที่เก็บถาวรที่แยกออกมา ไฟล์แพตช์จะอยู่ในไดเรกทอรี /modules/$MODULE/$VERSION/patches คีย์คือชื่อไฟล์แพตช์ และค่าคือเช็คซัม Integrity ของไฟล์แพตช์ ระบบจะใช้แพตช์หลังจากไฟล์ซ้อนทับและตามลำดับที่ปรากฏใน patches
  • patch_strip: ตัวเลข ซึ่งเหมือนกับอาร์กิวเมนต์ --strip ของ Unix patch
  • archive_type: สตริง ซึ่งเป็นประเภทที่เก็บถาวรของไฟล์ที่ดาวน์โหลด (เหมือนกับ type ใน http_archive)
• หาก type เป็น git_repository โมดูลเวอร์ชันนี้จะได้รับการสนับสนุนโดยกฎของ repo git_repository โดยจะดึงข้อมูลด้วยการโคลนที่เก็บ Git
  • ระบบรองรับช่องต่อไปนี้และส่งต่อโดยตรงไปยังกฎของ repo git_repository ที่เกี่ยวข้อง ได้แก่ remote, commit, shallow_since, tag, init_submodules, verbose และ strip_prefix
• หาก type เป็น local_path โมดูลเวอร์ชันนี้จะได้รับการสนับสนุนโดยกฎของ repo local_repository โดยจะลิงก์สัญลักษณ์ไปยังไดเรกทอรีในดิสก์ภายใน โดยรองรับช่องต่อไปนี้
  • path: เส้นทางภายในไปยัง repo ซึ่งคำนวณได้ดังนี้
    • หาก path เป็นเส้นทางสัมบูรณ์ เส้นทางจะยังคงเหมือนเดิม
    • หาก path เป็นเส้นทางสัมพัทธ์และ module_base_path เป็น เส้นทางสัมบูรณ์ เส้นทางจะเปลี่ยนเป็น <module_base_path>/<path>
    • หากทั้ง path และ module_base_path เป็นเส้นทางสัมพัทธ์ เส้นทางจะเปลี่ยนเป็น <registry_path>/<module_base_path>/<path> รีจิสทรีต้องโฮสต์ในเครื่องและใช้โดย --registry=file://<registry_path> มิเช่นนั้น Bazel จะแสดงข้อผิดพลาด

รีจิสทรีกลางของ Bazel

รีจิสทรีกลางของ Bazel (BCR) ที่ https://bcr.bazel.build/ คือรีจิสทรีดัชนี ที่มีเนื้อหาได้รับการสนับสนุนโดย repo GitHub bazelbuild/bazel-central-registry คุณสามารถเรียกดูเนื้อหาได้ โดยใช้ส่วนหน้าเว็บที่ https://registry.bazel.build/

ชุมชน Bazel เป็นผู้ดูแล BCR และยินดีรับผู้มีส่วนร่วมส่งคำขอ Pull ดูหลักเกณฑ์การมีส่วนร่วมใน BCR

นอกเหนือจากการใช้รูปแบบของรีจิสทรีดัชนีปกติแล้ว BCR ยังกำหนดให้มีไฟล์ presubmit.yml สำหรับโมดูลแต่ละเวอร์ชัน (/modules/$MODULE/$VERSION/presubmit.yml) ไฟล์นี้จะระบุเป้าหมายการสร้างและการทดสอบที่สำคัญบางอย่างที่คุณใช้เพื่อตรวจสอบความถูกต้องของโมดูลเวอร์ชันนี้ได้ ไปป์ไลน์ CI ของ BCR ยังใช้ไฟล์นี้เพื่อให้มั่นใจถึงความสามารถในการทำงานร่วมกันระหว่างโมดูล

การเลือกรีจิสทรี

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

หากรีจิสทรีโฮสต์อยู่ใน GitHub (เช่น เป็น Fork ของ bazelbuild/bazel-central-registry) ค่า --registry จะต้องมีที่อยู่ GitHub แบบดิบภายใต้ raw.githubusercontent.com ตัวอย่างเช่น ใน Branch main ของ Fork my-org คุณจะต้องตั้งค่า --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/

การใช้แฟล็ก --registry จะหยุดไม่ให้ใช้รีจิสทรีกลางของ Bazel เป็นค่าเริ่มต้น แต่คุณสามารถเพิ่มกลับได้โดยเพิ่ม --registry=https://bcr.bazel.build