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

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

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

MODULE.bazel

ใน MODULE.bazel ของโปรเจ็กต์ คุณควรกำหนดชื่อที่ผู้ใช้จะใช้ เพื่ออ้างอิงกฎของคุณ หากกฎของคุณอยู่ในองค์กร bazelbuild คุณต้องใช้ rules_<lang> (เช่น rules_mockascript) ไม่เช่นนั้น คุณควรตั้งชื่อที่เก็บว่า <org>_rules_<lang> (เช่น build_stack_rules_proto) โปรดเริ่ม เธรดใน GitHub หากคุณคิดว่ากฎของคุณควรเป็นไปตามรูปแบบสำหรับกฎในองค์กร bazelbuild

ในส่วนต่อไปนี้ ให้ถือว่าที่เก็บเป็นขององค์กร bazelbuild

module(name = "rules_mockascript")

README

ที่ระดับบนสุดควรมี README ซึ่งมีคำอธิบายสั้นๆ ของชุดกฎและ API ที่ผู้ใช้ควรคาดหวัง

กฎ

โดยปกติแล้วที่เก็บจะระบุกฎหลายข้อ สร้างไดเรกทอรีที่ตั้งชื่อตามภาษาและระบุจุดแรกเข้า - defs.bzl file exporting all rules (also include a BUILD file so the directory is a package) สำหรับ 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

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

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

กฎของคุณอาจมีการอ้างอิงภายนอก ซึ่งคุณจะต้องระบุในไฟล์ MODULE.bazel

การลงทะเบียน Toolchain

กฎอาจลงทะเบียน Toolchain ด้วย ซึ่งคุณระบุได้ในไฟล์ MODULE.bazel

โปรดทราบว่า Bazel ต้องวิเคราะห์toolchainเป้าหมายทั้งหมดที่ลงทะเบียนไว้เพื่อแก้ไข Toolchain ในระยะการวิเคราะห์ Bazel ไม่จำเป็นต้อง วิเคราะห์เป้าหมายทั้งหมดที่แอตทริบิวต์ toolchain.toolchain อ้างอิง หากต้องการลงทะเบียน Toolchain คุณต้องทำการคำนวณที่ซับซ้อนในที่เก็บ ให้พิจารณาแยกที่เก็บที่มีเป้าหมาย toolchain ออกจากที่เก็บที่มีเป้าหมาย <LANG>_toolchain ระบบจะดึงข้อมูลรายการแรกเสมอ และจะดึงข้อมูลรายการที่สองเมื่อผู้ใช้ต้องการสร้าง<LANG>โค้ดจริงๆ เท่านั้น

ตัวอย่างผลงาน

ในการประกาศการเปิดตัว ให้ระบุข้อมูลโค้ดที่ผู้ใช้สามารถคัดลอกและวาง ลงในไฟล์ MODULE.bazel ได้ โดยทั่วไปแล้วข้อมูลโค้ดนี้จะมีลักษณะดังนี้

bazel_dep(name = "rules_<LANG>", version = "<VERSION>")

การทดสอบ

ควรมีการทดสอบที่ยืนยันว่ากฎทำงานได้ตามที่คาดไว้ ซึ่งอาจอยู่ในตำแหน่งมาตรฐานสำหรับภาษาที่ใช้ในกฎหรือtests/ ไดเรกทอรีที่ระดับบนสุด

ตัวอย่าง (ไม่บังคับ)

examples/ ไดเรกทอรีที่แสดงวิธีพื้นฐาน 2-3 วิธีในการใช้กฎจะเป็นประโยชน์ต่อผู้ใช้

CI/CD

ชุดกฎจำนวนมากใช้ GitHub Actions ดูการกำหนดค่าที่ใช้ในที่เก็บ rules-template ซึ่งได้รับการปรับให้ง่ายขึ้นโดยใช้ "เวิร์กโฟลว์ที่นำมาใช้ใหม่ได้" ที่โฮสต์ใน bazel-contrib org ci.yaml จะเรียกใช้การทดสอบในแต่ละคำขอส่งรวม (PR) และmain คอมมิต และrelease.yaml จะเรียกใช้ทุกครั้งที่คุณพุชแท็กไปยังที่เก็บ ดูข้อมูลเพิ่มเติมได้ที่ความคิดเห็นในที่เก็บกฎ-เทมเพลต

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

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

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

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

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

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

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

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

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