ส่วนขยายโมดูลช่วยให้ผู้ใช้ขยายระบบโมดูลได้โดยการอ่านข้อมูลอินพุตจากโมดูลต่างๆ ในกราฟทรัพยากร Dependency ดำเนินการตรรกะที่จำเป็นเพื่อแก้ไขทรัพยากร Dependency และสุดท้ายสร้างที่เก็บด้วยการเรียกใช้กฎที่เก็บ ส่วนขยายเหล่านี้มีความสามารถคล้ายกับกฎของรีโป ซึ่งช่วยให้สามารถดำเนินการ I/O ของไฟล์ ส่งคำขอเครือข่าย และอื่นๆ ได้ นอกเหนือจากการดำเนินการอื่นๆ แล้ว โมดูลเหล่านี้ยังช่วยให้ Bazel โต้ตอบกับระบบการจัดการแพ็กเกจอื่นๆ ไปพร้อมกับการเคารพกราฟความเกี่ยวข้องที่สร้างขึ้นจากโมดูล Bazel
คุณสามารถกำหนดส่วนขยายของโมดูลในไฟล์ .bzl ได้เช่นเดียวกับกฎของที่เก็บ แท็กเหล่านี้จะไม่เรียกใช้โดยตรง แต่โมดูลจะระบุข้อมูลที่เรียกว่าแท็กเพื่อให้ส่วนขยายอ่าน Bazel เรียกใช้ความละเอียดของโมดูลก่อนประเมินส่วนขยายใดๆ ส่วนขยายจะอ่านแท็กทั้งหมดที่เป็นของส่วนขยายนั้นในกราฟความเกี่ยวข้องทั้งหมด
การใช้ส่วนขยาย
ส่วนขยายจะโฮสต์อยู่ในโมดูล Bazel ด้วยตนเอง หากต้องการใช้ส่วนขยายในข้อบังคับ ให้เพิ่ม bazel_dep ในข้อบังคับที่โฮสต์ส่วนขยายก่อน จากนั้นเรียกใช้ฟังก์ชันในตัว use_extension เพื่อนำส่วนขยายเข้ามาอยู่ในขอบเขต ลองดูตัวอย่างต่อไปนี้ ซึ่งเป็นข้อมูลโค้ดจากไฟล์ MODULE.bazel เพื่อใช้ส่วนขยาย "maven" ที่กำหนดไว้ในโมดูล rules_jvm_external
bazel_dep(name = "rules_jvm_external", version = "4.5")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
ซึ่งจะเชื่อมโยงค่าที่แสดงผลของ use_extension กับตัวแปร ซึ่งช่วยให้ผู้ใช้ใช้ไวยากรณ์จุดเพื่อระบุแท็กสําหรับส่วนขยายได้ แท็กต้องเป็นไปตามสคีมาที่กำหนดโดยคลาสแท็กที่เกี่ยวข้องซึ่งระบุไว้ในคำจำกัดความของส่วนขยาย เช่น การระบุแท็ก maven.install และ maven.artifact บางรายการ
maven.install(artifacts = ["org.junit:junit:4.13.2"])
maven.artifact(group = "com.google.guava",
artifact = "guava",
version = "27.0-jre",
exclusions = ["com.google.j2objc:j2objc-annotations"])
ใช้คำสั่ง use_repo เพื่อนําที่เก็บข้อมูลที่สร้างขึ้นโดยส่วนขยายมาไว้ในขอบเขตของโมดูลปัจจุบัน
use_repo(maven, "maven")
Repo ที่สร้างขึ้นโดยส่วนขยายเป็นส่วนหนึ่งของ API ของส่วนขยายนั้น ในตัวอย่างนี้ ส่วนขยายโมดูล "maven" สัญญาว่าจะสร้างที่เก็บชื่อ maven จากประกาศข้างต้น ส่วนขยายจะแก้ไขป้ายกํากับได้อย่างเหมาะสม เช่น @maven//:org_junit_junit ให้ชี้ไปยังที่เก็บที่สร้างโดยส่วนขยาย "maven"
คําจํากัดความของส่วนขยาย
คุณสามารถกำหนดส่วนขยายของโมดูลได้เช่นเดียวกับกฎของรีโปโดยใช้ฟังก์ชัน module_extension อย่างไรก็ตาม แม้ว่ากฎที่เก็บจะมีแอตทริบิวต์จำนวนหนึ่ง แต่ส่วนขยายโมดูลจะมี tag_class ซึ่งแต่ละรายการจะมีแอตทริบิวต์จำนวนหนึ่ง คลาสแท็กจะกําหนดสคีมาสําหรับแท็กที่ใช้โดยส่วนขยายนี้ ตัวอย่างเช่น ส่วนขยาย "maven" ด้านบนอาจกำหนดไว้ดังต่อไปนี้
# @rules_jvm_external//:extensions.bzl
_install = tag_class(attrs = {"artifacts": attr.string_list(), ...})
_artifact = tag_class(attrs = {"group": attr.string(), "artifact": attr.string(), ...})
maven = module_extension(
implementation = _maven_impl,
tag_classes = {"install": _install, "artifact": _artifact},
)
การประกาศเหล่านี้แสดงให้เห็นว่าสามารถระบุแท็ก maven.install และ maven.artifact โดยใช้สคีมาแอตทริบิวต์ที่ระบุ
ฟังก์ชันการใช้งานส่วนขยายโมดูลคล้ายกับกฎที่เก็บ เว้นแต่ว่าจะได้รับออบเจ็กต์ module_ctx ซึ่งให้สิทธิ์เข้าถึงโมดูลทั้งหมดที่ใช้ส่วนขยายและแท็กที่เกี่ยวข้องทั้งหมด
จากนั้นฟังก์ชันการใช้งานจะเรียกใช้กฎของ repo เพื่อสร้าง repo
# @rules_jvm_external//:extensions.bzl
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") # a repo rule
def _maven_impl(ctx):
# This is a fake implementation for demonstration purposes only
# collect artifacts from across the dependency graph
artifacts = []
for mod in ctx.modules:
for install in mod.tags.install:
artifacts += install.artifacts
artifacts += [_to_artifact(artifact) for artifact in mod.tags.artifact]
# call out to the coursier CLI tool to resolve dependencies
output = ctx.execute(["coursier", "resolve", artifacts])
repo_attrs = _process_coursier_output(output)
# call repo rules to generate repos
for attrs in repo_attrs:
http_file(**attrs)
_generate_hub_repo(name = "maven", repo_attrs)
ข้อมูลประจำตัวส่วนขยาย
ส่วนขยายของโมดูลจะระบุด้วยชื่อและไฟล์ .bzl ที่ปรากฏในการเรียกใช้ use_extension ในตัวอย่างต่อไปนี้ ส่วนขยาย maven จะระบุโดยไฟล์ .bzl @rules_jvm_external//:extension.bzl และชื่อ maven
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
การส่งออกส่วนขยายอีกครั้งจากไฟล์ .bzl อื่นจะทำให้ส่วนขยายมีข้อมูลระบุใหม่ และหากมีการใช้ทั้ง 2 เวอร์ชันของส่วนขยายในกราฟโมดูลแบบทรานซิทีฟ ระบบจะประเมินแยกกันและจะเห็นเฉพาะแท็กที่เชื่อมโยงกับข้อมูลระบุนั้น
ในฐานะผู้เขียนส่วนขยาย คุณควรตรวจสอบว่าผู้ใช้จะใช้ส่วนขยายโมดูลจากไฟล์ .bzl ไฟล์เดียวเท่านั้น
ชื่อและระดับการเข้าถึงที่เก็บ
Repo ที่สร้างขึ้นโดยส่วนขยายจะมีชื่อตามแบบฉบับในรูปแบบ module_repo_canonical_name~extension_name~repo_name สําหรับส่วนขยายที่โฮสต์ในไฟล์ .js ของโมดูลรูท ระบบจะแทนที่ส่วน module_repo_canonical_name ด้วยสตริง _main โปรดทราบว่ารูปแบบของชื่อ Canonical ไม่ใช่ API ที่คุณควรใช้ เนื่องจากอาจเปลี่ยนแปลงได้ตลอดเวลา
นโยบายการตั้งชื่อนี้หมายความว่าส่วนขยายแต่ละรายการจะมี "เนมสเปซของที่เก็บข้อมูล" ของตัวเอง ส่วนขยาย 2 รายการที่แตกต่างกันจะกำหนดที่เก็บข้อมูลที่มีชื่อเดียวกันได้โดยไม่เสี่ยงต่อการทับซ้อนกัน นอกจากนี้ยังหมายความว่า repository_ctx.name รายงานชื่อ Canonical ของที่เก็บ ซึ่งไม่เหมือนกับชื่อที่ระบุในการเรียกกฎที่เก็บ
การพิจารณาที่เก็บข้อมูลที่สร้างขึ้นโดยส่วนขยายโมดูลมีกฎการแสดงผลที่เก็บข้อมูลหลายข้อดังนี้
- ที่เก็บโมดูล Bazel สามารถดูที่เก็บทั้งหมดที่แนะนำในไฟล์
MODULE.bazelผ่านbazel_depและuse_repoได้ - รีโปที่สร้างขึ้นโดยส่วนขยายโมดูลจะดูรีโปทั้งหมดที่มองเห็นได้ของโมดูลที่โฮสต์ส่วนขยายได้ รวมถึงรีโปอื่นๆ ทั้งหมดที่สร้างขึ้นโดยส่วนขยายโมดูลเดียวกัน (โดยใช้ชื่อที่ระบุในการเรียกใช้กฎของรีโปเป็นชื่อที่ปรากฏ)
- ซึ่งอาจทำให้เกิดข้อขัดแย้ง หากที่เก็บโมดูลเห็นที่เก็บที่ใช้ชื่อ
fooอย่างชัดเจน และส่วนขยายสร้างที่เก็บที่มีชื่อที่ระบุfooที่เก็บทั้งหมดที่สร้างขึ้นโดยส่วนขยายนั้นfooจะหมายถึงที่เก็บเก่า
- ซึ่งอาจทำให้เกิดข้อขัดแย้ง หากที่เก็บโมดูลเห็นที่เก็บที่ใช้ชื่อ
- ในทำนองเดียวกัน ในฟังก์ชันการใช้งานของส่วนขยายโมดูล Repos ที่ส่วนขยายสร้างขึ้นสามารถอ้างอิงกันและกันด้วยชื่อที่ปรากฏในแอตทริบิวต์ ไม่ว่าจะสร้างขึ้นในลำดับใดก็ตาม
- ในกรณีที่มีความขัดแย้งกับที่เก็บข้อมูลที่แสดงต่อโมดูล คุณสามารถรวมป้ายกำกับที่ส่งไปยังแอตทริบิวต์กฎของที่เก็บไว้ในการเรียกใช้
Labelเพื่อให้แน่ใจว่าป้ายกำกับดังกล่าวอ้างอิงถึงที่เก็บข้อมูลที่แสดงต่อโมดูลแทนที่เก็บข้อมูลที่สร้างขึ้นจากส่วนขยายซึ่งมีชื่อเดียวกัน
- ในกรณีที่มีความขัดแย้งกับที่เก็บข้อมูลที่แสดงต่อโมดูล คุณสามารถรวมป้ายกำกับที่ส่งไปยังแอตทริบิวต์กฎของที่เก็บไว้ในการเรียกใช้
การลบล้างและการแทรกที่เก็บส่วนขยายโมดูล
โมดูลรูทสามารถใช้ override_repo และ inject_repo เพื่อลบล้างหรือแทรกที่เก็บส่วนขยายของโมดูล
ตัวอย่าง: การแทนที่ java_tools ของ rules_java ด้วยสำเนาของผู้ให้บริการ
# MODULE.bazel
local_repository = use_repo_rule("@bazel_tools//tools/build_defs/repo:local.bzl", "local_repository")
local_repository(
name = "my_java_tools",
path = "vendor/java_tools",
)
bazel_dep(name = "rules_java", version = "7.11.1")
java_toolchains = use_extension("@rules_java//java:extension.bzl", "toolchains")
override_repo(java_toolchains, remote_java_tools = "my_java_tools")
ตัวอย่าง: แพตช์ทรัพยากร Dependency ของ Go เพื่อพึ่งพา @zlib แทน zlib ของระบบ
# MODULE.bazel
bazel_dep(name = "gazelle", version = "0.38.0")
bazel_dep(name = "zlib", version = "1.3.1.bcr.3")
go_deps = use_extension("@gazelle//:extensions.bzl", "go_deps")
go_deps.from_file(go_mod = "//:go.mod")
go_deps.module_override(
patches = [
"//patches:my_module_zlib.patch",
],
path = "example.com/my_module",
)
use_repo(go_deps, ...)
inject_repo(go_deps, "zlib")
# patches/my_module_zlib.patch
--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -1,6 +1,6 @@
go_binary(
name = "my_module",
importpath = "example.com/my_module",
srcs = ["my_module.go"],
- copts = ["-lz"],
+ cdeps = ["@zlib"],
)
แนวทางปฏิบัติแนะนำ
ส่วนนี้จะอธิบายแนวทางปฏิบัติแนะนำในการเขียนส่วนขยายเพื่อให้ใช้งาน บำรุงรักษา และปรับให้เข้ากับการเปลี่ยนแปลงเมื่อเวลาผ่านไปได้ง่าย
ใส่ส่วนขยายแต่ละรายการในไฟล์แยกกัน
เมื่อส่วนขยายอยู่ในไฟล์ที่ต่างกัน ส่วนขยายหนึ่งจะอนุญาตให้ส่วนขยายหนึ่งโหลดที่เก็บที่สร้างขึ้นโดยส่วนขยายอื่นได้ แม้ว่าคุณจะไม่ได้ใช้ฟังก์ชันนี้ แต่คุณควรใส่ไฟล์เหล่านั้นไว้ในไฟล์แยกต่างหากในกรณีที่จำเป็นต้องใช้ในภายหลัง นั่นเป็นเพราะการระบุส่วนขยายนั้นอิงตามไฟล์ ดังนั้นการย้ายส่วนขยายไปยังไฟล์อื่นในภายหลังจะเปลี่ยน API สาธารณะของคุณ และเป็นการเปลี่ยนแปลงที่เข้ากันไม่ได้แบบย้อนหลังสำหรับผู้ใช้
ระบุความสามารถในการทำซ้ำ
หากส่วนขยายกำหนดที่เก็บข้อมูลเดียวกันเสมอเมื่อมีอินพุตเดียวกัน (แท็กส่วนขยาย ไฟล์ที่อ่าน ฯลฯ) และโดยเฉพาะอย่างยิ่งไม่ได้ใช้การดาวน์โหลดที่ไม่ได้ป้องกันโดยการตรวจสอบผลรวม ให้พิจารณาแสดงผล extension_metadata พร้อม reproducible = True ซึ่งจะช่วยให้ Bazel ข้ามส่วนขยายนี้เมื่อเขียนลงในไฟล์ล็อก
ระบุระบบปฏิบัติการและสถาปัตยกรรม
หากส่วนขยายใช้ระบบปฏิบัติการหรือประเภทสถาปัตยกรรมของระบบปฏิบัติการ ให้ระบุข้อมูลนี้ในการกำหนดค่าส่วนขยายโดยใช้แอตทริบิวต์บูลีน os_dependent และ arch_dependent วิธีนี้ช่วยให้ Bazel ตระหนักถึงความจำเป็นในการประเมินซ้ำหากมีการเปลี่ยนแปลงสิ่งใดสิ่งหนึ่ง
เนื่องจากการพึ่งพาโฮสต์ประเภทนี้ทำให้การดูแลรักษารายการล็อกไฟล์สำหรับส่วนขยายนี้ทำได้ยากขึ้น ให้พิจารณาทำเครื่องหมายส่วนขยายนั้นซ้ำได้หากเป็นไปได้
เฉพาะโมดูลรูทเท่านั้นที่จะมีผลต่อชื่อที่เก็บโดยตรง
โปรดทราบว่าเมื่อส่วนขยายสร้างที่เก็บ ที่เก็บจะสร้างขึ้นภายในเนมสเปซของส่วนขยาย ซึ่งหมายความว่าอาจเกิดข้อขัดแย้งขึ้นหากโมดูลต่างๆ ใช้ส่วนขยายเดียวกันและสร้างที่เก็บข้อมูลที่มีชื่อเดียวกัน ซึ่งมักจะปรากฏเป็น tag_class ของส่วนขยายโมดูลที่มีอาร์กิวเมนต์ name ที่ส่งผ่านเป็นค่า name ของกฎที่เก็บ
ตัวอย่างเช่น สมมติว่าโมดูลรูท A ขึ้นอยู่กับโมดูล B โมดูลทั้ง 2 รายการขึ้นอยู่กับโมดูล mylang หากทั้ง A และ B เรียกใช้ mylang.toolchain(name="foo") ทั้ง 2 รายการจะพยายามสร้างที่เก็บข้อมูลที่ชื่อ foo ภายในโมดูล mylang และจะเกิดข้อผิดพลาด
วิธีหลีกเลี่ยงปัญหานี้คือ ให้นำความสามารถในการตั้งชื่อที่เก็บโดยตรงออก หรืออนุญาตให้เฉพาะโมดูลรูทเท่านั้นที่ดำเนินการดังกล่าวได้ การให้สิทธิ์นี้แก่โมดูลรูทนั้นไม่มีปัญหา เนื่องจากไม่มีโมดูลใดต้องอาศัยโมดูลนี้ จึงไม่ต้องกังวลว่าโมดูลอื่นจะสร้างชื่อที่ทับซ้อนกัน