รีจิสทรี 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 และ patch_strip
  • patches: ออบเจ็กต์ JSON ที่มีไฟล์แพตช์ที่จะใช้กับที่เก็บที่โคลน ไฟล์แพตช์จะอยู่ในไดเรกทอรี /modules/$MODULE/$VERSION/patches คีย์คือชื่อไฟล์แพตช์ และค่าคือเช็กซัม Integrity ของไฟล์แพตช์ ระบบจะใช้แพตช์ตามลำดับที่ปรากฏใน patches
• หาก 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