หน้านี้มีไว้สำหรับผู้เขียนกฎที่วางแผนจะทำให้ผู้อื่นใช้กฎของตน
กฎโฮสติ้งและการตั้งชื่อ
กฎใหม่ควรอยู่ในที่เก็บ 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 ของโปรเจ็กต์ คุณควรกำหนดชื่อที่ผู้ใช้จะใช้เพื่ออ้างอิงกฎของคุณ หากกฎของคุณเป็นขององค์กร 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 ที่จะดาวน์โหลดทรัพยากร 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 ของการพัฒนาลงในไฟล์ WORKSPACE
สร้างไฟล์ชื่อ <LANG>/repositories.bzl และระบุมาโครจุดแรกเข้า 1 ตัวชื่อ rules_<LANG>_dependencies ไดเรกทอรีของเราจะมีลักษณะดังนี้
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
กำลังลงทะเบียน Toolchain
นอกจากนี้ กฎของคุณยังอาจลงทะเบียน Toolchains ด้วย โปรดระบุมาโคร WORKSPACE แยกต่างหากที่ลงทะเบียน Toolchain เหล่านี้ วิธีนี้จะช่วยให้ผู้ใช้เลือกละเว้นมาโครก่อนหน้าและควบคุมทรัพยากร Dependency ด้วยตนเองได้ในขณะที่ยังคงได้รับอนุญาตให้ลงทะเบียน Toolchain
ดังนั้นให้เพิ่มมาโคร WORKSPACE ชื่อ rules_<LANG>_toolchains ลงในไฟล์ <LANG>/repositories.bzl
โปรดทราบว่า 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 วิธีในการใช้กฎนั้นมีประโยชน์สำหรับผู้ใช้
การทดสอบ
ตั้งค่า 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 ข้ออยู่ แต่กำลังพยายามนำกฎที่เหลือออก