รีจิสทรี 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 (ค่าเริ่มต้น) โมดูลเวอร์ชันนี้จะได้รับการสนับสนุนโดยกฎของที่เก็บ http_archive โดยจะดึงข้อมูล ด้วยการดาวน์โหลดไฟล์เก็บถาวรจาก URL ที่กำหนดและแยกเนื้อหา โดยรองรับช่องต่อไปนี้
  • url: สตริง ซึ่งเป็น URL ของไฟล์เก็บถาวรของซอร์ส
  • mirror_urls: รายการสตริง ซึ่งเป็น URL ที่มิเรอร์ของไฟล์เก็บถาวรของซอร์ส ระบบจะลองใช้ URL ตามลำดับหลังจาก url เป็นข้อมูลสำรอง
  • integrity: สตริง ซึ่งเป็นผลรวมตรวจสอบความสมบูรณ์ของทรัพยากรย่อยของไฟล์เก็บถาวร
  • strip_prefix: สตริง ซึ่งเป็นคำนำหน้าไดเรกทอรีที่จะนำออกเมื่อแยกไฟล์เก็บถาวรของซอร์ส
  • overlay: ออบเจ็กต์ JSON ที่มีไฟล์ซ้อนทับเพื่อวางไว้เหนือไฟล์เก็บถาวรที่แยกออกมา ไฟล์แพตช์จะอยู่ในไดเรกทอรี /modules/$MODULE/$VERSION/overlay คีย์คือชื่อไฟล์ซ้อนทับ และค่าคือผลรวมตรวจสอบความสมบูรณ์ของไฟล์ซ้อนทับ ระบบจะใช้การซ้อนทับก่อนไฟล์แพตช์
  • patches: ออบเจ็กต์ JSON ที่มีไฟล์แพตช์ที่จะใช้กับไฟล์เก็บถาวรที่แยกออกมา ไฟล์แพตช์จะอยู่ในไดเรกทอรี /modules/$MODULE/$VERSION/patches คีย์คือชื่อไฟล์แพตช์ และค่าคือผลรวมตรวจสอบความสมบูรณ์ของไฟล์แพตช์ ระบบจะใช้แพตช์หลังจากไฟล์ซ้อนทับและตามลำดับที่ปรากฏใน patches
  • patch_strip: ตัวเลข ซึ่งเหมือนกับอาร์กิวเมนต์ --strip ของ Unix patch
  • archive_type: สตริง ซึ่งเป็นประเภทไฟล์เก็บถาวรของไฟล์ที่ดาวน์โหลด (เหมือนกับ type ใน http_archive)
• หาก type เป็น git_repository โมดูลเวอร์ชันนี้จะได้รับการสนับสนุนโดยกฎของที่เก็บ git_repository โดยจะดึงข้อมูลด้วยการโคลนที่เก็บ Git
  • ระบบรองรับช่องต่อไปนี้และส่งต่อโดยตรงไปยังกฎของที่เก็บ git_repository ที่เกี่ยวข้อง ได้แก่ remote, commit, shallow_since, tag, init_submodules, verbose, strip_prefix, และ patch_strip
  • patches: ออบเจ็กต์ JSON ที่มีไฟล์แพตช์ที่จะใช้กับที่เก็บที่โคลน ไฟล์แพตช์จะอยู่ในไดเรกทอรี /modules/$MODULE/$VERSION/patches คีย์คือชื่อไฟล์แพตช์ และค่าคือผลรวมตรวจสอบความสมบูรณ์ของไฟล์แพตช์ ระบบจะใช้แพตช์ตามลำดับที่ปรากฏใน patches
• หาก type เป็น local_path โมดูลเวอร์ชันนี้จะได้รับการสนับสนุนโดยกฎของที่เก็บ local_repository โดย จะมีการสร้างลิงก์สัญลักษณ์ไปยังไดเรกทอรีในดิสก์ในเครื่อง โดยรองรับช่องต่อไปนี้
  • path: เส้นทางในเครื่องไปยังที่เก็บ ซึ่งคำนวณได้ดังนี้
    • หาก 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/ คือรีจิสทรีดัชนีที่มีเนื้อหาได้รับการสนับสนุนโดยที่เก็บ 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 ตัวอย่างเช่น ในสาขา main ของ Fork my-org คุณจะต้องตั้งค่า --registry=https://raw.githubusercontent.com/my-org/bazel-central-registry/main/

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