สำหรับเอกสารรุ่นที่เสถียร โปรดใช้รายการแบบเลื่อนลง "เอกสารที่มีเวอร์ชัน" มุมมองเริ่มต้นจะแสดงเวอร์ชันล่าสุดที่ HEAD

หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

เราขอแนะนำให้คุณเริ่มต้นชุดกฎใหม่จากที่เก็บเทมเพลตดังนี้ 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 เพื่อใช้กฎ โดยทั่วไป URL นี้จะเป็น 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 ของตน (เช่น การใช้ตัวเลือก) ข้อจำกัดที่กำหนดเองช่วยให้คุณกำหนดภาษาที่ทั้งระบบนิเวศของ Bazel จะใช้สื่อสาร

ไลบรารี Runfiles

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

กฎที่เก็บ

การอ้างอิง

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

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

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

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

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

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

โปรดทราบว่า Bazel ต้องวิเคราะห์เป้าหมาย toolchain ทั้งหมดที่ลงทะเบียนไว้ก่อนที่จะแก้ไขเชนเครื่องมือในขั้นตอนการวิเคราะห์ Bazel ไม่จำเป็นต้องวิเคราะห์เป้าหมายทั้งหมดที่อ้างอิงโดยแอตทริบิวต์ 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 Actions ดูการกำหนดค่าที่ใช้ในที่เก็บเทมเพลตกฎ ซึ่งง่ายขึ้นโดยใช้ "เวิร์กโฟลว์ที่นำกลับมาใช้ใหม่ได้" ซึ่งโฮสต์ในองค์กร bazel-contrib ci.yaml เรียกใช้การทดสอบใน PR และ main แต่ละรายการ และ release.yaml จะทำงานทุกครั้งที่คุณพุชแท็กไปยังที่เก็บ ดูความคิดเห็นในที่เก็บเทมเพลตกฎสำหรับข้อมูลเพิ่มเติม

หากที่เก็บอยู่ภายใต้องค์กร bazelbuild คุณสามารถขอเพิ่มที่เก็บดังกล่าวลงใน ci.bazel.build ได้

เอกสารประกอบ

ดูวิธีการแสดงความคิดเห็นเกี่ยวกับกฎได้ในเอกสารประกอบของ Stardoc เพื่อให้สร้างเอกสารได้โดยอัตโนมัติ

โฟลเดอร์เอกสาร/ เทมเพลตกฎ แสดงวิธีง่ายๆ ในการตรวจสอบว่าเนื้อหา Markdown ในโฟลเดอร์ docs/ เป็นเวอร์ชันล่าสุดอยู่เสมอ เมื่อมีการอัปเดตไฟล์ Starlark

คำถามที่พบบ่อย

เหตุใดเราจึงเพิ่มกฎไปยังที่เก็บ Bazel GitHub หลักไม่ได้

เราต้องการแยกกฎจากการเผยแพร่ของ Bazel ออกให้มากที่สุดเท่าที่จะเป็นไปได้ ใครเป็นเจ้าของกฎแต่ละข้อจะชัดเจนกว่า ซึ่งช่วยลดภาระของนักพัฒนาซอฟต์แวร์ Bazel สำหรับผู้ใช้ของเรา การแยกทำให้แก้ไข อัปเกรด ดาวน์เกรด และแทนที่กฎได้ง่ายขึ้น การมีส่วนร่วมในกฎอาจมีน้ำหนักน้อยกว่าการมีส่วนร่วมใน Bazel ทั้งนี้ขึ้นอยู่กับกฎ รวมถึงสิทธิ์การส่งเต็มรูปแบบสำหรับที่เก็บ GitHub ที่เกี่ยวข้อง การขอสิทธิ์เข้าถึง Bazel เป็นกระบวนการที่เกี่ยวข้องมากกว่ามาก

ข้อเสียคือขั้นตอนการติดตั้งแบบครั้งเดียวที่ซับซ้อนมากขึ้นสำหรับผู้ใช้ของเรา กล่าวคือ ต้องคัดลอกและวางกฎลงในไฟล์ WORKSPACE ดังที่แสดงในส่วน README.md ด้านบน

เราเคยมีกฎทั้งหมดในที่เก็บ Bazel (ภายใต้ //tools/build_rules หรือ //tools/build_defs) เรายังมีกฎ 2-3 ข้ออยู่ แต่เรากำลังดำเนินการย้ายกฎที่เหลือออกไป