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

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

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