การติดตั้งใช้งานกฎ

หน้านี้มีไว้สำหรับผู้เขียนกฎที่วางแผนจะเผยแพร่กฎของตนให้ผู้อื่นใช้

เราขอแนะนำให้คุณเริ่มชุดกฎใหม่จากที่เก็บเทมเพลต https://github.com/bazel-contrib/rules-template เทมเพลตดังกล่าวเป็นไปตามคำแนะนำด้านล่าง และรวมถึงการสร้างเอกสารประกอบ API และตั้งค่าไปป์ไลน์ CI/CD เพื่อให้การเผยแพร่ชุดกฎเป็นเรื่องง่าย

กฎการโฮสต์และการตั้งชื่อ

กฎใหม่ควรอยู่ในที่เก็บ GitHub ของตัวเองภายใต้องค์กรของคุณ เริ่มกระทู้ใน GitHub หากคุณคิดว่ากฎของคุณควรอยู่ในองค์กรbazelbuild

ชื่อที่เก็บสำหรับกฎของ Bazel เป็นไปตามรูปแบบต่อไปนี้ $ORGANIZATION/rules_$NAME ดูตัวอย่างใน GitHub คุณควรใช้รูปแบบเดียวกันนี้เมื่อเผยแพร่กฎของ Bazel เพื่อให้สอดคล้องกัน

ตรวจสอบว่าได้ใช้คำอธิบายที่เก็บ GitHub และชื่อ README.md ที่สื่อความหมาย เช่น

