การลงทะเบียน BazelCon 2024 เปิดให้ลงทะเบียนแล้วในตอนนี้

หน้านี้ได้รับการแปลโดย Cloud Translation API

คู่มือการย้ายข้อมูล Bzlmod

วันที่ รายงานปัญหา ดูแหล่งที่มา ตอนกลางคืน · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

เนื่องจากข้อบกพร่องของ 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 จากมาโครของทรัพยากร Dependency สมมติทั้ง bazel_skylib และ rules_java ขึ้นอยู่กับ platform ซึ่งเป็นเวอร์ชันที่แน่นอนของ platform Dependency จะกำหนดตามลำดับของมาโคร
Bzlmod

เมื่อใช้ Bzlmod ตราบใดที่ทรัพยากร Dependency ของคุณมีอยู่ใน Bazel Central รีจิสทรีหรือ Bazel ที่กำหนดเอง รีจิสทรี คุณก็สามารถใช้รีจิสทรีพร้อม 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

ในฐานะโมดูลรูท คุณสามารถลบล้างทรัพยากร Dependency ของโมดูล Bazel ใน ได้

โปรดอ่านข้อมูลเพิ่มเติมในส่วนการลบล้าง

คุณสามารถดูตัวอย่างการใช้งานได้ใน ตัวอย่าง ที่เก็บได้

ดึงข้อมูลทรัพยากร 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 เนื่องจากไม่ใช่วิธีที่เหมาะสมในการ แปลค่าทรัพยากร Dependency

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 ขณะที่ ทรัพยากร Dependency bar ต้องใช้ 3.0 ส่วนขยายโมดูลใน foo สามารถ แก้ไขข้อขัดแย้งนี้และเลือกเวอร์ชัน 3.0 โดยอัตโนมัติให้กับข้อมูล การพึ่งพา

รวมตัวจัดการแพ็กเกจของบุคคลที่สาม

ต่อจากส่วนสุดท้าย เนื่องจากส่วนขยายโมดูลให้วิธีรวบรวม จากกราฟทรัพยากร Dependency ให้ทำตรรกะที่กำหนดเองเพื่อแก้ไข ทรัพยากร Dependency และเรียกกฎที่เก็บเพื่อแนะนำที่เก็บภายนอก เป็นวิธีที่ดีสำหรับผู้เขียนกฎในการปรับปรุงชุดกฎที่ผสานรวม แพ็กเกจของบางภาษา

โปรดอ่านหน้าส่วนขยายโมดูลเพื่อเรียนรู้เพิ่มเติม เกี่ยวกับวิธีใช้ส่วนขยายโมดูล

ต่อไปนี้คือรายการชุดกฎที่ใช้ Bzlmod เพื่อดึงข้อมูลทรัพยากร Dependency แล้ว จากผู้จัดการแพ็กเกจรายต่างๆ ดังนี้

ตัวอย่างขั้นต่ำที่ผสานรวมตัวจัดการแพ็กเกจเทียมจะอยู่ที่ ตัวอย่าง ที่เก็บได้

ตรวจหา Toolchain ในเครื่องโฮสต์

เมื่อ Bazel สร้างกฎเพื่อตรวจหาเครื่องมือเชนที่พร้อมใช้งานในโฮสต์ของคุณ จะใช้กฎที่เก็บเพื่อตรวจสอบเครื่องโฮสต์และสร้าง ข้อมูล 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 แพลตฟอร์มการดำเนินการ

ต่อจากส่วนสุดท้าย หลังจากแนะนำ Toolchain โฮสติ้งของที่เก็บ (เช่น local_config_sh) คุณอาจต้องการลงทะเบียน Toolchain

พื้นที่ทำงาน

เมื่อใช้ WORKSPACE คุณจะลงทะเบียนเครื่องมือเชนได้ด้วยวิธีต่อไปนี้
1. คุณสามารถลงทะเบียน Toolchain ไฟล์ .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()
```
2. หรือลงทะเบียน 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 register_toolchains และ register_execution_platforms API จะใช้ได้เฉพาะในไฟล์ 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")
```

