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

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

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

ข้อจำกัด

หากกฎกำหนดกฎชุดเครื่องมือ คุณอาจต้องกำหนด constraint_setting และ/หรือ constraint_value ที่กำหนดเอง ใส่ข้อมูลเหล่านี้ลงใน//<LANG>/constraintsแพ็กเกจ โครงสร้างไดเรกทอรีจะมีลักษณะดังนี้

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

โปรดอ่านgithub.com/bazelbuild/platforms เพื่อดูแนวทางปฏิบัติแนะนำและดูข้อจำกัดที่มีอยู่แล้ว รวมถึง พิจารณาการมีส่วนร่วมในการเพิ่มข้อจำกัดของคุณที่นั่นหากข้อจำกัดนั้นไม่ขึ้นอยู่กับภาษา โปรดคำนึงถึงการกำหนดข้อจำกัดที่กำหนดเอง เนื่องจากผู้ใช้กฎทั้งหมดจะใช้ข้อจำกัดดังกล่าวเพื่อดำเนินการตรรกะเฉพาะแพลตฟอร์มในไฟล์ BUILD (เช่น การใช้ selects) ข้อจำกัดที่กำหนดเองช่วยให้คุณกำหนดภาษาที่ทั้งระบบนิเวศของ Bazel จะใช้ได้

ไลบรารีไฟล์รันไทม์

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

กฎของที่เก็บ

แท็กเริ่มการทำงาน

กฎอาจมีทรัพยากร Dependency ภายนอก โปรดระบุWORKSPACEมาโครที่จะประกาศการอ้างอิง การอ้างอิงภายนอกเหล่านั้น เพื่อให้การอ้างอิงกฎของคุณง่ายขึ้น อย่าประกาศการขึ้นต่อกันของการทดสอบที่นั่น ให้ประกาศเฉพาะการขึ้นต่อกันที่กฎกำหนดให้ทำงานเท่านั้น ใส่ทรัพยากร Dependency ในการพัฒนาลงในไฟล์ 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 org ci.yaml จะเรียกใช้การทดสอบในแต่ละคำขอส่งรวม (PR) และmain คอมมิต และrelease.yaml จะเรียกใช้ทุกครั้งที่คุณพุชแท็กไปยังที่เก็บ ดูข้อมูลเพิ่มเติมได้ที่ความคิดเห็นในที่เก็บเทมเพลตกฎ

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

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

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

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

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

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

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

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

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