หน้านี้มีไว้สำหรับผู้เขียนกฎที่วางแผนจะทำให้ผู้อื่นใช้กฎของตน
เราขอแนะนำให้คุณเริ่มชุดกฎใหม่จากที่เก็บเทมเพลต: 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
ข้อจำกัด
หากกฎของคุณกําหนดกฎเครื่องมือทํางาน คุณอาจต้องกําหนด 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
) โดยทั่วไปแล้วเป้าหมายผู้ใช้ที่จำเป็นต้องเข้าถึงทรัพยากร Dependency จะเพิ่มเป้าหมายนี้ลงในแอตทริบิวต์ deps
ของตน
กฎที่เก็บ
การอ้างอิง
กฎของคุณอาจมีทรัพยากรภายนอก ซึ่งคุณจะต้องระบุไว้ในไฟล์ MODULE.bazel
กำลังลงทะเบียน Toolchain
กฎของคุณอาจลงทะเบียน Toolchain ด้วย ซึ่งคุณระบุในไฟล์ MODULE.bazel ได้ด้วย
โปรดทราบว่า Bazel ต้องวิเคราะห์เป้าหมาย toolchain
ทั้งหมดที่ลงทะเบียนไว้ เพื่อแก้ไข Toolchain ในระยะการวิเคราะห์ Bazel จะไม่จําเป็นต้องวิเคราะห์เป้าหมายทั้งหมดที่แอตทริบิวต์ toolchain.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 ข้ออยู่ แต่กำลังพยายามนำกฎที่เหลือออก