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

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

กฎการโฮสต์และการตั้งชื่อ

กฎใหม่ควรอยู่ในที่เก็บ GitHub ของตัวเองภายใต้องค์กรของคุณ โปรดติดต่อรายชื่ออีเมล bazel-dev หากคุณคิดว่ากฎของคุณควรอยู่ในองค์กร 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) ได้

เนื้อหาที่เก็บ

ที่เก็บกฎทุกรายการควรมีเลย์เอาต์ที่แน่นอนเพื่อให้ผู้ใช้เข้าใจกฎใหม่ได้อย่างรวดเร็ว

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

การทดสอบ

ตั้งค่า Travis ตามที่อธิบายไว้ในเอกสารประกอบการเริ่มต้นใช้งาน จากนั้นเพิ่มไฟล์ .travis.yml ลงในที่เก็บด้วยเนื้อหาต่อไปนี้

dist: xenial  # Ubuntu 16.04

# On trusty (or later) images, the Bazel apt repository can be used.
addons:
  apt:
    sources:
    - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
      key_url: 'https://bazel.build/bazel-release.pub.gpg'
    packages:
    - bazel

script:
  - bazel build //...
  - bazel test //...

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

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

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

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

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

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

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

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