หน้านี้มีไว้สำหรับผู้เขียนกฎที่วางแผนจะเผยแพร่กฎให้ผู้อื่นใช้
กฎเกี่ยวกับการโฮสต์และการตั้งชื่อ
กฎใหม่ควรอยู่ในที่เก็บ GitHub ของตนเองภายใต้องค์กรของคุณ โปรดติดต่อรายชื่ออีเมลของ bazel-dev หากคิดว่ากฎของคุณควรอยู่ในองค์กร bazelbuild
ชื่อที่เก็บสำหรับกฎ Bazel จะเป็นรูปแบบมาตรฐานดังต่อไปนี้
$ORGANIZATION/rules_$NAME
ดูตัวอย่างใน GitHub
คุณต้องปฏิบัติตามรูปแบบเดียวกันนี้เมื่อเผยแพร่กฎ Bazel เพื่อให้สอดคล้องกัน
ตรวจสอบว่าคุณใช้คำอธิบายและREADME.mdชื่อที่เก็บ GitHub ที่สื่อความหมาย เช่น
- ชื่อที่เก็บ:
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
rules จะมีลักษณะดังนี้
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 (เช่น ใช้select)
ข้อจำกัดที่กำหนดเองช่วยให้คุณกำหนดภาษาที่ทั้งระบบนิเวศ Bazel จะใช้ได้
ไลบรารี Runfiles
หากกฎของคุณระบุไลบรารีมาตรฐานสําหรับการเข้าถึงไฟล์รันไทม์ กฎควรอยู่ในรูปแบบของเป้าหมายไลบรารีที่อยู่ที่ //<LANG>/runfiles (ชื่อย่อของ //<LANG>/runfiles:runfiles) โดยปกติแล้ว เป้าหมายผู้ใช้ที่จําเป็นต้องเข้าถึงข้อมูลที่เกี่ยวข้องจะเพิ่มเป้าหมายนี้ลงในแอตทริบิวต์ deps
กฎที่เก็บ
การอ้างอิง
กฎของคุณอาจมีทรัพยากร Dependency ภายนอก โปรดระบุมาโคร WORKSPACE ที่จะประกาศการอ้างอิงไปยังทรัพยากรภายนอกเหล่านั้นเพื่อให้การอ้างอิงกฎของคุณง่ายขึ้น อย่าประกาศการพึ่งพาของการทดสอบในนั้น ยกเว้นการพึ่งพาที่กฎกำหนดให้ทำงาน ใส่การพึ่งพาสำหรับการพัฒนาลงในไฟล์ WORKSPACE
สร้างไฟล์ชื่อ <LANG>/repositories.bzl และระบุมาโครที่มีจุดแรกเข้าเดียวชื่อ rules_<LANG>_dependencies ไดเรกทอรีจะมีลักษณะดังนี้
/
mockascript/
constraints/
BUILD
BUILD
defs.bzl
repositories.bzl
การลงทะเบียนชุดเครื่องมือ
กฎอาจลงทะเบียนเครื่องมือทางเทคนิคด้วย โปรดระบุWORKSPACE
มาโครแยกต่างหากที่ลงทะเบียนเครื่องมือเหล่านี้ วิธีนี้ช่วยให้ผู้ใช้ตัดสินใจได้ว่าจะไม่ใช้มาโครก่อนหน้าและควบคุมการพึ่งพาด้วยตนเองได้ ขณะที่ยังคงลงทะเบียนเครื่องมือทางเทคนิคได้
ดังนั้นให้เพิ่มมาโคร WORKSPACE ชื่อ rules_<LANG>_toolchains ลงในไฟล์ <LANG>/repositories.bzl
โปรดทราบว่า Bazel จะต้องวิเคราะห์เป้าหมาย toolchain ทั้งหมดที่ลงทะเบียนไว้เพื่อแก้ไขเครื่องมือในเฟสการวิเคราะห์ Bazel จะไม่จําเป็นต้องวิเคราะห์เป้าหมายทั้งหมดที่แอตทริบิวต์ toolchain.toolchain อ้างอิง หากต้องการลงทะเบียนชุดเครื่องมือ คุณต้องดำเนินการคํานวณที่ซับซ้อนในที่เก็บข้อมูล ให้ลองแยกที่เก็บข้อมูลที่มีเป้าหมาย toolchain ออกจากที่เก็บข้อมูลที่มีเป้าหมาย <LANG>_toolchain ระบบจะดึงข้อมูลรายการแรกเสมอ และดึงข้อมูลรายการที่ 2 เมื่อผู้ใช้ต้องการสร้างโค้ด <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
คำถามที่พบบ่อย
เหตุใดเราจึงเพิ่มกฎของเราไปยังที่เก็บ GitHub หลักของ Bazel ไม่ได้
เราต้องการแยกกฎออกจากรุ่น Bazel ให้ได้มากที่สุด ช่วยให้ทราบได้ชัดเจนขึ้นว่าใครเป็นเจ้าของกฎแต่ละข้อ ซึ่งจะช่วยลดภาระของนักพัฒนาซอฟต์แวร์ Bazel สำหรับการแยกการเชื่อมโยง ผู้ใช้จะแก้ไข อัปเกรด ดาวน์เกรด และแทนที่กฎได้ง่ายขึ้น การมีส่วนร่วมในกฎอาจง่ายกว่าการมีส่วนร่วมใน Bazel ทั้งนี้ขึ้นอยู่กับกฎ รวมถึงสิทธิ์เข้าถึงแบบเต็มในการส่งไปยังที่เก็บ GitHub ที่เกี่ยวข้อง การรับสิทธิ์ส่งไปยัง Bazel นั้นเป็นเรื่องซับซ้อนกว่ามาก
ข้อเสียคือกระบวนการติดตั้งแบบครั้งเดียวที่ซับซ้อนขึ้นสำหรับผู้ใช้ของเรา ผู้ใช้ต้องคัดลอกและวางกฎลงในไฟล์ WORKSPACE ดังที่แสดงในส่วน README.md ด้านบน
ก่อนหน้านี้เรามีกฎทั้งหมดอยู่ในที่เก็บ Bazel (ในส่วน //tools/build_rules หรือ //tools/build_defs) ตอนนี้ยังมีกฎอยู่ 2-3 ข้อ แต่เรากำลังดำเนินการย้ายกฎที่เหลือออก