หน้านี้มีไว้สำหรับผู้เขียนกฎที่วางแผนจะทำให้กฎของตนใช้งานได้ ให้ผู้อื่นทราบ
เราขอแนะนำให้คุณเริ่มชุดกฎใหม่จากที่เก็บเทมเพลต โดยทำดังนี้ 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 (เช่น
โดยใช้ selects)
ข้อจำกัดที่กำหนดเองช่วยให้คุณกำหนดภาษาที่ระบบนิเวศ Bazel ทั้งหมด
จะพูด
ไลบรารี Runfiles
หากกฎของคุณมีไลบรารีมาตรฐานสำหรับการเข้าถึงรันไฟล์
ในรูปแบบของเป้าหมายห้องสมุดซึ่งอยู่ที่ //<LANG>/runfiles (อักษรย่อ
ของ //<LANG>/runfiles:runfiles) เป้าหมายผู้ใช้ที่ต้องการเข้าถึงข้อมูลของตน
โดยทั่วไปแล้วทรัพยากร Dependency จะเพิ่มเป้าหมายนี้ลงในแอตทริบิวต์ deps
กฎที่เก็บ
การอ้างอิง
กฎของคุณอาจมีทรัพยากร Dependency ภายนอก ซึ่งคุณต้องระบุใน ไฟล์ MODULE.bazel
กำลังลงทะเบียน Toolchain
กฎของคุณอาจลงทะเบียน Toolchains ด้วย ซึ่งคุณระบุใน MODULE.bazel
โปรดทราบว่าหากต้องการแก้ปัญหา Toolchain ในขั้นตอนการวิเคราะห์ Bazel จะต้อง
วิเคราะห์เป้าหมาย 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 ดูการกำหนดค่าที่ใช้ในที่เก็บrules-template ซึ่งทำได้ง่ายกว่าด้วย "เวิร์กโฟลว์ที่นำมาใช้ใหม่ได้" โฮสต์ใน Bazel-contrib
องค์กร ci.yaml จะทดสอบคอมโพเนนต์ PR และ main แต่ละรายการ และ release.yaml จะทำงานทุกครั้งที่คุณพุชแท็กไปยังที่เก็บ
ดูข้อมูลเพิ่มเติมได้ในความคิดเห็นในที่เก็บเทมเพลตกฎ
หากที่เก็บอยู่ภายใต้องค์กรbazelbuild คุณสามารถขอให้เพิ่มได้ ไปที่ ci.bazel.build
เอกสารประกอบ
ดูเอกสารประกอบของ Stardoc สำหรับ วิธีการแสดงความคิดเห็นเกี่ยวกับกฎของคุณ เพื่อให้ระบบสามารถสร้างเอกสารประกอบได้ โดยอัตโนมัติ
เอกสาร/ โฟลเดอร์เทมเพลตกฎ
แสดงวิธีง่ายๆ ในการตรวจสอบว่าเนื้อหามาร์กดาวน์ในโฟลเดอร์ docs/ เป็นข้อมูลล่าสุดเสมอ
เมื่อไฟล์ Starlark อัปเดต
คำถามที่พบบ่อย
เหตุใดเราเพิ่มกฎไปยังที่เก็บหลักของ Bazel GitHub ไม่ได้
เราต้องการแยกกฎจากการเผยแพร่ของ Bazel ออกให้ได้มากที่สุด ชัดเจนขึ้น ที่เป็นเจ้าของกฎเฉพาะตัว ซึ่งช่วยลดภาระงานให้กับนักพัฒนาของ Bazel สำหรับผู้ใช้ของเรา การแยกส่วนช่วยให้แก้ไข อัปเกรด ดาวน์เกรด และแทนที่กฎได้ง่ายขึ้น การมีส่วนร่วมกับกฎต่างๆ อาจมีน้ำหนักน้อยกว่าการร่วมให้ข้อมูลกับ Bazel - ซึ่งขึ้นอยู่กับกฎ ซึ่งรวมถึงการส่งสิทธิ์การเข้าถึง ที่เก็บ GitHub การขอสิทธิ์เข้าถึง Bazel นั้นเกี่ยวข้องกับ ขั้นตอนได้
แต่ข้อเสียคือกระบวนการติดตั้งแบบครั้งเดียวที่ซับซ้อนกว่าสำหรับผู้ใช้ของเรา คือ
เพิ่มการอ้างอิงในชุดกฎของคุณในไฟล์ MODULE.bazel
เราเคยมีกฎทั้งหมดในที่เก็บ Bazel (ภายใต้
//tools/build_rules หรือ //tools/build_defs) เรายังมีกฎอีก 2 ข้อ
แต่เรากำลังพยายามนำกฎที่เหลือออก