• ชื่อที่เก็บ: bazelbuild/rules_go
• คำอธิบายที่เก็บ: กฎ Go สำหรับ Bazel
• แท็กที่เก็บ: golang, bazel
• README.md ส่วนหัว: กฎ Go สำหรับ Bazel (โปรดสังเกตลิงก์ไปยัง https://bazel.build ซึ่งจะนำผู้ใช้ที่ไม่คุ้นเคย กับ Bazel ไปยังที่ที่เหมาะสม)

คุณจัดกลุ่มกฎตามภาษา (เช่น Scala), แพลตฟอร์มรันไทม์ (เช่น Android) หรือเฟรมเวิร์ก (เช่น Spring) ก็ได้

เนื้อหาที่เก็บ

ที่เก็บกฎทุกรายการควรมีเลย์เอาต์ที่กำหนดไว้เพื่อให้ผู้ใช้เข้าใจกฎใหม่ได้อย่างรวดเร็ว

ตัวอย่างเช่น เมื่อเขียนกฎใหม่สำหรับภาษา mockascript (สมมติขึ้น) ที่เก็บกฎจะมีโครงสร้างดังนี้

/
  LICENSE
  README
  MODULE.bazel
  mockascript/
    constraints/
      BUILD
    runfiles/
      BUILD
      runfiles.mocs
    BUILD
    defs.bzl
  tests/
    BUILD
    some_test.sh
    another_test.py
  examples/
    BUILD
    bin.mocs
    lib.mocs
    test.mocs

MODULE.bazel

ใน MODULE.bazel ของโปรเจ็กต์ คุณควรกำหนดชื่อที่ผู้ใช้จะใช้เพื่ออ้างอิงกฎของคุณ หากกฎของคุณอยู่ในองค์กร bazelbuild คุณต้องใช้ rules_<lang> (เช่น rules_mockascript) ไม่เช่นนั้น คุณควรตั้งชื่อ ที่เก็บเป็น <org>_rules_<lang> (เช่น build_stack_rules_proto) โปรด เริ่มกระทู้ใน GitHub หากคุณคิดว่ากฎของคุณควรเป็นไปตามข้อกำหนดสำหรับกฎในองค์กร bazelbuild

ในส่วนต่อไปนี้ ให้ถือว่าที่เก็บเป็นของ องค์กร bazelbuild

module(name = "rules_mockascript")

README

ที่ระดับบนสุดควรมี README ที่มีคำอธิบายสั้นๆ เกี่ยวกับชุดกฎและ API ที่ผู้ใช้ควรคาดหวัง

กฎ

ที่เก็บของคุณอาจมีกฎหลายข้อ สร้างไดเรกทอรีที่ตั้งชื่อตามภาษาและระบุจุดแรกเข้า ซึ่งก็คือไฟล์ defs.bzl ที่ส่งออกกฎทั้งหมด (รวมถึงไฟล์ BUILD เพื่อให้ไดเรกทอรีเป็นแพ็กเกจ) สำหรับ rules_mockascript นั่นหมายความว่าจะมีไดเรกทอรีชื่อ mockascript รวมถึงไฟล์ BUILD และไฟล์ defs.bzl อยู่ภายใน

/
  mockascript/
    BUILD
    defs.bzl

ข้อจำกัด

หากกฎของคุณกำหนด Toolchain กฎ คุณอาจต้องกำหนด constraint_setting ที่กำหนดเอง และ/หรือ constraint_value ใส่รายการเหล่านี้ลงในแพ็กเกจ //<LANG>/constraints โครงสร้างไดเรกทอรีจะมีลักษณะดังนี้

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

โปรดอ่าน github.com/bazelbuild/platforms เพื่อดูแนวทางปฏิบัติแนะนำและดูข้อจำกัดที่มีอยู่แล้ว รวมถึง พิจารณาส่งข้อจำกัดของคุณที่นั่นหากข้อจำกัดนั้นไม่ขึ้นอยู่กับภาษา โปรดระวังการนำข้อจำกัดที่กำหนดเองมาใช้ เนื่องจากผู้ใช้กฎของคุณทุกคนจะ ใช้ข้อจำกัดเหล่านั้นเพื่อดำเนินการตรรกะที่เฉพาะเจาะจงกับแพลตฟอร์มในไฟล์ BUILD (เช่น การใช้ Select) เมื่อใช้ข้อจำกัดที่กำหนดเอง คุณจะกำหนดภาษาที่ระบบนิเวศ Bazel ทั้งหมดจะใช้

ไลบรารี Runfiles

หากกฎของคุณมีไลบรารีมาตรฐานสำหรับการเข้าถึง Runfiles ไลบรารีนั้นควรอยู่ในรูปแบบของเป้าหมายไลบรารีที่อยู่ใน //<LANG>/runfiles (ตัวย่อของ //<LANG>/runfiles:runfiles) โดยปกติแล้วเป้าหมายของผู้ใช้ที่ต้องเข้าถึงการอ้างอิงข้อมูลจะเพิ่มเป้าหมายนี้ลงในแอตทริบิวต์ deps

กฎของที่เก็บ

แท็กเริ่มการทำงาน

กฎของคุณอาจมีแท็กเริ่มการทำงานภายนอก ซึ่งคุณจะต้องระบุในไฟล์ MODULE.bazel

การลงทะเบียน Toolchain

กฎของคุณอาจลงทะเบียน Toolchain ด้วย ซึ่งคุณระบุได้ในไฟล์ MODULE.bazel

โปรดทราบว่า Bazel ต้องวิเคราะห์เป้าหมาย toolchain ทั้งหมดที่ลงทะเบียนไว้เพื่อแก้ไข Toolchain ในระยะการวิเคราะห์ Bazel ไม่จำเป็นต้องวิเคราะห์เป้าหมายทั้งหมดที่แอตทริบิวต์ toolchain.toolchain อ้างอิง หากคุณต้องทำการคำนวณที่ซับซ้อนใน ที่เก็บเพื่อลงทะเบียน Toolchain ให้พิจารณาแยกที่เก็บที่มีเป้าหมาย toolchain ออกจาก ที่เก็บที่มีเป้าหมาย <LANG>_toolchain ระบบจะดึงข้อมูลที่เก็บแรกเสมอ และ จะดึงข้อมูลที่เก็บหลังก็ต่อเมื่อผู้ใช้ต้องการสร้างโค้ด <LANG> จริงๆ

ข้อมูลโค้ดการเผยแพร่

ในประกาศการเผยแพร่ ให้ระบุข้อมูลโค้ดที่ผู้ใช้สามารถคัดลอกและวางลงในไฟล์ MODULE.bazel ได้ โดยทั่วไปข้อมูลโค้ดนี้จะมีลักษณะดังนี้

bazel_dep(name = "rules_<LANG>", version = "<VERSION>")

การทดสอบ

ควรมีการทดสอบเพื่อยืนยันว่ากฎทำงานตามที่คาดไว้ การทดสอบอาจอยู่ในตำแหน่งมาตรฐานสำหรับภาษาที่กฎใช้ หรืออยู่ในไดเรกทอรี tests/ ที่ระดับบนสุด

ตัวอย่าง (ไม่บังคับ)

การมีไดเรกทอรี examples/ ที่แสดงวิธีพื้นฐาน 2-3 วิธีในการใช้กฎจะเป็นประโยชน์ต่อผู้ใช้

CI/CD

ชุดกฎหลายชุดใช้ GitHub Actions ดูการกำหนดค่าที่ใช้ในที่เก็บ กฎเทมเพลต ซึ่งได้รับการทำให้ง่ายขึ้นโดยใช้ "เวิร์กโฟลว์ที่นำกลับมาใช้ใหม่ได้" ที่โฮสต์ในองค์กร bazel-contrib ci.yaml จะเรียกใช้การทดสอบใน PR และการคอมมิต main แต่ละรายการ ส่วน release.yaml จะเรียกใช้ทุกครั้งที่คุณพุชแท็กไปยังที่เก็บ ดูข้อมูลเพิ่มเติมได้ที่ความคิดเห็นในที่เก็บกฎเทมเพลต

หากที่เก็บของคุณอยู่ในองค์กร bazelbuild คุณสามารถขอเพิ่ม ที่เก็บลงในci.bazel.buildได้

เอกสารประกอบ

ดูวิธีการในเอกสารประกอบ Stardoc เกี่ยวกับ วิธีแสดงความคิดเห็นในกฎเพื่อให้ระบบสร้างเอกสารประกอบได้ โดยอัตโนมัติ

โฟลเดอร์ docs/ ของกฎเทมเพลต แสดงวิธีง่ายๆ ในการตรวจสอบว่าเนื้อหา Markdown ในโฟลเดอร์ docs/ เป็นข้อมูลล่าสุดเสมอ เมื่อมีการอัปเดตไฟล์ Starlark

คำถามที่พบบ่อย

เหตุใดเราจึงเพิ่มกฎลงในที่เก็บ GitHub หลักของ Bazel ไม่ได้

เราต้องการแยกกฎออกจากการเผยแพร่ Bazel ให้มากที่สุด การแยกกฎจะช่วยให้เห็นได้ชัดเจนขึ้นว่าใครเป็นเจ้าของกฎแต่ละข้อ ซึ่งจะช่วยลดภาระงานของนักพัฒนาซอฟต์แวร์ Bazel การแยกกฎออกจากการเผยแพร่จะช่วยให้ผู้ใช้แก้ไข อัปเกรด ดาวน์เกรด และแทนที่กฎได้ง่ายขึ้น การมีส่วนร่วมในกฎอาจมีน้ำหนักเบากว่าการมีส่วนร่วมใน Bazel (ขึ้นอยู่กับกฎ) ซึ่งรวมถึงสิทธิ์เข้าถึงแบบเต็มเพื่อส่งที่เก็บ GitHub ที่เกี่ยวข้อง การได้รับสิทธิ์เข้าถึงเพื่อส่ง Bazel เองเป็นกระบวนการที่ซับซ้อนกว่ามาก

ข้อเสียคือกระบวนการติดตั้งแบบครั้งเดียวที่ซับซ้อนมากขึ้นสำหรับผู้ใช้ ซึ่งต้องเพิ่มทรัพยากร Dependency ในชุดกฎลงในไฟล์ MODULE.bazel

เราเคยมีกฎทั้งหมดอยู่ในที่เก็บ Bazel (ภายใต้ //tools/build_rules หรือ //tools/build_defs) ปัจจุบันเรายังมีกฎ 2-3 ข้ออยู่ที่นั่น แต่กำลังดำเนินการย้ายกฎที่เหลือออก