เครื่องมือเชนและแพลตฟอร์มการดำเนินการที่ลงทะเบียนไว้ในWORKSPACE WORKSPACE.bzlmod และ MODULE.bazel ของโมดูล Bazel แต่ละรายการจะเป็นไปตามนี้ ลำดับความสำคัญระหว่างการเลือก Toolchain (จากสูงสุดไปต่ำสุด) มีดังนี้

เครื่องมือเชนและแพลตฟอร์มการดำเนินการที่ลงทะเบียนในโมดูลรูทของ MODULE.bazel ไฟล์
Toolchains และแพลตฟอร์มการดำเนินการที่ลงทะเบียนใน WORKSPACE หรือ WORKSPACE.bzlmod
แพลตฟอร์มเครื่องมือและการดำเนินการที่ลงทะเบียนโดยโมดูลที่ ทรัพยากร Dependency (สโลแกน) ของโมดูลรูท
เมื่อไม่ได้ใช้ 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",
)
```
หมายเหตุ: เมื่อใช้ local_path_override คุณจะแนะนำได้เฉพาะไดเรกทอรีในเครื่องเท่านั้น เป็นโมดูล Bazel ซึ่งหมายความว่าควรมีไฟล์ MODULE.bazel และ ระบบจะพิจารณาการขึ้นต่อกันแบบสับเปลี่ยนระหว่างการอ้างอิง ความละเอียดสูงสุดของคุณ นอกจากนี้ คำสั่งลบล้างโมดูลทั้งหมดจะใช้ได้เฉพาะโดย โมดูลรูท

คุณอาจแนะนำที่เก็บในเครื่องที่มีส่วนขยายโมดูลได้ด้วย แต่คุณจะเรียกใช้ native.local_repository ในส่วนขยายโมดูลไม่ได้ ยังมีความพยายามอย่างต่อเนื่องในการติดดาวกฎที่เก็บในระบบทั้งหมด (ตรวจสอบ #18285 เพื่อดูความคืบหน้า) จากนั้นคุณจะเรียกใช้ Starlark local_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-lib

การย้ายข้อมูล

ส่วนนี้ให้ข้อมูลและคำแนะนำที่เป็นประโยชน์สำหรับการย้ายข้อมูล Bzlmod ขั้นตอนได้

ทำความรู้จักทรัพยากร Dependency ใน WORKSPACE

ขั้นตอนแรกของการย้ายข้อมูลคือการทำความเข้าใจทรัพยากร Dependency ที่คุณมี ทั้งนี้ อาจทำได้ยากที่จะทราบว่า มีการเริ่มใช้ทรัพยากร Dependency ใดบ้าง ไฟล์ WORKSPACE เนื่องจากทรัพยากร Dependency แบบทรานซิทีฟมักจะโหลดด้วย *_deps มาโคร

ตรวจสอบทรัพยากร Dependency ภายนอกด้วยไฟล์ที่ได้รับการแก้ไขในพื้นที่ทํางาน

โชคดีที่ธง --experimental_repository_resolved_file สามารถช่วยคุณได้ โดยพื้นฐานแล้ว แฟล็กนี้จะสร้าง "ไฟล์ล็อก" ของรายการที่ดึงข้อมูลภายนอกทั้งหมด ทรัพยากร 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 อาจเสียหายใน แพลตฟอร์ม เนื่องจากกฎที่เก็บบางกฎอาจทำงานได้อย่างถูกต้องบนที่รองรับเท่านั้น ใหม่

หลังจากเรียกใช้คำสั่ง คุณควรมีข้อมูลจากบุคคลที่สาม ทรัพยากร Dependency ในไฟล์ resolved.bzl

ตรวจสอบทรัพยากร Dependency ภายนอกด้วย `bazel query`

หรืออาจรู้ว่าใช้ bazel query เพื่อตรวจสอบกฎของที่เก็บได้ด้วย

bazel query --output=build //external:<repo name>

แม้ว่าจะสะดวกสบายกว่าและเร็วกว่ามาก แต่คำค้นหาที่เปลี่ยนได้ก็คือ เวอร์ชันที่พึ่งพาภายนอก ดังนั้น โปรดระวังการใช้งานด้วย! การค้นหาและตรวจสอบภายนอก การพึ่งพา Bzlmod จะเกิดขึ้นโดยมี คำสั่งย่อย

ทรัพยากร Dependency เริ่มต้นในตัว

หากคุณตรวจสอบไฟล์ที่ --experimental_repository_resolved_file สร้างขึ้น คุณจะพบทรัพยากร Dependency มากมายที่ไม่ได้กำหนดไว้ใน WORKSPACE เพราะจริงๆ แล้ว Bazel เพิ่มคำนำหน้าและคำต่อท้ายลงใน WORKSPACE ของผู้ใช้ เนื้อหาไฟล์เพื่อใส่ทรัพยากร Dependency เริ่มต้นบางส่วน ซึ่งมักจะต้องใช้โดย กฎแบบเนทีฟ (เช่น @bazel_tools, @platforms และ @remote_java_tools) ด้วย Bzlmod ที่การพึ่งพากันเหล่านั้นได้รับการแนะนำด้วยโมดูลในตัว 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 สามารถควบคุมที่เก็บอื่นที่จะแสดง ที่เก็บ ให้ตรวจสอบชื่อที่เก็บและการตั้งค่าที่เข้มงวด deps สำหรับรายละเอียดเพิ่มเติม

ต่อไปนี้เป็นสรุปของระดับการเข้าถึงที่เก็บจากประเภทต่างๆ เมื่อนำ WORKSPACE มาพิจารณาด้วย

	จากที่เก็บหลัก	จากที่เก็บโมดูล Bazel	จากที่เก็บส่วนขยายโมดูล	จากที่เก็บของ Workspace
ที่เก็บหลัก	แสดง	หากโมดูลรูทเป็นทรัพยากร Dependency โดยตรง	หากโมดูลรูทเป็นทรัพยากร Dependency โดยตรงของโมดูลที่โฮสต์ส่วนขยายโมดูล	แสดง
ที่เก็บโมดูล Bazel	การเพิ่มขึ้นของเส้นตรง	การเพิ่มขึ้นของเส้นตรง	ส่วนโดยตรงของโมดูลที่โฮสต์ส่วนขยายโมดูล	ช่วงโดยตรงของโมดูลรูท
ที่เก็บส่วนขยายโมดูล	การเพิ่มขึ้นของเส้นตรง	การเพิ่มขึ้นของเส้นตรง	ช่วงเวลาโดยตรงของโมดูลที่โฮสต์ส่วนขยายโมดูล + ที่เก็บทั้งหมดที่สร้างขึ้นโดยส่วนขยายโมดูลเดียวกัน	ช่วงโดยตรงของโมดูลรูท
ที่เก็บใน Workspace	แสดงทั้งหมด	ไม่แสดง	ไม่แสดง	แสดงทั้งหมด

กระบวนการย้ายข้อมูล

กระบวนการย้ายข้อมูล 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

เพื่อให้ตรวจสอบโปรเจ็กต์ใน BCR ได้ คุณต้องมี URL ที่เก็บถาวรต้นทางเป็น ให้กับโครงการ ข้อควรทราบบางประการเมื่อสร้างที่เก็บถาวรต้นทางมีดังนี้

ตรวจสอบว่าไฟล์ที่เก็บถาวรชี้ไปยังเวอร์ชันที่เจาะจง

BCR จะยอมรับเฉพาะที่เก็บถาวรต้นทางที่มีเวอร์ชันเท่านั้นเนื่องจาก Bzlmod ต้อง ดำเนินการเปรียบเทียบเวอร์ชันในระหว่างการแก้ปัญหาทรัพยากร Dependency
ตรวจสอบว่า URL ที่เก็บถาวรไม่เสถียร

Bazel ตรวจสอบเนื้อหาของที่เก็บถาวรโดยใช้ค่าแฮช ดังนั้น ให้ตรวจสอบว่า checksum ของไฟล์ที่ดาวน์โหลดจะไม่เปลี่ยนแปลง หาก URL คือ จาก GitHub โปรดสร้างและอัปโหลดที่เก็บถาวรของรุ่นในหน้าการเผยแพร่ GitHub จะไม่รับประกันการตรวจสอบข้อผิดพลาดเกี่ยวกับที่เก็บถาวรของแหล่งที่มาที่สร้างขึ้นบน ความต้องการของคุณ กล่าวโดยสรุปคือ URL ในรูปแบบ https://github.com/<org>/<repo>/releases/download/... ถือว่าเสถียร แต่ https://github.com/<org>/<repo>/archive/... ไม่เป็นเช่นนั้น ลองดู GitHub การตรวจสอบข้อผิดพลาดในที่เก็บถาวร การหยุดทำงาน สำหรับบริบทเพิ่มเติม
ตรวจสอบว่าโครงสร้างแหล่งที่มาเป็นไปตามเลย์เอาต์ของที่เก็บต้นฉบับ

ในกรณีที่ที่เก็บมีขนาดใหญ่มากและคุณต้องการสร้างการกระจาย ที่เก็บถาวรที่มีขนาดลดลงโดยตัดแหล่งที่มาที่ไม่จำเป็นออก โปรด ตรวจสอบว่าแผนผังแหล่งที่มาที่ถูกตัดเป็นชุดย่อยของแผนผังแหล่งที่มาดั้งเดิม ช่วงเวลานี้ ทำให้ผู้ใช้ปลายทางลบล้างโมดูล เป็นเวอร์ชันที่ยังไม่เปิดตัวได้ง่ายขึ้น เวอร์ชันโดย archive_override และ git_override
รวมโมดูลทดสอบไว้ในไดเรกทอรีย่อยที่ทดสอบการตั้งค่าบ่อยที่สุด API

โมดูลทดสอบเป็นโปรเจ็กต์ Bazel ที่มี WORKSPACE และ MODULE.bazel ของตัวเอง ที่อยู่ในไดเรกทอรีย่อยของที่เก็บถาวรแหล่งที่มาซึ่งขึ้นอยู่กับ โมดูลจริงที่จะเผยแพร่ ควรมีตัวอย่างหรือ การทดสอบการผสานรวมที่ครอบคลุม API ที่คุณใช้บ่อยที่สุด ตรวจสอบ โมดูลทดสอบเพื่อดูวิธีตั้งค่า

เมื่อคุณมี URL ของที่เก็บถาวรต้นทางพร้อมแล้ว ให้ทำตามการมีส่วนร่วม BCR หลักเกณฑ์ในการส่งโมดูลของคุณไปยัง BCR ด้วย GitHub ดึงคำขอ

เราแนะนําอย่างยิ่งให้ตั้งค่าเผยแพร่ไปยัง แอป BCR GitHub สำหรับ เพื่อทำให้กระบวนการส่งโมดูลของคุณไปยัง BCR เป็นไปโดยอัตโนมัติ

แนวทางปฏิบัติแนะนำ

ส่วนนี้แสดงแนวทางปฏิบัติแนะนำบางประการที่คุณควรปฏิบัติตามเพื่อให้ทำงานได้ดีขึ้น การจัดการทรัพยากร Dependency ภายนอก

แยกเป้าหมายออกเป็นแพ็กเกจต่างๆ เพื่อหลีกเลี่ยงการดึงข้อมูลทรัพยากร Dependency ที่ไม่จำเป็น

ตรวจสอบ #12835 โดยที่ dev ทรัพยากร Dependency สำหรับการทดสอบถูกบังคับให้ดึงข้อมูลโดยไม่จำเป็นสำหรับการสร้าง เป้าหมายที่ไม่ต้องการ ที่จริงแล้ว ข้อมูลนี้ไม่ได้เกี่ยวข้องกับ Bzlmod เท่านั้น การปฏิบัติตามแนวทางปฏิบัตินี้จะช่วยให้คุณระบุทรัพยากร Dependency ได้ง่าย

ระบุทรัพยากร Dependency สำหรับนักพัฒนาซอฟต์แวร์

คุณตั้งค่าแอตทริบิวต์ dev_dependency เป็น "จริง" ได้สำหรับ bazel_dep และ use_extension คำสั่งเพื่อให้ และจะไม่เผยแพร่ไปยังโปรเจ็กต์ที่เกี่ยวข้อง ในฐานะโมดูลรูท คุณสามารถใช้ --ignore_dev_dependency แจ้งเพื่อยืนยันว่าเป้าหมายของคุณ ยังคงสร้างโดยไม่มีทรัพยากร Dependency สำหรับนักพัฒนาซอฟต์แวร์

ความคืบหน้าในการย้ายข้อมูลชุมชน

คุณไปที่รีจิสทรี Bazel Central Registry เพื่อดู ว่าทรัพยากร Dependency พร้อมใช้งานหรือไม่ หากไม่ต้องการเข้าร่วม ก็เข้าร่วมได้เลย การสนทนาของ GitHub เพื่อ โหวตเห็นด้วยหรือโพสต์ทรัพยากร Dependency ที่บล็อกการย้ายข้อมูล

รายงานปัญหา

โปรดตรวจสอบรายการปัญหา GitHub ของ Bazel สำหรับ Bzlmod ที่ทราบ ปัญหา คุณสามารถยื่นปัญหาใหม่ๆ หรือคําขอฟีเจอร์ซึ่งจะช่วยเลิกบล็อกได้ การย้ายข้อมูล!

คู่มือการย้ายข้อมูล Bzlmod

WORKSPACE เทียบกับ Bzlmod

กําหนดรูทของพื้นที่ทำงาน Bazel

เปิดใช้ Bzlmod ใน bazelrc ของคุณ

ระบุชื่อที่เก็บสำหรับพื้นที่ทำงาน

ดึงข้อมูลทรัพยากร Dependency ภายนอกเป็นโมดูล Bazel

ลบล้างการขึ้นต่อกันเป็นโมดูล Bazel

ดึงข้อมูลทรัพยากร Dependency ภายนอกด้วยส่วนขยายโมดูล

แก้ไขทรัพยากร Dependency ภายนอกที่มีข้อขัดแย้งด้วยส่วนขยายโมดูล

รวมตัวจัดการแพ็กเกจของบุคคลที่สาม

ตรวจหา Toolchain ในเครื่องโฮสต์

ลงทะเบียน Toolchain แพลตฟอร์มการดำเนินการ

แนะนำที่เก็บในเครื่อง

เชื่อมโยงเป้าหมาย

การย้ายข้อมูล

ทำความรู้จักทรัพยากร Dependency ใน WORKSPACE

ตรวจสอบทรัพยากร Dependency ภายนอกด้วยไฟล์ที่ได้รับการแก้ไขในพื้นที่ทํางาน

ตรวจสอบทรัพยากร Dependency ภายนอกด้วย bazel query

ทรัพยากร Dependency เริ่มต้นในตัว

โหมดผสมสำหรับการทยอยย้ายข้อมูล

WORKSPACE.bzlmod

ระดับการเข้าถึงที่เก็บ

กระบวนการย้ายข้อมูล

เครื่องมือย้ายข้อมูล

เผยแพร่โมดูล Bazel

แนวทางปฏิบัติแนะนำ

แยกเป้าหมายออกเป็นแพ็กเกจต่างๆ เพื่อหลีกเลี่ยงการดึงข้อมูลทรัพยากร Dependency ที่ไม่จำเป็น

ระบุทรัพยากร Dependency สำหรับนักพัฒนาซอฟต์แวร์

ความคืบหน้าในการย้ายข้อมูลชุมชน

รายงานปัญหา

ตรวจสอบทรัพยากร Dependency ภายนอกด้วย `bazel query`