รีจิสทรี Bazel

รายงานปัญหา ดูซอร์ส รุ่น Nightly · 8.1 · 8.0 · 7.5 · 7.4

Bzlmod จะค้นหาข้อมูลพึ่งพาโดยขอข้อมูลจาก registries ของ 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 ที่อ่านระหว่างการแก้ไขข้อกำหนดภายนอกของ Bazel ไม่ใช่ไฟล์จากที่เก็บถาวรของซอร์สโค้ด (เว้นแต่จะมีการลบล้างที่ไม่ใช่รีจิสทรี)
  • source.json: ไฟล์ JSON ที่มีข้อมูลเกี่ยวกับวิธีดึงข้อมูลแหล่งที่มาของเวอร์ชันโมดูลนี้
  • patches/: ไดเรกทอรีที่ไม่บังคับซึ่งมีไฟล์แพตช์ จะใช้ก็ต่อเมื่อ source.json มีประเภทเป็น "archive"
  • overlay/: ไดเรกทอรีที่ไม่บังคับซึ่งมีไฟล์วางซ้อน จะใช้ก็ต่อเมื่อ source.json มีประเภทเป็น "ไฟล์เก็บถาวร"

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 ที่ระบุเวอร์ชันที่ยกเลิกของข้อบังคับนี้ คีย์ควรเป็นเวอร์ชันที่จะดึงออก และค่าควรเป็นคำอธิบายสาเหตุที่ดึงเวอร์ชันออก โดยควรมีลิงก์ไปยังข้อมูลเพิ่มเติม

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

source.json

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

• หาก type เป็น archive (ค่าเริ่มต้น) เวอร์ชันของโมดูลนี้จะสำรองข้อมูลโดยกฎของที่เก็บ http_archive ระบบจะดึงข้อมูลโดยดาวน์โหลดไฟล์เก็บถาวรจาก URL ที่ระบุและดึงข้อมูลเนื้อหา โดยรองรับฟิลด์ต่อไปนี้
  • url: สตริงที่เป็น URL ของที่เก็บถาวรของแหล่งที่มา
  • integrity: สตริง ซึ่งเป็นการตรวจสอบข้อผิดพลาด Subresource Integrity ของที่เก็บถาวร
  • strip_prefix: สตริง ซึ่งเป็นคำนำหน้าไดเรกทอรีที่จะตัดออกเมื่อแตกไฟล์เก็บถาวรต้นทาง
  • overlay: ออบเจ็กต์ JSON ที่มีไฟล์วางซ้อนเพื่อวางซ้อนบนไฟล์ที่เก็บถาวรที่ดึงข้อมูล ไฟล์แพตช์จะอยู่ภายใต้ไดเรกทอรี /modules/$MODULE/$VERSION/overlay โดยคีย์คือชื่อไฟล์วางซ้อน และค่าคือการตรวจสอบความสมบูรณ์ของไฟล์วางซ้อน ระบบจะใช้การวางซ้อนก่อนไฟล์แพตช์
  • patches: ออบเจ็กต์ JSON ที่มีไฟล์แพตช์ที่จะใช้กับไฟล์ที่เก็บถาวรที่ดึงข้อมูล ไฟล์แพตช์จะอยู่ภายใต้ไดเรกทอรี /modules/$MODULE/$VERSION/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
• หาก 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 และยินดีให้ผู้มีส่วนร่วมส่งคำขอดึงข้อมูล โปรดดูหลักเกณฑ์การมีส่วนร่วมใน BCR

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

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

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

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

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