หน้านี้มีไว้สำหรับผู้เขียนกฎที่วางแผนจะเผยแพร่กฎของตนให้ผู้อื่นใช้
เราขอแนะนำให้คุณเริ่มชุดกฎใหม่จากที่เก็บเทมเพลต 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
ใน 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
มาโครที่จะดาวน์โหลดการอ้างอิงทั้งหมด (ดู 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 (เช่น
การใช้ Select)
ข้อจำกัดที่กำหนดเองจะกำหนดภาษาที่ระบบนิเวศ Bazel ทั้งหมดจะใช้
ไลบรารี Runfiles
หากกฎของคุณมีไลบรารีมาตรฐานสำหรับการเข้าถึง Runfiles ไลบรารีนั้นควรอยู่ในรูปแบบเป้าหมายของไลบรารีที่ //<LANG>/runfiles (ตัวย่อของ //<LANG>/runfiles:runfiles) โดยทั่วไปเป้าหมายของผู้ใช้ที่ต้องเข้าถึงการอ้างอิงข้อมูลจะเพิ่มเป้าหมายนี้ลงในแอตทริบิวต์ deps
กฎที่เก็บ
แท็กเริ่มการทำงาน
กฎของคุณอาจมีการอ้างอิงภายนอก โปรดระบุมาโคร WORKSPACE ที่จะประกาศการอ้างอิงการอ้างอิงภายนอกเหล่านั้น เพื่อให้การอ้างอิงกฎของคุณง่ายขึ้น อย่าประกาศการอ้างอิงการทดสอบที่นั่น ให้ประกาศเฉพาะการอ้างอิงที่กฎต้องใช้ในการทำงาน ใส่การอ้างอิงการพัฒนาลงในไฟล์ WORKSPACE
สร้างไฟล์ชื่อ <LANG>/repositories.bzl และระบุมาโครจุดเริ่มต้นเดียว ชื่อ rules_<LANG>_dependencies. ไดเรกทอรีของเราจะมีลักษณะดังนี้
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
การลงทะเบียน Toolchain
กฎของคุณอาจลงทะเบียน Toolchain ด้วย โปรดระบุมาโคร WORKSPACE แยกต่างหากที่จะลงทะเบียน Toolchain เหล่านี้ วิธีนี้จะช่วยให้ผู้ใช้เลือกละเว้นมาโครก่อนหน้าและควบคุมการอ้างอิงด้วยตนเองได้ ขณะเดียวกันก็ยังได้รับอนุญาตให้ลงทะเบียน Toolchain
ดังนั้น ให้เพิ่มมาโคร WORKSPACE ชื่อ rules_<LANG>_toolchains ลงใน
<LANG>/repositories.bzl ไฟล์
โปรดทราบว่า Bazel ต้องวิเคราะห์เป้าหมาย toolchain ทั้งหมดที่ลงทะเบียนไว้เพื่อแก้ไข 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 Actions ดูการกำหนดค่าที่ใช้ในที่เก็บ rules-template ซึ่งได้รับการทำให้ง่ายขึ้นโดยใช้ "เวิร์กโฟลว์ที่นำมาใช้ซ้ำได้" ที่โฮสต์อยู่ในองค์กร bazel-contrib
ci.yaml จะเรียกใช้การทดสอบในคำขอแบบดึงข้อมูล (Pull Request) และการคอมมิต main แต่ละรายการ ส่วน release.yaml จะเรียกใช้ทุกครั้งที่คุณพุชแท็กไปยังที่เก็บ
ดูข้อมูลเพิ่มเติมได้ที่ความคิดเห็นในที่เก็บ rules-template
หากที่เก็บของคุณอยู่ในองค์กร bazelbuild คุณสามารถขอเพิ่ม ที่เก็บลงในci.bazel.buildได้
เอกสารประกอบ
ดูวิธีการในเอกสารประกอบ Stardoc เกี่ยวกับ วิธีแสดงความคิดเห็นในกฎเพื่อให้ระบบสร้างเอกสารประกอบได้ โดยอัตโนมัติ
โฟลเดอร์ docs/ ของ rules-template
แสดงวิธีง่ายๆ ในการตรวจสอบว่าเนื้อหา Markdown ในโฟลเดอร์ docs/ เป็นข้อมูลล่าสุดเสมอ
เมื่อมีการอัปเดตไฟล์ Starlark
คำถามที่พบบ่อย
เหตุใดเราจึงเพิ่มกฎลงในที่เก็บ GitHub หลักของ Bazel ไม่ได้
เราต้องการแยกกฎออกจากการเผยแพร่ Bazel ให้มากที่สุด เพื่อให้เห็นได้ชัดเจนว่าใครเป็นเจ้าของกฎแต่ละข้อ ซึ่งจะช่วยลดภาระงานของนักพัฒนาซอฟต์แวร์ Bazel การแยกกฎออกจากการเผยแพร่ Bazel จะช่วยให้ผู้ใช้แก้ไข อัปเกรด ดาวน์เกรด และแทนที่กฎได้ง่ายขึ้น การมีส่วนร่วมในกฎอาจมีขั้นตอนน้อยกว่าการมีส่วนร่วมใน Bazel (ขึ้นอยู่กับกฎ) ซึ่งรวมถึงสิทธิ์เข้าถึงแบบเต็มเพื่อส่งที่เก็บ GitHub ที่เกี่ยวข้อง การได้รับสิทธิ์เข้าถึงเพื่อส่ง Bazel เองเป็นกระบวนการที่ซับซ้อนกว่ามาก
ข้อเสียคือกระบวนการติดตั้งครั้งเดียวที่ซับซ้อนมากขึ้นสำหรับผู้ใช้ ซึ่งต้องคัดลอกและวางกฎลงในไฟล์ WORKSPACE ตามที่แสดงในส่วน README.md ด้านบน
เราเคยมีกฎทั้งหมดอยู่ในที่เก็บ Bazel (ภายใต้ //tools/build_rules หรือ //tools/build_defs) ปัจจุบันเรายังมีกฎ 2-3 ข้ออยู่ที่นั่น แต่กำลังดำเนินการย้ายกฎที่เหลือออก