เนื่องจากข้อบกพร่องของ Workspace ทำให้ Bzlmod จะมาแทนที่ระบบ WORKSPACE เดิมใน Bazel รุ่นต่อๆ ไป คำแนะนำนี้จะช่วยคุณย้ายข้อมูลโปรเจ็กต์ไปยัง Bzlmod และวาง WORKSPACE สำหรับการดึงข้อมูลทรัพยากร Dependency ภายนอก
WORKSPACE เทียบกับ Bzlmod
WORKSPACE และ Bzlmod ของ Bazel มีฟีเจอร์ที่คล้ายกันแต่มีไวยากรณ์ต่างกัน ส่วนนี้อธิบายวิธีย้ายข้อมูลจากฟังก์ชัน WORKSPACE ที่เฉพาะเจาะจงไปยัง Bzlmod
กําหนดรูทของพื้นที่ทำงาน Bazel
ไฟล์ WORKSPACE จะทำเครื่องหมายรูทต้นทางของโปรเจ็กต์ Bazel และจะแทนที่ความรับผิดชอบนี้ด้วย MODULE.bazel ใน Bazel เวอร์ชัน 6.3 ขึ้นไป เมื่อใช้ Bazel เวอร์ชันก่อน 6.3 ควรมีไฟล์ WORKSPACE
หรือ WORKSPACE.bazel
ที่รูทพื้นที่ทำงานของคุณ ซึ่งอาจมีความคิดเห็นอย่างเช่น
พื้นที่ทำงาน
# This file marks the root of the Bazel workspace. # See MODULE.bazel for external dependencies setup.
เปิดใช้ Bzlmod ใน bazelrc ของคุณ
.bazelrc
ช่วยให้คุณตั้งค่าแฟล็กที่มีผลทุกครั้งที่เรียกใช้ Bazel ได้ หากต้องการเปิดใช้ Bzlmod ให้ใช้แฟล็ก --enable_bzlmod
และนำไปใช้กับคำสั่ง common
เพื่อให้มีผลกับทุกคำสั่ง ดังนี้
.bazelrc
# Enable Bzlmod for every Bazel command common --enable_bzlmod
ระบุชื่อที่เก็บสำหรับพื้นที่ทำงาน
พื้นที่ทำงาน
ใช้ฟังก์ชัน
workspace
เพื่อระบุชื่อที่เก็บสำหรับพื้นที่ทำงานของคุณ ซึ่งจะช่วยให้อ้างอิง//foo:bar
เป้าหมายในพื้นที่ทำงานเป็น@<workspace name>//foo:bar
ได้ หากไม่ได้ระบุไว้ ชื่อที่เก็บเริ่มต้นสำหรับพื้นที่ทำงานของคุณคือ__main__
## WORKSPACE workspace(name = "com_foo_bar")
Bzlmod
ขอแนะนำให้อ้างอิงเป้าหมายในพื้นที่ทำงานเดียวกันด้วยไวยากรณ์
//foo:bar
ที่ไม่มี@<repo name>
แต่หากต้องการใช้ไวยากรณ์เดิม ก็ใช้ชื่อโมดูลที่ระบุโดยฟังก์ชันmodule
เป็นชื่อที่เก็บได้ หากชื่อโมดูลต่างจากชื่อที่เก็บที่จำเป็น คุณใช้แอตทริบิวต์repo_name
ของฟังก์ชันmodule
เพื่อลบล้างชื่อที่เก็บได้## MODULE.bazel module( name = "bar", repo_name = "com_foo_bar", )
ดึงข้อมูลทรัพยากร Dependency ภายนอกเป็นโมดูล Bazel
หากทรัพยากร Dependency ของคุณเป็นโปรเจ็กต์ Bazel คุณก็ควรพึ่งพาโปรเจ็กต์ดังกล่าวเป็นโมดูลของ Bazel ได้เมื่อมีการใช้ Bzlmod ด้วย
พื้นที่ทำงาน
ใน Workspace เป็นเรื่องปกติที่จะใช้กฎที่เก็บ
http_archive
หรือgit_repository
เพื่อดาวน์โหลดแหล่งที่มาของโปรเจ็กต์ Bazel## WORKSPACE load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") http_archive( name = "bazel_skylib", urls = ["https://github.com/bazelbuild/bazel-skylib/releases/download/1.4.2/bazel-skylib-1.4.2.tar.gz"], sha256 = "66ffd9315665bfaafc96b52278f57c7e2dd09f5ede279ea6d39b2be471e7e3aa", ) load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() http_archive( name = "rules_java", urls = ["https://github.com/bazelbuild/rules_java/releases/download/6.1.1/rules_java-6.1.1.tar.gz"], sha256 = "76402a50ae6859d50bd7aed8c1b8ef09dae5c1035bb3ca7d276f7f3ce659818a", ) load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains") rules_java_dependencies() rules_java_toolchains()
คุณจะเห็นได้ว่ารูปแบบนี้เป็นรูปแบบทั่วไปที่ผู้ใช้จะต้องโหลดการขึ้นต่อกันแบบทรานซิทีฟจากมาโครของทรัพยากร Dependency สมมติว่าทั้ง
bazel_skylib
และrules_java
ขึ้นอยู่กับplatform
เวอร์ชันที่แน่นอนของการอ้างอิงplatform
จะกำหนดโดยลำดับของมาโครBzlmod
เมื่อใช้ Bzlmod ตราบใดที่ทรัพยากร Dependency ของคุณมีอยู่ใน Bazel Central Registry หรือรีจิสทรี Bazel ที่กำหนดเอง คุณก็เพียงแค่ใช้ Dependency ได้โดยใช้คำสั่ง
bazel_dep
## MODULE.bazel bazel_dep(name = "bazel_skylib", version = "1.4.2") bazel_dep(name = "rules_java", version = "6.1.1")
Bzlmod แก้ไขทรัพยากร Dependency ของโมดูล Bazel แบบชั่วคราวโดยใช้อัลกอริทึม MVS ดังนั้น ระบบจะเลือก
platform
เวอร์ชันสูงสุดที่จำเป็นโดยอัตโนมัติ
ลบล้างการขึ้นต่อกันเป็นโมดูล Bazel
ในฐานะโมดูลรูท คุณลบล้างการขึ้นต่อกันของโมดูล Bazel ได้หลายวิธี
โปรดอ่านข้อมูลเพิ่มเติมในส่วนoverrides
คุณดูตัวอย่างการใช้ตัวอย่างได้ในที่เก็บตัวอย่าง
ดึงข้อมูลทรัพยากร Dependency ภายนอกด้วยส่วนขยายโมดูล
หากทรัพยากร Dependency ไม่ใช่โปรเจ็กต์ Bazel หรือยังไม่พร้อมใช้งานในรีจิสทรี Bazel ใดๆ คุณจะแนะนำโปรเจ็กต์ดังกล่าวได้โดยใช้ use_repo_rule
หรือส่วนขยายโมดูล
พื้นที่ทำงาน
ดาวน์โหลดไฟล์โดยใช้กฎที่เก็บ
http_file
## WORKSPACE load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") http_file( name = "data_file", url = "http://example.com/file", sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", )
Bzlmod
เมื่อใช้ Bzlmod คุณจะใช้คำสั่ง
use_repo_rule
ในไฟล์ MODULE.bazel เพื่อสร้างอินสแตนซ์ repos ได้โดยตรง โดยทำดังนี้## MODULE.bazel http_file = use_repo_rule("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") http_file( name = "data_file", url = "http://example.com/file", sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", )
ขั้นสูง สามารถดำเนินการโดยใช้ส่วนขยายโมดูล หากต้องการใช้ตรรกะที่ซับซ้อนกว่าการเรียกใช้กฎที่เก็บ คุณยังใช้ส่วนขยายโมดูลได้ด้วยตนเอง คุณจะต้องย้ายคำจำกัดความไปไว้ในไฟล์
.bzl
ซึ่งช่วยให้คุณแชร์คำจำกัดความระหว่าง Workspace และ Bzlmod ในระหว่างการย้ายข้อมูลได้ด้วย## repositories.bzl load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file") def my_data_dependency(): http_file( name = "data_file", url = "http://example.com/file", sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", )
ใช้ส่วนขยายโมดูลเพื่อโหลดมาโครทรัพยากร Dependency คุณจะกำหนดมาโครดังกล่าวในไฟล์
.bzl
เดียวกันก็ได้ แต่หากต้องการรักษาความเข้ากันได้กับ Bazel เวอร์ชันเก่า ควรกำหนดในไฟล์.bzl
แยกต่างหาก## extensions.bzl load("//:repositories.bzl", "my_data_dependency") def _non_module_dependencies_impl(_ctx): my_data_dependency() non_module_dependencies = module_extension( implementation = _non_module_dependencies_impl, )
หากต้องการทำให้ที่เก็บปรากฏแก่โปรเจ็กต์รูท คุณควรประกาศการใช้ส่วนขยายโมดูลและที่เก็บในไฟล์ MODULE.bazel
## MODULE.bazel non_module_dependencies = use_extension("//:extensions.bzl", "non_module_dependencies") use_repo(non_module_dependencies, "data_file")
แก้ไขทรัพยากร Dependency ภายนอกที่มีข้อขัดแย้งด้วยส่วนขยายโมดูล
โปรเจ็กต์จะมีมาโครที่แนะนำที่เก็บภายนอกตามอินพุตจากผู้โทรได้ แต่จะเกิดอะไรขึ้นหากมีผู้โทรหลายรายในกราฟการขึ้นต่อกันและ ทำให้เกิดการขัดแย้งกัน
สมมติว่าโปรเจ็กต์ foo
ระบุมาโครต่อไปนี้ซึ่งจะใช้ version
เป็นอาร์กิวเมนต์
## repositories.bzl in foo {:#repositories.bzl-foo}
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
def data_deps(version = "1.0"):
http_file(
name = "data_file",
url = "http://example.com/file-%s" % version,
# Omitting the "sha256" attribute for simplicity
)
พื้นที่ทำงาน
เมื่อใช้ WORKSPACE คุณโหลดมาโครจาก
@foo
และระบุเวอร์ชันของทรัพยากร Dependency ที่ต้องการได้ สมมติว่าคุณมีทรัพยากร Dependency อีก@bar
รายการที่ขึ้นอยู่กับ@foo
ด้วย แต่จำเป็นต้องใช้การขึ้นต่อข้อมูลเวอร์ชันอื่น## WORKSPACE # Introduce @foo and @bar. ... load("@foo//:repositories.bzl", "data_deps") data_deps(version = "2.0") load("@bar//:repositories.bzl", "bar_deps") bar_deps() # -> which calls data_deps(version = "3.0")
ในกรณีนี้ ผู้ใช้ปลายทางต้องปรับลำดับของมาโครใน Workspace อย่างระมัดระวังเพื่อให้ได้เวอร์ชันที่ต้องการ นี่เป็นปัญหาที่ใหญ่ที่สุดปัญหาหนึ่งของ WORKSPACE เนื่องจากไม่ได้ให้วิธีที่เหมาะสมในการแก้ปัญหาการพึ่งพากัน
Bzlmod
ผู้เขียนโปรเจ็กต์
foo
สามารถใช้ส่วนขยายโมดูลเพื่อแก้ไขข้อขัดแย้งได้ด้วย Bzlmod ตัวอย่างเช่น สมมติว่าควรเลือกเวอร์ชันสูงสุดของทรัพยากร Dependency ในโมดูล Bazel ทั้งหมดเสมอ## extensions.bzl in foo load("//:repositories.bzl", "data_deps") data = tag_class(attrs={"version": attr.string()}) def _data_deps_extension_impl(module_ctx): # Select the maximal required version in the dependency graph. version = "1.0" for mod in module_ctx.modules: for data in mod.tags.data: version = max(version, data.version) data_deps(version) data_deps_extension = module_extension( implementation = _data_deps_extension_impl, tag_classes = {"data": data}, )
## MODULE.bazel in bar bazel_dep(name = "foo", version = "1.0") foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension") foo_data_deps.data(version = "3.0") use_repo(foo_data_deps, "data_file")
## MODULE.bazel in root module bazel_dep(name = "foo", version = "1.0") bazel_dep(name = "bar", version = "1.0") foo_data_deps = use_extension("@foo//:extensions.bzl", "data_deps_extension") foo_data_deps.data(version = "2.0") use_repo(foo_data_deps, "data_file")
ในกรณีนี้ โมดูลรูทต้องใช้ข้อมูลเวอร์ชัน
2.0
ในขณะที่การขึ้นต่อกันbar
ต้องใช้3.0
ส่วนขยายโมดูลในfoo
จะแก้ไขความขัดแย้งนี้ได้อย่างถูกต้องและเลือกเวอร์ชัน3.0
สำหรับการขึ้นต่อข้อมูลโดยอัตโนมัติ
รวมตัวจัดการแพ็กเกจของบุคคลที่สาม
ในส่วนสุดท้าย เนื่องจากส่วนขยายโมดูลมีวิธีเก็บรวบรวมข้อมูลจากกราฟทรัพยากร Dependency จะใช้ตรรกะที่กำหนดเองเพื่อแก้ไขการขึ้นต่อกันและกฎที่เก็บการเรียกใช้เพื่อแนะนำที่เก็บภายนอก ซึ่งเป็นวิธีที่ยอดเยี่ยมสำหรับผู้เขียนกฎในการปรับปรุงชุดกฎที่ผสานรวมเครื่องมือจัดการแพ็กเกจสำหรับบางภาษา
โปรดอ่านหน้าส่วนขยายโมดูลเพื่อเรียนรู้เพิ่มเติมเกี่ยวกับวิธีใช้ส่วนขยายโมดูล
ต่อไปนี้คือรายการของชุดกฎที่ใช้ Bzlmod อยู่แล้วเพื่อดึงข้อมูลทรัพยากร Dependency จากผู้จัดการแพ็กเกจต่างๆ
ตัวอย่างขั้นต่ำที่ผสานรวมตัวจัดการแพ็กเกจเทียมจะมีอยู่ในที่เก็บ examples
ตรวจหา Toolchain ในเครื่องโฮสต์
เมื่อกฎบิลด์ของ Bazel ต้องตรวจหา Toolchain ที่พร้อมใช้งานในเครื่องของโฮสต์ กฎดังกล่าวจะใช้กฎที่เก็บเพื่อตรวจสอบเครื่องโฮสต์และสร้างข้อมูล Toolchain เป็นที่เก็บภายนอก
พื้นที่ทำงาน
ตรวจหาเครื่องมือเชนของ Shell ตามกฎที่เก็บต่อไปนี้
## local_config_sh.bzl def _sh_config_rule_impl(repository_ctx): sh_path = get_sh_path_from_env("SH_BIN_PATH") if not sh_path: sh_path = detect_sh_from_path() if not sh_path: sh_path = "/shell/binary/not/found" repository_ctx.file("BUILD", """ load("@bazel_tools//tools/sh:sh_toolchain.bzl", "sh_toolchain") sh_toolchain( name = "local_sh", path = "{sh_path}", visibility = ["//visibility:public"], ) toolchain( name = "local_sh_toolchain", toolchain = ":local_sh", toolchain_type = "@bazel_tools//tools/sh:toolchain_type", ) """.format(sh_path = sh_path)) sh_config_rule = repository_rule( environ = ["SH_BIN_PATH"], local = True, implementation = _sh_config_rule_impl, )
คุณโหลดกฎที่เก็บได้ใน WORKSPACE
## WORKSPACE load("//:local_config_sh.bzl", "sh_config_rule") sh_config_rule(name = "local_config_sh")
Bzlmod
เมื่อใช้ Bzlmod คุณจะแนะนำที่เก็บเดียวกันนี้ได้โดยใช้ส่วนขยายโมดูล ซึ่งคล้ายกับการแนะนำที่เก็บ
@data_file
ในส่วนสุดท้าย## local_config_sh_extension.bzl load("//:local_config_sh.bzl", "sh_config_rule") sh_config_extension = module_extension( implementation = lambda ctx: sh_config_rule(name = "local_config_sh"), )
จากนั้นใช้นามสกุลในไฟล์ MODULE.bazel
## MODULE.bazel sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension") use_repo(sh_config_ext, "local_config_sh")
ลงทะเบียนเครื่องมือเชนและแพลตฟอร์มการดำเนินการ
หลังจากส่วนสุดท้าย หลังจากแนะนำข้อมูล Toolchain ของที่เก็บ (เช่น local_config_sh
) คุณอาจต้องการลงทะเบียน Toolchain
พื้นที่ทำงาน
เมื่อใช้ WORKSPACE คุณจะลงทะเบียนเครื่องมือเชนได้ด้วยวิธีต่อไปนี้
คุณลงทะเบียนเครื่องมือเชนไฟล์
.bzl
และโหลดมาโครในไฟล์ WORKSPACE ได้## local_config_sh.bzl def sh_configure(): sh_config_rule(name = "local_config_sh") native.register_toolchains("@local_config_sh//:local_sh_toolchain")
## WORKSPACE load("//:local_config_sh.bzl", "sh_configure") sh_configure()
หรือลงทะเบียน Toolchain ในไฟล์ WORKSPACE โดยตรง
## WORKSPACE load("//:local_config_sh.bzl", "sh_config_rule") sh_config_rule(name = "local_config_sh") register_toolchains("@local_config_sh//:local_sh_toolchain")
Bzlmod
เมื่อใช้ Bzlmod แล้ว API ของ
register_toolchains
และregister_execution_platforms
จะพร้อมใช้งานในไฟล์ MODULE.bazel เท่านั้น คุณไม่สามารถเรียกใช้native.register_toolchains
ในส่วนขยายโมดูล## MODULE.bazel sh_config_ext = use_extension("//:local_config_sh_extension.bzl", "sh_config_extension") use_repo(sh_config_ext, "local_config_sh") register_toolchains("@local_config_sh//:local_sh_toolchain")
Toolchain และแพลตฟอร์มการดำเนินการที่จดทะเบียนใน WORKSPACE
, WORKSPACE.bzlmod
และไฟล์ MODULE.bazel
ของโมดูล Bazel แต่ละรายการจะมีลำดับความสําคัญสูงกว่าในระหว่างการเลือก Toolchain (จากมากไปน้อย) ดังนี้
- Toolchains และแพลตฟอร์มการดำเนินการที่ลงทะเบียนไว้ในไฟล์
MODULE.bazel
ของโมดูลรูท - Toolchains และแพลตฟอร์มการดำเนินการที่ลงทะเบียนในไฟล์
WORKSPACE
หรือWORKSPACE.bzlmod
- Toolchains และแพลตฟอร์มการดำเนินการที่ลงทะเบียนโดยโมดูลที่ขึ้นต่อกัน (แบบสับเปลี่ยน) ของโมดูลรูท
- เมื่อไม่ได้ใช้
WORKSPACE.bzlmod
: Toolchains ที่ลงทะเบียนในส่วนต่อท้ายWORKSPACE
แนะนำที่เก็บในเครื่อง
คุณอาจต้องแนะนำทรัพยากร Dependency เป็นที่เก็บภายในเครื่องเมื่อต้องการทรัพยากร Dependency ในเวอร์ชันในเครื่องสำหรับการแก้ไขข้อบกพร่อง หรือหากต้องการรวมไดเรกทอรีในพื้นที่ทำงานเป็นที่เก็บภายนอก
พื้นที่ทำงาน
การใช้ WORKSPACE ทำได้ตามกฎที่เก็บในเครื่อง 2 ข้อ ได้แก่
local_repository
และnew_local_repository
## WORKSPACE local_repository( name = "rules_java", path = "/Users/bazel_user/workspace/rules_java", )
Bzlmod
เมื่อใช้ Bzlmod คุณจะใช้
local_path_override
เพื่อลบล้างโมดูลด้วยเส้นทางภายในได้## MODULE.bazel bazel_dep(name = "rules_java") local_path_override( module_name = "rules_java", path = "/Users/bazel_user/workspace/rules_java", )
คุณอาจแนะนำที่เก็บในเครื่องที่มีส่วนขยายโมดูลได้ด้วย แต่คุณจะเรียกใช้
native.local_repository
ในส่วนขยายโมดูลไม่ได้ เรามีความพยายามในการติดดาวกฎที่เก็บในเครื่องทั้งหมด (ตรวจสอบความคืบหน้าที่ #18285) จากนั้นคุณจะเรียก Starlarklocal_repository
ที่เกี่ยวข้องในส่วนขยายโมดูลได้ การใช้กฎที่เก็บlocal_repository
เวอร์ชันที่กำหนดเองของที่เก็บเวอร์ชันที่กำหนดเองนั้นไม่ใช่เรื่องสำคัญเช่นกัน หากเป็นปัญหาเกี่ยวกับการบล็อกสำหรับคุณ
เชื่อมโยงเป้าหมาย
เลิกใช้งานกฎ bind
ใน WORKSPACE แล้วและไม่รองรับใน Bzlmod มีการเปิดตัวเพื่อตั้งชื่ออีเมลแทนในแพ็กเกจ //external
พิเศษ ผู้ใช้ทุกคนตามกรณีนี้ควรย้ายข้อมูลออก
เช่น หากคุณมีผู้ติดตาม
## WORKSPACE
bind(
name = "openssl",
actual = "@my-ssl//src:openssl-lib",
)
ซึ่งจะทำให้เป้าหมายอื่นๆ ขึ้นอยู่กับ //external:openssl
คุณสามารถย้ายข้อมูล
จากตรงนี้ได้โดยทำดังนี้
แทนที่การใช้งาน
//external:openssl
ทั้งหมดด้วย@my-ssl//src:openssl-lib
หรือใช้กฎบิลด์
alias
กำหนดเป้าหมายต่อไปนี้ในแพ็กเกจ (เช่น
//third_party
)## third_party/BUILD alias( name = "openssl", actual = "@my-ssl//src:openssl-lib", )
แทนที่การใช้งาน
//external:openssl
ทั้งหมดด้วย//third_party:openssl
การดึงข้อมูลกับการซิงค์
คำสั่งดึงข้อมูลและซิงค์มีไว้เพื่อดาวน์โหลดที่เก็บภายนอกในเครื่องและอัปเดตอยู่เสมอ บางครั้งอาจต้องอนุญาตให้สร้างแบบออฟไลน์โดยใช้แฟล็ก --nofetch
หลังจากดึงข้อมูลที่เก็บทั้งหมดที่จำเป็นสำหรับงานสร้างแล้ว
พื้นที่ทำงาน
การซิงค์จะบังคับดึงข้อมูลสำหรับที่เก็บทั้งหมด หรือสำหรับชุดที่เก็บที่กำหนดค่าไว้ที่เจาะจง ขณะที่การดึงข้อมูลจะใช้เพื่อดึงข้อมูลเป้าหมายที่เจาะจงเท่านั้น
Bzlmod
คำสั่งซิงค์ใช้ไม่ได้แล้ว แต่การดึงข้อมูลมีตัวเลือกต่างๆ คุณสามารถดึงข้อมูลเป้าหมาย ที่เก็บ ชุดของที่เก็บที่กำหนดค่าไว้ หรือที่เก็บทั้งหมดที่เกี่ยวข้องกับการแก้ไขทรัพยากร Dependency และส่วนขยายโมดูลได้ ผลการดึงข้อมูลจะแคชไว้และหากต้องการบังคับการดึงข้อมูล คุณต้องมีตัวเลือก
--force
ในระหว่างขั้นตอนการดึงข้อมูล
การย้ายข้อมูล
ส่วนนี้จะแสดงข้อมูลและคำแนะนำที่เป็นประโยชน์สำหรับขั้นตอนการย้ายข้อมูล Bzlmod
ทำความรู้จักทรัพยากร Dependency ใน WORKSPACE
ขั้นตอนแรกของการย้ายข้อมูลคือการทำความเข้าใจทรัพยากร Dependency ที่คุณมี เป็นเรื่องยากที่จะหาว่าใช้ทรัพยากร Dependency ใดในไฟล์ WORKSPACE เนื่องจากทรัพยากร Dependency แบบทรานซิทีฟมักจะโหลดด้วยมาโคร *_deps
ตรวจสอบทรัพยากร Dependency ภายนอกด้วยไฟล์ที่ได้รับการแก้ไขในพื้นที่ทํางาน
โชคดีที่ Flag
--experimental_repository_resolved_file
ช่วยคุณได้ โดยพื้นฐานแล้ว Flag นี้จะสร้าง "ไฟล์ล็อก" ของทรัพยากร Dependency ภายนอกทั้งหมดที่ดึงมาในคำสั่ง Bazel ล่าสุด ดูรายละเอียดเพิ่มเติมได้ในบล็อกโพสต์นี้
โดยใช้ได้ 2 วิธีดังนี้
เพื่อดึงข้อมูลของทรัพยากร Dependency ภายนอกที่จำเป็นสำหรับการสร้างเป้าหมายบางรายการ
bazel clean --expunge bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
เพื่อดึงข้อมูลของทรัพยากร Dependency ภายนอกทั้งหมดที่กำหนดไว้ในไฟล์ WORKSPACE
bazel clean --expunge bazel sync --experimental_repository_resolved_file=resolved.bzl
คุณจะใช้คำสั่ง
bazel sync
เพื่อดึงข้อมูลทรัพยากร Dependency ทั้งหมดที่กำหนดไว้ในไฟล์ WORKSPACE ได้ ซึ่งประกอบด้วย- การใช้งาน
bind
- การใช้งาน
register_toolchains
และregister_execution_platforms
อย่างไรก็ตาม หากโปรเจ็กต์เป็นแบบข้ามแพลตฟอร์ม การซิงค์ Bazel อาจเสียหายในบางแพลตฟอร์มเนื่องจากกฎที่เก็บบางข้ออาจทำงานได้อย่างถูกต้องเฉพาะในแพลตฟอร์มที่รองรับเท่านั้น
- การใช้งาน
หลังจากเรียกใช้คำสั่ง คุณควรมีข้อมูลการขึ้นต่อกันภายนอกในไฟล์ resolved.bzl
ตรวจสอบทรัพยากร Dependency ภายนอกด้วย bazel query
หรืออาจรู้ว่าใช้ bazel query
เพื่อตรวจสอบกฎของที่เก็บได้ด้วย
bazel query --output=build //external:<repo name>
แม้ว่าจะสะดวกสบายกว่าและเร็วกว่ามาก แต่คำค้นหา Bazel อาจไม่ตรงกับเวอร์ชันของ Dependency ภายนอก ดังนั้นโปรดระวังการใช้งานด้วย การค้นหาและตรวจสอบการพึ่งพาภายนอกด้วย Bzlmod จะดำเนินการได้ด้วยคำสั่งย่อยใหม่
ทรัพยากร Dependency เริ่มต้นในตัว
หากคุณตรวจสอบไฟล์ที่ --experimental_repository_resolved_file
สร้างขึ้น คุณจะพบทรัพยากร Dependency จำนวนมากที่ไม่ได้กำหนดไว้ใน WORKSPACE
นั่นเป็นเพราะ Bazel เพิ่มคำนำหน้าและคำต่อท้ายให้กับเนื้อหาไฟล์ WORKSPACE ของผู้ใช้เพื่อแทรกทรัพยากร Dependency เริ่มต้นบางส่วน ซึ่งมักกำหนดโดยกฎของระบบ (เช่น @bazel_tools
, @platforms
และ @remote_java_tools
) เมื่อใช้ Bzlmod ทรัพยากร Dependency เหล่านี้จะเริ่มใช้ด้วยโมดูลในตัว bazel_tools
ซึ่งเป็นทรัพยากร Dependency เริ่มต้นสําหรับโมดูล Bazel ทั้งหมด
โหมดผสมสำหรับการทยอยย้ายข้อมูล
Bzlmod และ WORKSPACE สามารถทำงานควบคู่กันไปได้ ซึ่งจะทำให้การย้ายข้อมูลทรัพยากร Dependency จากไฟล์ WORKSPACE ไปยัง Bzlmod เป็นกระบวนการแบบค่อยเป็นค่อยไปได้
WORKSPACE.bzlmod
ในระหว่างการย้ายข้อมูล ผู้ใช้ Bazel อาจต้องสลับระหว่างบิลด์ที่มีและไม่ได้เปิดใช้ Bzlmod มีการสนับสนุน WORKSPACE.bzlmod เพื่อทำให้ กระบวนการราบรื่นยิ่งขึ้น
WORKSPACE.bzlmod มีไวยากรณ์เดียวกันกับ WORKSPACE เมื่อเปิดใช้ Bzlmod หากมีไฟล์ WORKSPACE.bzlmod อยู่ที่รูทของพื้นที่ทำงาน
WORKSPACE.bzlmod
มีผลบังคับใช้และเนื้อหาของWORKSPACE
จะไม่มีผล- ระบบจะไม่เพิ่มคำนำหน้าหรือคำต่อท้ายในไฟล์ WORKSPACE.bzlmod
การใช้ไฟล์ WORKSPACE.bzlmod จะช่วยให้การย้ายข้อมูลง่ายขึ้นเนื่องจากเหตุผลต่อไปนี้
- เมื่อปิดใช้ Bzlmod คุณจะกลับไปดึงข้อมูลทรัพยากร Dependency จากไฟล์ WORKSPACE เดิม
- เมื่อเปิดใช้ Bzlmod คุณจะติดตามทรัพยากร Dependency ที่เหลืออยู่ในการย้ายข้อมูลได้ดีขึ้นด้วย WORKSPACE.bzlmod
ระดับการเข้าถึงที่เก็บ
Bzlmod ควบคุมได้ว่าจะให้ที่เก็บอื่นใดแสดงจากที่เก็บหนึ่งๆ ดูรายละเอียดเพิ่มเติมได้ที่ชื่อและรายละเอียดของที่เก็บ
ต่อไปนี้คือสรุประดับการเข้าถึงที่เก็บจากที่เก็บประเภทต่างๆ เมื่อนำ WORKSPACE มาพิจารณาด้วย
จากที่เก็บหลัก | จากที่เก็บโมดูล Bazel | จากที่เก็บส่วนขยายโมดูล | จากที่เก็บของ Workspace | |
---|---|---|---|---|
ที่เก็บหลัก | แสดง | หากโมดูลรูทเป็นทรัพยากร Dependency โดยตรง | หากโมดูลรูทเป็นทรัพยากร Dependency โดยตรงของโมดูลที่โฮสต์ส่วนขยายโมดูล | แสดง |
ที่เก็บโมดูล Bazel | การเพิ่มขึ้นของเส้นตรง | การเพิ่มขึ้นของเส้นตรง | ส่วนโดยตรงของโมดูลที่โฮสต์ส่วนขยายโมดูล | ช่วงโดยตรงของโมดูลรูท |
ที่เก็บส่วนขยายโมดูล | การเพิ่มขึ้นของเส้นตรง | การเพิ่มขึ้นของเส้นตรง | ช่วงเวลาโดยตรงของโมดูลที่โฮสต์ส่วนขยายโมดูล + ที่เก็บทั้งหมดที่สร้างขึ้นโดยส่วนขยายโมดูลเดียวกัน | ช่วงโดยตรงของโมดูลรูท |
ที่เก็บใน Workspace | แสดงทั้งหมด | ไม่แสดง | ไม่แสดง | แสดงทั้งหมด |
@bar
กระบวนการย้ายข้อมูล
กระบวนการย้ายข้อมูล Bzlmod โดยทั่วไปจะมีลักษณะดังนี้
- ทำความเข้าใจทรัพยากร Dependency ที่คุณมีใน WORKSPACE
- เพิ่มไฟล์ MODULE.bazel ว่างที่รากของโปรเจ็กต์
- เพิ่มไฟล์ WORKSPACE.bzlmod ที่ว่างเปล่าเพื่อลบล้างเนื้อหาไฟล์ WORKSPACE
- สร้างเป้าหมายโดยเปิดใช้ Bzlmod และดูว่าที่เก็บใดขาดหายไป
- ตรวจสอบคำจำกัดความของที่เก็บที่หายไปในไฟล์ทรัพยากร Dependency ที่ได้รับการแก้ไขแล้ว
- แนะนำทรัพยากร Dependency ที่ขาดหายไปในฐานะโมดูล Bazel ผ่านส่วนขยายโมดูล หรือปล่อยไว้ใน WORKSPACE.bzlmod เพื่อย้ายข้อมูลในภายหลัง
- กลับไปที่ 4 และทำซ้ำจนกว่าทรัพยากร Dependency ทั้งหมดจะพร้อมใช้งาน
เครื่องมือย้ายข้อมูล
มีสคริปต์ตัวช่วยสำหรับการย้ายข้อมูล Bzlmod แบบอินเทอร์แอกทีฟที่จะช่วยคุณเริ่มต้นใช้งาน
สคริปต์จะดำเนินการต่อไปนี้
- สร้างและแยกวิเคราะห์ไฟล์ที่แก้ปัญหาแล้วของ WORKSPACE
- พิมพ์ข้อมูลที่เก็บจากไฟล์ที่แก้ไขแล้วด้วยวิธีที่มนุษย์อ่านได้
- เรียกใช้คำสั่งบิลด์ bazel, ตรวจหาข้อความแสดงข้อผิดพลาดที่รู้จัก และแนะนำวิธีย้ายข้อมูล
- ตรวจสอบว่าทรัพยากร Dependency มีใน BCR อยู่แล้วหรือไม่
- เพิ่มทรัพยากร Dependency ไปยังไฟล์ MODULE.bazel
- เพิ่มการอ้างอิงผ่านส่วนขยายโมดูล
- เพิ่มทรัพยากร Dependency ไปยังไฟล์ WORKSPACE.bzlmod
หากต้องการใช้งาน ให้ตรวจสอบว่าคุณได้ติดตั้ง Bazel รุ่นล่าสุดแล้ว และเรียกใช้คำสั่งต่อไปนี้
git clone https://github.com/bazelbuild/bazel-central-registry.git
cd <your workspace root>
<BCR repo root>/tools/migrate_to_bzlmod.py -t <your build targets>
เผยแพร่โมดูล Bazel
หากโปรเจ็กต์ Bazel ของคุณเป็นทรัพยากร Dependency สำหรับโปรเจ็กต์อื่นๆ คุณจะเผยแพร่โปรเจ็กต์ใน Bazel Central Registry ได้
คุณต้องมี URL ที่เก็บถาวรต้นทางของโปรเจ็กต์เพื่อให้ตรวจสอบโปรเจ็กต์ใน BCR ได้ ข้อควรทราบบางประการเมื่อสร้างที่เก็บถาวรต้นทางมีดังนี้
ตรวจสอบว่าไฟล์ที่เก็บถาวรชี้ไปยังเวอร์ชันที่เจาะจง
BCR จะยอมรับเฉพาะที่เก็บถาวรต้นทางที่มีเวอร์ชันเท่านั้น เนื่องจาก Bzlmod ต้องทำการเปรียบเทียบเวอร์ชันระหว่างการแปลงทรัพยากร Dependency
ตรวจสอบว่า URL ที่เก็บถาวรไม่เสถียร
Bazel ยืนยันเนื้อหาของที่เก็บถาวรโดยใช้ค่าแฮช ดังนั้นคุณควรตรวจสอบว่า Checksum ของไฟล์ที่ดาวน์โหลดไม่มีการเปลี่ยนแปลง หาก URL มาจาก GitHub โปรดสร้างและอัปโหลดที่เก็บถาวรของรุ่นในหน้าการเผยแพร่ GitHub จะไม่รับประกันการตรวจสอบผลรวมของแหล่งที่มาที่เก็บถาวรที่สร้างขึ้นตามคำขอ กล่าวโดยสรุปคือ URL ในรูปแบบ
https://github.com/<org>/<repo>/releases/download/...
จะถือว่าเสถียรในขณะที่https://github.com/<org>/<repo>/archive/...
ไม่เสถียร ดู GitHub ที่เก็บถาวรของ Checksum การหยุดทำงาน เพื่อดูบริบทเพิ่มเติมตรวจสอบว่าโครงสร้างแหล่งที่มาเป็นไปตามเลย์เอาต์ของที่เก็บต้นฉบับ
ในกรณีที่ที่เก็บมีขนาดใหญ่มากและต้องการสร้างที่เก็บถาวรสำหรับการกระจายที่มีขนาดลดลงโดยตัดแหล่งที่มาที่ไม่จำเป็นออก โปรดตรวจสอบว่าทรีซอร์สที่ตัดออกเป็นชุดย่อยของแผนผังแหล่งที่มาต้นฉบับ วิธีนี้ช่วยให้ผู้ใช้ปลายทางลบล้างโมดูลเป็นเวอร์ชันที่ยังไม่เปิดตัวด้วย
archive_override
และgit_override
ได้ง่ายขึ้นรวมโมดูลทดสอบในไดเรกทอรีย่อยที่ทดสอบ API ที่คุณใช้บ่อยที่สุด
โมดูลทดสอบคือโปรเจ็กต์ Bazel ที่มีไฟล์ WORKSPACE และ MODULE.bazel ของตัวเองซึ่งอยู่ในไดเรกทอรีย่อยของที่เก็บถาวรต้นทางซึ่งจะขึ้นอยู่กับโมดูลจริงที่จะเผยแพร่ ซึ่งควรมีตัวอย่างหรือการทดสอบการผสานรวมบางส่วนที่ครอบคลุม API ที่คุณใช้บ่อยที่สุด ไปที่โมดูลการทดสอบเพื่อดูวิธีตั้งค่า
เมื่อคุณมี URL ของที่เก็บถาวรต้นทางพร้อมแล้ว ให้ทำตามหลักเกณฑ์การสนับสนุน BCR เพื่อส่งโมดูลไปยัง BCR ด้วยคำขอพุล GitHub
เราขอแนะนำเป็นอย่างยิ่งให้ตั้งค่าแอป GitHub เผยแพร่ไปยัง BCR สำหรับที่เก็บของคุณเพื่อทำให้กระบวนการส่งโมดูลไปยัง BCR เป็นแบบอัตโนมัติ
แนวทางปฏิบัติแนะนำ
ส่วนนี้จะแสดงแนวทางปฏิบัติแนะนำบางส่วนที่คุณควรปฏิบัติตามเพื่อให้จัดการทรัพยากร Dependency ภายนอกได้ดียิ่งขึ้น
แยกเป้าหมายออกเป็นแพ็กเกจต่างๆ เพื่อหลีกเลี่ยงการดึงข้อมูลทรัพยากร Dependency ที่ไม่จำเป็น
ตรวจสอบ #12835 ซึ่งจะมีการบังคับให้ดึงข้อมูลทรัพยากร Dependency ของนักพัฒนาซอฟต์แวร์สำหรับการทดสอบโดยไม่จำเป็นเพื่อสร้างเป้าหมายที่ไม่จำเป็น จริงๆ แล้วข้อมูลนี้ไม่ได้เฉพาะเจาะจงสำหรับ Bzlmod แต่การปฏิบัติตามแนวทางปฏิบัตินี้จะช่วยให้คุณระบุทรัพยากร Dependency ของ Dependency อย่างถูกต้องได้ง่ายขึ้น
ระบุทรัพยากร Dependency สำหรับนักพัฒนาซอฟต์แวร์
คุณตั้งค่าแอตทริบิวต์ dev_dependency
เป็น "จริง" สำหรับคำสั่ง bazel_dep
และ use_extension
ได้ เพื่อไม่ให้มีผลกับโปรเจ็กต์ที่เกี่ยวข้อง ในฐานะโมดูลรูท คุณสามารถใช้แฟล็ก --ignore_dev_dependency
เพื่อตรวจสอบว่าเป้าหมายยังคงสร้างโดยไม่มีทรัพยากร Dependency หรือไม่
ความคืบหน้าในการย้ายข้อมูลชุมชน
คุณตรวจสอบ Bazel Central Registry เพื่อดูว่าทรัพยากร Dependency พร้อมใช้งานหรือไม่ หรือเข้าร่วมการสนทนาของ GitHub นี้เพื่อโหวตเห็นด้วยหรือโพสต์ทรัพยากร Dependency ที่บล็อกการย้ายข้อมูลได้
รายงานปัญหา
โปรดตรวจสอบรายการปัญหา GitHub ของ Bazel เพื่อดูปัญหาที่ทราบเกี่ยวกับ Bzlmod คุณสามารถยื่นปัญหาหรือคำขอฟีเจอร์ใหม่เพื่อช่วยเลิกบล็อกการย้ายข้อมูลได้