หน้านี้มีไว้สำหรับผู้เขียนกฎที่วางแผนจะทำให้กฎของตนใช้งานได้ ให้ผู้อื่นทราบ
เราขอแนะนำให้คุณเริ่มชุดกฎใหม่จากที่เก็บเทมเพลต โดยทำดังนี้ 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
WORKSPACE
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
พื้นที่ทำงาน
ใน WORKSPACE ของโปรเจ็กต์ คุณควรกำหนดชื่อที่ผู้ใช้จะใช้
เพื่ออ้างอิงกฎของคุณ หากกฎของคุณเป็นของ
bazelbuild คุณต้องใช้
rules_<lang> (เช่น rules_mockascript) หรือไม่เช่นนั้น คุณควรตั้งชื่อ
ที่เก็บ <org>_rules_<lang> (เช่น build_stack_rules_proto) โปรด
เริ่มชุดข้อความใน GitHub
ถ้าคุณรู้สึกว่ากฎของคุณควรเป็นไปตามกฎเกณฑ์สำหรับกฎใน
องค์กร bazelbuild
ในส่วนต่อไปนี้ ให้สมมติว่าที่เก็บเป็นของ bazelbuild
workspace(name = "rules_mockascript")
README
ที่ระดับบนสุด ควรมี README ที่มีส่วน (อย่างน้อย)
ผู้ใช้ต้องคัดลอกและวางลงในไฟล์ WORKSPACE เพื่อใช้กฎของคุณ
โดยทั่วไปแล้ว นี่จะเป็น http_archive ที่ชี้ไปยังรุ่น GitHub และ
การเรียกมาโครที่ดาวน์โหลด/กำหนดค่าเครื่องมือใดๆ ที่กฎของคุณต้องการ ตัวอย่างเช่น
สำหรับปุ่ม Go
กฎข้อนี้
ดูเหมือน:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_go",
urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()
หากกฎของคุณขึ้นอยู่กับกฎของที่เก็บอื่น ให้ระบุพารามิเตอร์นั้นใน
(เช่น โปรดดู
กฎของ Skydoc
ซึ่งขึ้นอยู่กับกฎ Sass) และระบุ WORKSPACE
ที่จะดาวน์โหลดทรัพยากร Dependency ทั้งหมด (ดู rules_go ด้านบน)
กฎ
บ่อยครั้งจะมีกฎหลายข้อจากที่เก็บของคุณ สร้าง
ไดเรกทอรีที่ตั้งชื่อตามภาษาและระบุจุดแรกเข้า - ไฟล์ 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 ภายนอก เพื่อทำให้ขึ้นอยู่กับกฎของคุณ
โปรดระบุมาโคร WORKSPACE ที่จะประกาศทรัพยากร Dependency ใน
ทรัพยากร Dependency ภายนอกเหล่านั้น ไม่ต้องประกาศทรัพยากร Dependency ของการทดสอบในหน้าดังกล่าว มีเพียง
ทรัพยากร Dependency ที่กฎกำหนดให้ทำงาน ใส่ทรัพยากร Dependency ของการพัฒนา
WORKSPACE ไฟล์
สร้างไฟล์ชื่อ <LANG>/repositories.bzl และระบุจุดแรกเข้าจุดเดียว
ชื่อ rules_<LANG>_dependencies ไดเรกทอรีของเราจะมีลักษณะดังนี้
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
กำลังลงทะเบียน Toolchain
นอกจากนี้ กฎของคุณยังอาจลงทะเบียน Toolchains ด้วย โปรดระบุWORKSPACEแยกต่างหาก
ซึ่งจะลงทะเบียน Toolchain เหล่านี้ วิธีนี้จะช่วยให้ผู้ใช้สามารถเลือกไม่ใช้
ก่อนหน้าและควบคุมทรัพยากร Dependency ด้วยตนเองได้
ขณะที่ยังคงได้รับอนุญาต
ลงทะเบียน Toolchain
ดังนั้นให้เพิ่มมาโคร WORKSPACE ชื่อ rules_<LANG>_toolchains ลงใน
<LANG>/repositories.bzl ไฟล์
โปรดทราบว่าหากต้องการแก้ปัญหา Toolchain ในขั้นตอนการวิเคราะห์ Bazel จะต้อง
วิเคราะห์เป้าหมาย toolchain ทั้งหมดที่ลงทะเบียนไว้ Bazel ไม่จำเป็นต้อง
วิเคราะห์เป้าหมายทั้งหมดที่อ้างอิงโดยแอตทริบิวต์ toolchain.toolchain หากสั่งซื้อ
ในการลงทะเบียน Toolchain คุณต้องทำการคำนวณที่ซับซ้อนใน
ให้ลองแยกที่เก็บที่มีเป้าหมาย toolchain จาก
ที่มีเป้าหมาย <LANG>_toolchain รายการ ระบบจะดึงข้อมูล "ก่อนหน้า" เสมอและ
ระบบจะดึงข้อมูลรายการหลังเมื่อผู้ใช้จำเป็นต้องสร้างโค้ด <LANG> จริงๆ เท่านั้น
ตัวอย่างข้อมูลการเผยแพร่
ในประกาศประจำรุ่น ให้ระบุตัวอย่างข้อมูลที่ผู้ใช้สามารถคัดลอกและวางได้
ลงในไฟล์ WORKSPACE โดยทั่วไปข้อมูลโค้ดนี้จะมีลักษณะดังต่อไปนี้
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_<LANG>",
urls = ["<url_to_the_release.zip"],
sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()
การทดสอบ
ควรมีการทดสอบที่ยืนยันว่ากฎทำงานตามที่คาดไว้ ช่วงเวลานี้
อาจอยู่ในสถานที่ตั้งมาตรฐานสำหรับภาษาที่มีกฎ หรือ
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 นั้นเกี่ยวข้องกับ ขั้นตอนได้
แต่ข้อเสียคือกระบวนการติดตั้งแบบครั้งเดียวที่ซับซ้อนกว่าสำหรับผู้ใช้ของเรา คือ
จะต้องคัดลอกและวางกฎลงในไฟล์ WORKSPACE ดังที่แสดงใน
README.md ด้านบน
เราเคยมีกฎทั้งหมดในที่เก็บ Bazel (ภายใต้
//tools/build_rules หรือ //tools/build_defs) เรายังมีกฎอีก 2 ข้อ
แต่เรากำลังพยายามนำกฎที่เหลือออก