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

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

เราขอแนะนำให้คุณเริ่มชุดกฎใหม่จากที่เก็บเทมเพลต ดังนี้ 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 ที่ดาวน์โหลดข้อกำหนดทั้งหมด (ดู 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

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

กฎที่เก็บ

การอ้างอิง

กฎของคุณอาจมีทรัพยากร Dependency ภายนอก โปรดระบุมาโคร WORKSPACE ที่จะประกาศทรัพยากร Dependency ของทรัพยากร Dependency ภายนอกเพื่อให้ ขึ้นอยู่กับกฎง่ายขึ้น อย่าประกาศทรัพยากร Dependency ของการทดสอบที่นั่น แต่ให้ประกาศเฉพาะการขึ้นต่อกันที่กฎกำหนดให้ทำงาน ใส่การอ้างอิงสำหรับการพัฒนาลงในไฟล์ WORKSPACE

สร้างไฟล์ชื่อ <LANG>/repositories.bzl และระบุมาโครจุดเข้าถึง 1 ตัวชื่อ rules_<LANG>_dependencies ไดเรกทอรีจะมีลักษณะดังนี้

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

กำลังลงทะเบียน Toolchain

กฎอาจลงทะเบียนเครื่องมือทางเทคนิคด้วย โปรดระบุมาโคร WORKSPACE แยกต่างหากที่ลงทะเบียน Toolchain เหล่านี้ วิธีนี้จะช่วยให้ผู้ใช้เลือกละเว้นมาโครก่อนหน้าและควบคุมทรัพยากร Dependency ด้วยตนเองได้ในขณะที่ยังคงได้รับอนุญาตให้ลงทะเบียน Toolchain

ดังนั้นให้เพิ่มมาโคร WORKSPACE ชื่อ rules_<LANG>_toolchains ลงในไฟล์ <LANG>/repositories.bzl

โปรดทราบว่า Bazel ต้องวิเคราะห์เป้าหมาย toolchain ทั้งหมดที่ลงทะเบียนไว้ เพื่อแก้ไข Toolchain ในระยะการวิเคราะห์ Bazel จะไม่จําเป็นต้องวิเคราะห์เป้าหมายทั้งหมดที่แอตทริบิวต์ toolchain.toolchain อ้างอิง หากต้องการลงทะเบียน Toolchain จำเป็นต้องทำการคำนวณที่ซับซ้อนในที่เก็บ ให้ลองแยกที่เก็บที่มีเป้าหมาย toolchain จากที่เก็บที่มีเป้าหมาย <LANG>_toolchain ระบบจะดึงข้อมูล URL ก่อนหน้าเสมอ และจะดึงข้อมูลรายการก่อนหน้าเมื่อผู้ใช้ต้องการสร้างโค้ด <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 org 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-3 ข้อ แต่กำลังดำเนินการย้ายกฎที่เหลือออก