รีจิสทรี Bazel

รายงานปัญหา ดูซอร์สโค้ด รุ่น Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Bazel จะค้นหาข้อมูลพึ่งพาโดยขอข้อมูลจาก 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 ไม่ใช่ไฟล์จากที่เก็บถาวรของซอร์สโค้ด (เว้นแต่จะมีการลบล้างที่ไม่ใช่รีจิสทรี) นอกจากนี้ โปรดทราบว่าคุณควรใช้ไฟล์นี้เพื่อตั้งค่าเวอร์ชันของรุ่นและหลีกเลี่ยงการตั้งค่าในไฟล์ MODULE.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 ของที่เก็บถาวรของแหล่งที่มา
    • mirror_urls: รายการสตริง ซึ่งเป็น URL มิเรอร์ของที่เก็บถาวรต้นทาง ระบบจะลองใช้ URL ตามลําดับหลังจาก url รายการเป็นข้อมูลสํารอง
    • integrity: สตริง ซึ่งเป็นการตรวจสอบข้อผิดพลาด Subresource 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
  • หาก 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