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

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

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

กฎเกี่ยวกับการโฮสต์และการตั้งชื่อ

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

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

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

• ชื่อที่เก็บ: 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

ข้อจำกัด

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

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

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

ไลบรารี Runfiles

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

กฎที่เก็บ

การอ้างอิง

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

การลงทะเบียนชุดเครื่องมือ

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

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

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

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

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

การทดสอบ

ควรมีการทดสอบเพื่อยืนยันว่ากฎทํางานตามที่คาดไว้ ซึ่งอาจเป็นที่ตำแหน่งมาตรฐานสำหรับภาษาของกฎหรือไดเรกทอรีtests/ที่ระดับบนสุดก็ได้

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

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

CI/CD

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

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

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

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

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

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

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

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

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

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