Chúng tôi hiện đang nhận đơn đăng ký và CFP cho BazelCon 2025!

Trang này được dịch bởi Cloud Translation API.

Hướng dẫn di chuyển Bzlmod

Báo cáo vấn đề Xem nguồn Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Do những thiếu sót của WORKSPACE, Bzlmod sẽ thay thế hệ thống WORKSPACE cũ. Tệp WORKSPACE đã bị vô hiệu hoá trong Bazel 8 (cuối năm 2024) và sẽ bị xoá trong Bazel 9 (cuối năm 2025). Hướng dẫn này giúp bạn di chuyển dự án sang Bzlmod và xoá WORKSPACE để quản lý các phần phụ thuộc bên ngoài.

Tại sao nên di chuyển sang Bzlmod?

Có nhiều ưu điểm so với hệ thống WORKSPACE cũ, giúp đảm bảo sự phát triển lành mạnh của hệ sinh thái Bazel.
Nếu dự án của bạn là một phần phụ thuộc của các dự án khác, thì việc di chuyển sang Bzlmod sẽ giúp các dự án đó di chuyển và giúp chúng dễ dàng phụ thuộc vào dự án của bạn hơn.
Việc di chuyển sang Bzlmod là một bước cần thiết để sử dụng các phiên bản Bazel trong tương lai (bắt buộc trong Bazel 9).

Cách di chuyển sang Bzlmod

Quy trình di chuyển được đề xuất:

Sử dụng công cụ di chuyển làm công cụ hỗ trợ để đơn giản hoá quy trình di chuyển nhiều nhất có thể. Xem phần công cụ di chuyển và cách sử dụng công cụ.
Nếu vẫn còn lỗi sau khi sử dụng công cụ di chuyển, hãy giải quyết các lỗi đó theo cách thủ công. Để hiểu rõ những điểm khác biệt chính giữa các khái niệm trong tệp WORKSPACE và MODULE.bazel, hãy xem phần WORKSPACE so với Bzlmod.

Công cụ di chuyển

Để đơn giản hoá quy trình thường phức tạp khi di chuyển từ WORKSPACE sang Bzlmod, bạn nên dùng tập lệnh di chuyển. Công cụ trợ giúp này tự động hoá nhiều bước liên quan đến việc di chuyển hệ thống quản lý phần phụ thuộc bên ngoài.

Chức năng cốt lõi

Các chức năng chính của tập lệnh là:

Thu thập thông tin về phần phụ thuộc: Phân tích tệp WORKSPACE của dự án để xác định các kho lưu trữ bên ngoài mà mục tiêu bản dựng đã chỉ định sử dụng. Thao tác này sử dụng cờ experimental_repository_resolved_file của Bazel để tạo tệp resolved_deps.py chứa thông tin này.
Xác định phần phụ thuộc trực tiếp: Sử dụng bazel query để xác định những kho lưu trữ là phần phụ thuộc trực tiếp cho các mục tiêu được chỉ định.
Di chuyển Bzlmod: Dịch các phần phụ thuộc WORKSPACE có liên quan thành các phần phụ thuộc tương đương trong Bzlmod. Đây là quy trình gồm 2 bước:
1. Thử giới thiệu tất cả các phần phụ thuộc trực tiếp đã xác định vào tệp MODULE.bazel.
2. Cố gắng tạo các mục tiêu được chỉ định khi Bzlmod được bật, sau đó xác định và khắc phục các lỗi có thể nhận dạng một cách lặp đi lặp lại. Bước này là cần thiết vì một số phần phụ thuộc có thể bị thiếu trong bước đầu tiên.
Tạo báo cáo di chuyển: Tạo một tệp migration_info.md ghi lại quy trình di chuyển. Báo cáo này bao gồm danh sách các phần phụ thuộc trực tiếp, các khai báo Bzlmod được tạo và mọi bước thủ công có thể cần thiết để hoàn tất quá trình di chuyển.

Công cụ di chuyển hỗ trợ:

Các phần phụ thuộc có trong Bazel Central Registry
Quy tắc kho lưu trữ tuỳ chỉnh do người dùng xác định
[Sắp ra mắt] Phần phụ thuộc của trình quản lý gói

Lưu ý quan trọng: Công cụ di chuyển là một tiện ích hoạt động hiệu quả nhất có thể. Luôn kiểm tra kỹ các đề xuất của công cụ này để đảm bảo tính chính xác.

Cách sử dụng công cụ di chuyển

Trước khi bắt đầu:

Nâng cấp lên bản phát hành Bazel 7 mới nhất, có hỗ trợ mạnh mẽ cho cả WORKSPACE và Bzlmod.
Xác minh rằng lệnh sau chạy thành công cho các mục tiêu chính của bản dựng dự án:
```
bazel build --nobuild --enable_workspace --noenable_bzlmod <targets>
```

Sau khi đáp ứng các điều kiện tiên quyết, hãy chạy các lệnh sau để sử dụng công cụ di chuyển:

# Clone the Bazel Central Registry repository
git clone https://github.com/bazelbuild/bazel-central-registry.git
cd bazel-central-registry

# Build the migration tool
bazel build //tools:migrate_to_bzlmod

# Create a convenient alias for the tool
alias migrate2bzlmod=$(realpath ./bazel-bin/tools/migrate_to_bzlmod)

# Navigate to your project's root directory and run the tool
cd <your workspace root>
migrate2bzlmod -t <your build targets>

WORKSPACE so với Bzlmod

WORKSPACE và Bzlmod của Bazel cung cấp các tính năng tương tự nhưng có cú pháp khác nhau. Phần này giải thích cách di chuyển từ các chức năng cụ thể của WORKSPACE sang Bzlmod.

Xác định thư mục gốc của không gian làm việc Bazel

Tệp WORKSPACE đánh dấu gốc nguồn của một dự án Bazel. Trách nhiệm này được thay thế bằng MODULE.bazel trong Bazel phiên bản 6.3 trở lên. Với các phiên bản Bazel trước 6.3, vẫn phải có tệp WORKSPACE hoặc WORKSPACE.bazel ở thư mục gốc của không gian làm việc, có thể có các nhận xét như:

WORKSPACE

# This file marks the root of the Bazel workspace.
# See MODULE.bazel for external dependencies setup.

Bật Bzlmod trong bazelrc

.bazelrc cho phép bạn đặt các cờ áp dụng mỗi khi bạn chạy Bazel. Để bật Bzlmod, hãy dùng cờ --enable_bzlmod và áp dụng cờ này cho lệnh common để cờ này áp dụng cho mọi lệnh:

.bazelrc

# Enable Bzlmod for every Bazel command
common --enable_bzlmod

Chỉ định tên kho lưu trữ cho không gian làm việc của bạn

WORKSPACE

Hàm workspace dùng để chỉ định tên kho lưu trữ cho không gian làm việc của bạn. Điều này cho phép tham chiếu một //foo:bar mục tiêu trong không gian làm việc dưới dạng @<workspace name>//foo:bar. Nếu bạn không chỉ định, tên kho lưu trữ mặc định cho không gian làm việc của bạn là __main__.
```
## WORKSPACE
workspace(name = "com_foo_bar")
```
Bzlmod

Bạn nên tham chiếu các mục tiêu trong cùng một không gian làm việc bằng cú pháp //foo:bar mà không có @<repo name>. Nhưng nếu cần cú pháp cũ, bạn có thể sử dụng tên mô-đun do hàm module chỉ định làm tên kho lưu trữ. Nếu tên mô-đun khác với tên kho lưu trữ cần thiết, bạn có thể sử dụng thuộc tính repo_name của hàm module để ghi đè tên kho lưu trữ.
```
## MODULE.bazel
module(
    name = "bar",
    repo_name = "com_foo_bar",
)
```

Tìm nạp các phần phụ thuộc bên ngoài dưới dạng mô-đun Bazel

Nếu phần phụ thuộc của bạn là một dự án Bazel, thì bạn có thể phụ thuộc vào dự án đó dưới dạng một mô-đun Bazel khi dự án đó cũng áp dụng Bzlmod.

WORKSPACE

Với WORKSPACE, bạn thường dùng các quy tắc kho lưu trữ http_archive hoặc git_repository để tải các nguồn của dự án Bazel xuống.

## 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()

Như bạn có thể thấy, đây là một mẫu phổ biến mà người dùng cần tải các phần phụ thuộc bắc cầu từ một macro của phần phụ thuộc. Giả sử cả bazel_skylib và rules_java đều phụ thuộc vào platform, phiên bản chính xác của phần phụ thuộc platform được xác định theo thứ tự của các macro.

Bzlmod

Với Bzlmod, miễn là phần phụ thuộc của bạn có trong Bazel Central Registry hoặc Bazel registry tuỳ chỉnh, bạn chỉ cần phụ thuộc vào phần phụ thuộc đó bằng chỉ thị bazel_dep.
```
## MODULE.bazel
bazel_dep(name = "bazel_skylib", version = "1.4.2")
bazel_dep(name = "rules_java", version = "6.1.1")
```
Bzlmod giải quyết các phần phụ thuộc của mô-đun Bazel một cách bắc cầu bằng cách sử dụng thuật toán MVS. Do đó, phiên bản tối đa bắt buộc của platform sẽ được chọn tự động.

Ghi đè một phần phụ thuộc dưới dạng mô-đun Bazel

Là mô-đun gốc, bạn có thể ghi đè các phần phụ thuộc của mô-đun Bazel theo nhiều cách.

Vui lòng đọc phần ghi đè để biết thêm thông tin.

Bạn có thể tìm thấy một số ví dụ về cách sử dụng trong kho lưu trữ examples.

Tìm nạp các phần phụ thuộc bên ngoài bằng tiện ích mô-đun

Nếu phần phụ thuộc của bạn không phải là một dự án Bazel hoặc chưa có trong bất kỳ sổ đăng ký Bazel nào, bạn có thể giới thiệu phần phụ thuộc đó bằng cách sử dụng use_repo_rule hoặc các tiện ích mô-đun.

WORKSPACE

Tải tệp xuống bằng quy tắc kho lưu trữ 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

Với Bzlmod, bạn có thể dùng chỉ thị use_repo_rule trong tệp MODULE.bazel để trực tiếp tạo thực thể cho các kho lưu trữ:
```
## 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",
)
```
Theo cách không rõ ràng, việc này được triển khai bằng cách sử dụng một tiện ích mô-đun. Nếu cần thực hiện logic phức tạp hơn là chỉ cần gọi một quy tắc kho lưu trữ, bạn cũng có thể tự triển khai một tiện ích mô-đun. Bạn cần di chuyển định nghĩa vào tệp .bzl. Thao tác này cũng cho phép bạn chia sẻ định nghĩa giữa WORKSPACE và Bzlmod trong thời gian di chuyển.
```
## 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",
    )
```
Triển khai một tiện ích mô-đun để tải macro phần phụ thuộc. Bạn có thể xác định nó trong cùng một tệp .bzl của macro, nhưng để duy trì khả năng tương thích với các phiên bản Bazel cũ, bạn nên xác định nó trong một tệp .bzl riêng biệt.
```
## 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,
)
```
Để dự án gốc có thể thấy kho lưu trữ, bạn nên khai báo các cách sử dụng của tiện ích mô-đun và kho lưu trữ trong tệp MODULE.bazel.
```
## MODULE.bazel
non_module_dependencies = use_extension("//:extensions.bzl", "non_module_dependencies")
use_repo(non_module_dependencies, "data_file")
```

Giải quyết các phần phụ thuộc bên ngoài xung đột bằng tiện ích mô-đun

Một dự án có thể cung cấp một macro giới thiệu các kho lưu trữ bên ngoài dựa trên dữ liệu đầu vào từ các trình gọi của dự án. Nhưng nếu có nhiều lệnh gọi trong biểu đồ phần phụ thuộc và chúng gây ra xung đột thì sao?

Giả sử dự án foo cung cấp macro sau đây lấy version làm đối số.

## 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

Với WORKSPACE, bạn có thể tải macro từ @foo và chỉ định phiên bản của phần phụ thuộc dữ liệu mà bạn cần. Giả sử bạn có một phần phụ thuộc khác là @bar, phần phụ thuộc này cũng phụ thuộc vào @foo nhưng yêu cầu một phiên bản khác của phần phụ thuộc dữ liệu.
```
## 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")
```
Trong trường hợp này, người dùng cuối phải điều chỉnh cẩn thận thứ tự của các macro trong WORKSPACE để có được phiên bản mà họ cần. Đây là một trong những điểm khó khăn lớn nhất với WORKSPACE vì nó không thực sự cung cấp một cách hợp lý để giải quyết các phần phụ thuộc.

Bzlmod

Với Bzlmod, tác giả của dự án foo có thể sử dụng tiện ích mô-đun để giải quyết xung đột. Ví dụ: giả sử bạn luôn chọn phiên bản tối đa bắt buộc của phần phụ thuộc dữ liệu trong số tất cả các mô-đun 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")

Trong trường hợp này, mô-đun gốc yêu cầu phiên bản dữ liệu 2.0, trong khi phần phụ thuộc bar yêu cầu 3.0. Tiện ích mô-đun trong foo có thể giải quyết chính xác xung đột này và tự động chọn phiên bản 3.0 cho phần phụ thuộc dữ liệu.

Tích hợp trình quản lý gói của bên thứ ba

Sau phần cuối cùng, vì tiện ích mô-đun cung cấp một cách để thu thập thông tin từ biểu đồ phần phụ thuộc, thực hiện logic tuỳ chỉnh để phân giải các phần phụ thuộc và gọi các quy tắc kho lưu trữ để giới thiệu các kho lưu trữ bên ngoài, nên điều này mang đến một cách tuyệt vời để tác giả quy tắc nâng cao các bộ quy tắc tích hợp trình quản lý gói cho các ngôn ngữ cụ thể.

Vui lòng đọc trang tiện ích mô-đun để tìm hiểu thêm về cách sử dụng tiện ích mô-đun.

Dưới đây là danh sách các nhóm quy tắc đã áp dụng Bzlmod để tìm nạp các phần phụ thuộc từ nhiều trình quản lý gói:

Bạn có thể xem một ví dụ tối giản tích hợp trình quản lý gói giả tại kho lưu trữ examples.

Phát hiện chuỗi công cụ trên máy chủ

Khi các quy tắc tạo Bazel cần phát hiện những chuỗi công cụ có trên máy chủ lưu trữ, các quy tắc này sẽ sử dụng quy tắc kho lưu trữ để kiểm tra máy chủ lưu trữ và tạo thông tin chuỗi công cụ dưới dạng kho lưu trữ bên ngoài.

WORKSPACE

Cho trước quy tắc kho lưu trữ sau đây để phát hiện một chuỗi công cụ 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,
)

Bạn có thể tải quy tắc kho lưu trữ trong WORKSPACE.

## WORKSPACE
load("//:local_config_sh.bzl", "sh_config_rule")
sh_config_rule(name = "local_config_sh")

Bzlmod

Với Bzlmod, bạn có thể giới thiệu cùng một kho lưu trữ bằng cách sử dụng một tiện ích mô-đun, tương tự như việc giới thiệu kho lưu trữ @data_file trong phần cuối cùng.

## 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"),
)

Sau đó, hãy sử dụng tiện ích này trong tệp 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")

Đăng ký chuỗi công cụ và nền tảng thực thi

Sau phần cuối cùng, sau khi giới thiệu thông tin về chuỗi công cụ lưu trữ kho lưu trữ (ví dụ: local_config_sh), có lẽ bạn muốn đăng ký chuỗi công cụ.

WORKSPACE

Với WORKSPACE, bạn có thể đăng ký chuỗi công cụ theo những cách sau.

Bạn có thể đăng ký chuỗi công cụ trong tệp .bzl và tải macro trong tệp 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()

Hoặc đăng ký chuỗi công cụ trực tiếp trong tệp 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

Với Bzlmod, các API register_toolchains và register_execution_platforms chỉ có trong tệp MODULE.bazel. Bạn không thể gọi native.register_toolchains trong một tiện ích mô-đun.

## 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")

Các chuỗi công cụ và nền tảng thực thi được đăng ký trong WORKSPACE, WORKSPACE.bzlmod và tệp MODULE.bazel của mỗi mô-đun Bazel tuân theo thứ tự ưu tiên này trong quá trình chọn chuỗi công cụ (từ cao nhất đến thấp nhất):

toolchain và nền tảng thực thi được đăng ký trong tệp MODULE.bazel của mô-đun gốc.
toolchain và nền tảng thực thi được đăng ký trong tệp WORKSPACE hoặc WORKSPACE.bzlmod.
toolchain và nền tảng thực thi do các mô-đun đăng ký (phụ thuộc bắc cầu) của mô-đun gốc.
khi không sử dụng WORKSPACE.bzlmod: toolchain được đăng ký trong hậu tố WORKSPACE.

Giới thiệu kho lưu trữ cục bộ

Bạn có thể cần giới thiệu một phần phụ thuộc dưới dạng kho lưu trữ cục bộ khi cần một phiên bản cục bộ của phần phụ thuộc để gỡ lỗi hoặc bạn muốn kết hợp một thư mục trong không gian làm việc của mình dưới dạng kho lưu trữ bên ngoài.

WORKSPACE

Với WORKSPACE, bạn có thể thực hiện việc này bằng 2 quy tắc kho lưu trữ gốc, local_repository và new_local_repository.
```
## WORKSPACE
local_repository(
    name = "rules_java",
    path = "/Users/bazel_user/workspace/rules_java",
)
```
Bzlmod

Với Bzlmod, bạn có thể dùng local_path_override để ghi đè một mô-đun bằng đường dẫn cục bộ.
```
## MODULE.bazel
bazel_dep(name = "rules_java")
local_path_override(
    module_name = "rules_java",
    path = "/Users/bazel_user/workspace/rules_java",
)
```
Lưu ý: Với local_path_override, bạn chỉ có thể giới thiệu một thư mục cục bộ làm mô-đun Bazel. Điều này có nghĩa là thư mục đó phải có tệp MODULE.bazel và các phần phụ thuộc bắc cầu của thư mục đó sẽ được xem xét trong quá trình phân giải phần phụ thuộc. Ngoài ra, tất cả các chỉ thị ghi đè mô-đun chỉ có thể được sử dụng bởi mô-đun gốc.

Bạn cũng có thể giới thiệu một kho lưu trữ cục bộ bằng tiện ích mô-đun. Tuy nhiên, bạn không thể gọi native.local_repository trong tiện ích mô-đun, hiện đang có nỗ lực liên tục để chuyển đổi tất cả các quy tắc kho lưu trữ gốc sang Starlark (xem #18285 để biết tiến trình). Sau đó, bạn có thể gọi local_repository starlark tương ứng trong một tiện ích mô-đun. Bạn cũng có thể dễ dàng triển khai phiên bản tuỳ chỉnh của quy tắc kho lưu trữ local_repository nếu đây là vấn đề chặn đối với bạn.

Mục tiêu liên kết

Quy tắc bind trong WORKSPACE không được dùng nữa và không được hỗ trợ trong Bzlmod. Thư viện này được giới thiệu để cung cấp cho mục tiêu một biệt hiệu trong gói //external đặc biệt. Tất cả người dùng phụ thuộc vào thành phần này đều phải di chuyển.

Ví dụ: Nếu bạn có

## WORKSPACE
bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

Điều này cho phép các mục tiêu khác phụ thuộc vào //external:openssl. Bạn có thể di chuyển khỏi chế độ này bằng cách:

Thay thế tất cả các cách sử dụng //external:openssl bằng @my-ssl//src:openssl-lib.
- Mẹo: Sử dụng lệnh bazel query --output=build --noenable_bzlmod --enable_workspace [target] để tìm thông tin liên quan về mục tiêu.
Hoặc sử dụng quy tắc tạo alias
- Xác định mục tiêu sau đây trong một gói (ví dụ: //third_party)
```
## third_party/BUILD
alias(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)
```
- Thay thế tất cả các cách sử dụng //external:openssl bằng //third_party:openssl.

Tìm nạp so với Đồng bộ hoá

Các lệnh tìm nạp và đồng bộ hoá được dùng để tải các kho lưu trữ bên ngoài xuống thiết bị và cập nhật chúng. Đôi khi, bạn cũng có thể cho phép tạo ngoại tuyến bằng cách sử dụng cờ --nofetch sau khi tìm nạp tất cả các kho lưu trữ cần thiết cho bản dựng.

WORKSPACE

Đồng bộ hoá sẽ thực hiện thao tác tìm nạp bắt buộc cho tất cả các kho lưu trữ hoặc cho một tập hợp kho lưu trữ cụ thể đã định cấu hình, trong khi tìm nạp chỉ được dùng để tìm nạp cho một mục tiêu cụ thể.
Bzlmod

Lệnh đồng bộ hoá không còn áp dụng được nữa, nhưng lệnh tìm nạp cung cấp nhiều lựa chọn. Bạn có thể tìm nạp một mục tiêu, một kho lưu trữ, một tập hợp các kho lưu trữ đã định cấu hình hoặc tất cả các kho lưu trữ có liên quan đến quá trình phân giải phần phụ thuộc và các tiện ích mô-đun. Kết quả tìm nạp được lưu vào bộ nhớ đệm và để buộc tìm nạp, bạn phải thêm lựa chọn --force trong quá trình tìm nạp.

Di chuyển theo cách thủ công

Phần này cung cấp thông tin và hướng dẫn hữu ích cho quy trình di chuyển Bzlmod thủ công. Để biết thêm về quy trình di chuyển tự động, hãy xem phần quy trình di chuyển được đề xuất.

Biết các phần phụ thuộc của bạn trong WORKSPACE

Bước đầu tiên của quá trình di chuyển là tìm hiểu những phần phụ thuộc mà bạn có. Có thể khó xác định chính xác những phần phụ thuộc nào được giới thiệu trong tệp WORKSPACE vì các phần phụ thuộc bắc cầu thường được tải bằng macro *_deps.

Kiểm tra phần phụ thuộc bên ngoài bằng tệp đã phân giải trong không gian làm việc

Rất may là cờ --experimental_repository_resolved_file có thể giúp ích. Cờ này về cơ bản sẽ tạo ra một "tệp khoá" của tất cả các phần phụ thuộc bên ngoài đã tìm nạp trong lệnh Bazel gần đây nhất của bạn. Bạn có thể xem thêm thông tin chi tiết trong bài đăng này trên blog.

Bạn có thể sử dụng tính năng này theo 2 cách:

Để tìm nạp thông tin về các phần phụ thuộc bên ngoài cần thiết để tạo các mục tiêu nhất định.
```
bazel clean --expunge
bazel build --nobuild --experimental_repository_resolved_file=resolved.bzl //foo:bar
```
Để tìm nạp thông tin của tất cả các phần phụ thuộc bên ngoài được xác định trong tệp WORKSPACE.
```
bazel clean --expunge
bazel sync --experimental_repository_resolved_file=resolved.bzl
```
Với lệnh bazel sync, bạn có thể tìm nạp tất cả các phần phụ thuộc được xác định trong tệp WORKSPACE, bao gồm:
- Mức sử dụng bind
- register_toolchains và register_execution_platforms cách sử dụng
Tuy nhiên, nếu dự án của bạn là đa nền tảng, thì quá trình đồng bộ hoá bazel có thể bị gián đoạn trên một số nền tảng nhất định vì một số quy tắc kho lưu trữ chỉ có thể chạy chính xác trên các nền tảng được hỗ trợ.

Sau khi chạy lệnh, bạn sẽ có thông tin về các phần phụ thuộc bên ngoài trong tệp resolved.bzl.

Kiểm tra phần phụ thuộc bên ngoài bằng `bazel query`

Bạn cũng có thể biết rằng bazel query có thể được dùng để kiểm tra các quy tắc kho lưu trữ bằng

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

Mặc dù tiện lợi và nhanh hơn nhiều, nhưng truy vấn bazel có thể cung cấp thông tin sai về phiên bản phần phụ thuộc bên ngoài, vì vậy hãy cẩn thận khi sử dụng! Việc truy vấn và kiểm tra các phần phụ thuộc bên ngoài bằng Bzlmod sẽ được thực hiện bằng một lệnh con mới.

Các phần phụ thuộc mặc định có sẵn

Nếu kiểm tra tệp do --experimental_repository_resolved_file tạo, bạn sẽ thấy nhiều phần phụ thuộc không được xác định trong WORKSPACE. Điều này là do Bazel thực tế sẽ thêm tiền tố và hậu tố vào nội dung tệp WORKSPACE của người dùng để chèn một số phần phụ thuộc mặc định. Các phần phụ thuộc này thường được yêu cầu theo các quy tắc gốc (ví dụ: @bazel_tools, @platforms và @remote_java_tools). Với Bzlmod, các phần phụ thuộc đó được giới thiệu bằng một mô-đun tích hợp bazel_tools, đây là phần phụ thuộc mặc định cho mọi mô-đun Bazel khác.

Chế độ kết hợp để di chuyển dần

Bzlmod và WORKSPACE có thể hoạt động song song, cho phép di chuyển các phần phụ thuộc từ tệp WORKSPACE sang Bzlmod theo quy trình từng bước.

WORKSPACE.bzlmod

Trong quá trình di chuyển, người dùng Bazel có thể cần chuyển đổi giữa các bản dựng có và không bật Bzlmod. Hỗ trợ WORKSPACE.bzlmod được triển khai để giúp quy trình diễn ra suôn sẻ hơn.

WORKSPACE.bzlmod có cú pháp giống hệt như WORKSPACE. Khi Bzlmod được bật, nếu tệp WORKSPACE.bzlmod cũng tồn tại ở thư mục gốc của không gian làm việc:

WORKSPACE.bzlmod có hiệu lực và nội dung của WORKSPACE sẽ bị bỏ qua.
Không có tiền tố hoặc hậu tố nào được thêm vào tệp WORKSPACE.bzlmod.

Việc sử dụng tệp WORKSPACE.bzlmod có thể giúp quá trình di chuyển trở nên dễ dàng hơn vì:

Khi Bzlmod bị vô hiệu hoá, bạn sẽ quay lại tìm nạp các phần phụ thuộc từ tệp WORKSPACE ban đầu.
Khi bật Bzlmod, bạn có thể theo dõi tốt hơn những phần phụ thuộc còn lại cần di chuyển bằng WORKSPACE.bzlmod.

Chế độ hiển thị của kho lưu trữ

Bzlmod có thể kiểm soát những kho lưu trữ khác có thể nhìn thấy từ một kho lưu trữ nhất định, hãy kiểm tra tên kho lưu trữ và deps nghiêm ngặt để biết thêm thông tin chi tiết.

Dưới đây là thông tin tóm tắt về chế độ hiển thị kho lưu trữ của nhiều loại kho lưu trữ khi cũng xem xét WORKSPACE.

	Từ kho lưu trữ chính	Từ các kho lưu trữ mô-đun Bazel	Từ các kho lưu trữ tiện ích mô-đun	Từ các kho lưu trữ WORKSPACE
Kho lưu trữ chính	Hiển thị	Nếu mô-đun gốc là một phần phụ thuộc trực tiếp	Nếu mô-đun gốc là một phần phụ thuộc trực tiếp của mô-đun lưu trữ tiện ích mô-đun	Hiển thị
Kho lưu trữ mô-đun Bazel	Direct deps	Direct deps	Các phần phụ thuộc trực tiếp của mô-đun lưu trữ tiện ích mô-đun	Các phần phụ thuộc trực tiếp của mô-đun gốc
Kho lưu trữ tiện ích mô-đun	Direct deps	Direct deps	Các phần phụ thuộc trực tiếp của mô-đun lưu trữ tiện ích mô-đun + tất cả các kho lưu trữ do cùng một tiện ích mô-đun tạo ra	Các phần phụ thuộc trực tiếp của mô-đun gốc
Kho lưu trữ WORKSPACE	Tất cả đều hiển thị	Không hiển thị	Không hiển thị	Tất cả đều hiển thị

Quy trình di chuyển theo cách thủ công

Quy trình di chuyển Bzlmod điển hình có thể trông như sau:

Tìm hiểu những phần phụ thuộc mà bạn có trong WORKSPACE.
Thêm một tệp MODULE.bazel trống vào thư mục gốc của dự án.
Thêm một tệp WORKSPACE.bzlmod trống để ghi đè nội dung tệp WORKSPACE.
Tạo các mục tiêu của bạn khi Bzlmod được bật và kiểm tra xem kho lưu trữ nào bị thiếu.
Kiểm tra định nghĩa về kho lưu trữ bị thiếu trong tệp phần phụ thuộc đã phân giải.
Giới thiệu phần phụ thuộc bị thiếu dưới dạng một mô-đun Bazel, thông qua một tiện ích mô-đun hoặc để phần phụ thuộc đó trong WORKSPACE.bzlmod để di chuyển sau này.
Quay lại bước 4 và lặp lại cho đến khi có tất cả các phần phụ thuộc.

Xuất bản các mô-đun Bazel

Nếu dự án Bazel của bạn là một phần phụ thuộc cho các dự án khác, bạn có thể xuất bản dự án của mình trong Bazel Central Registry.

Để có thể kiểm tra dự án trong BCR, bạn cần có URL lưu trữ nguồn của dự án. Hãy lưu ý một số điều khi tạo tệp lưu trữ nguồn:

Đảm bảo rằng kho lưu trữ đang trỏ đến một phiên bản cụ thể.

BCR chỉ có thể chấp nhận các kho lưu trữ nguồn có phiên bản vì Bzlmod cần tiến hành so sánh phiên bản trong quá trình phân giải phần phụ thuộc.
Đảm bảo URL lưu trữ ổn định.

Bazel xác minh nội dung của kho lưu trữ bằng giá trị băm, vì vậy, bạn nên đảm bảo tổng kiểm tra của tệp đã tải xuống không bao giờ thay đổi. Nếu URL đó là của GitHub, vui lòng tạo và tải tệp lưu trữ bản phát hành lên trang phát hành. GitHub sẽ không đảm bảo tổng kiểm tra của các tệp lưu trữ nguồn được tạo theo yêu cầu. Tóm lại, URL ở dạng https://github.com/<org>/<repo>/releases/download/... được coi là ổn định, còn https://github.com/<org>/<repo>/archive/... thì không. Xem Sự cố về tổng kiểm tra lưu trữ GitHub để biết thêm thông tin.
Đảm bảo cây nguồn tuân theo bố cục của kho lưu trữ ban đầu.

Trong trường hợp kho lưu trữ của bạn rất lớn và bạn muốn tạo một kho lưu trữ phân phối có kích thước nhỏ hơn bằng cách loại bỏ các nguồn không cần thiết, vui lòng đảm bảo rằng cây nguồn đã loại bỏ là một tập hợp con của cây nguồn ban đầu. Điều này giúp người dùng cuối dễ dàng ghi đè mô-đun thành phiên bản không phát hành bằng cách archive_override và git_override.
Đưa một mô-đun kiểm thử vào một thư mục con để kiểm thử các API phổ biến nhất của bạn.

Mô-đun kiểm thử là một dự án Bazel có WORKSPACE và tệp MODULE.bazel riêng, nằm trong một thư mục con của kho lưu trữ nguồn, tuỳ thuộc vào mô-đun thực tế sẽ được xuất bản. Thư mục này phải chứa các ví dụ hoặc một số kiểm thử tích hợp bao gồm các API phổ biến nhất của bạn. Hãy kiểm tra mô-đun kiểm thử để tìm hiểu cách thiết lập.

Khi bạn đã chuẩn bị xong URL lưu trữ nguồn, hãy làm theo nguyên tắc đóng góp BCR để gửi mô-đun của bạn đến BCR bằng một Yêu cầu kéo trên GitHub.

Bạn rất nên thiết lập Ứng dụng GitHub Publish to BCR (Phát hành lên BCR) cho kho lưu trữ của mình để tự động hoá quy trình gửi mô-đun đến BCR.

Các phương pháp hay nhất

Phần này trình bày một số phương pháp hay nhất mà bạn nên tuân theo để quản lý các phần phụ thuộc bên ngoài hiệu quả hơn.

Chia các mục tiêu thành nhiều gói để tránh tìm nạp các phần phụ thuộc không cần thiết.

Kiểm tra #12835, trong đó các phần phụ thuộc của nhà phát triển đối với các kiểm thử buộc phải được tìm nạp một cách không cần thiết để tạo các mục tiêu không cần đến chúng. Điều này không chỉ dành riêng cho Bzlmod, mà việc tuân theo các phương pháp này còn giúp bạn dễ dàng chỉ định các phần phụ thuộc phát triển một cách chính xác.

Chỉ định các phần phụ thuộc dành cho quá trình phát triển

Bạn có thể đặt thuộc tính dev_dependency thành true cho các chỉ thị bazel_dep và use_extension để các chỉ thị này không truyền đến các dự án phụ thuộc. Là mô-đun gốc, bạn có thể sử dụng cờ --ignore_dev_dependency để xác minh xem các mục tiêu của bạn có còn được tạo mà không có các phần phụ thuộc và chế độ ghi đè dành cho nhà phát triển hay không.

Tiến trình di chuyển cộng đồng

Bạn có thể kiểm tra Bazel Central Registry để biết các phần phụ thuộc của bạn đã có sẵn hay chưa. Nếu không, bạn có thể tham gia cuộc thảo luận này trên GitHub để bình chọn hoặc đăng các phần phụ thuộc đang chặn quá trình di chuyển của bạn.

Báo cáo sự cố

Vui lòng kiểm tra danh sách vấn đề về Bazel trên GitHub để biết các vấn đề đã biết về Bzlmod. Bạn có thể gửi vấn đề mới hoặc yêu cầu về tính năng để giúp bạn hoàn tất quá trình di chuyển!

Hướng dẫn di chuyển Bzlmod

Tại sao nên di chuyển sang Bzlmod?

Cách di chuyển sang Bzlmod

Công cụ di chuyển

Chức năng cốt lõi

Cách sử dụng công cụ di chuyển

WORKSPACE so với Bzlmod

Xác định thư mục gốc của không gian làm việc Bazel

Bật Bzlmod trong bazelrc

Chỉ định tên kho lưu trữ cho không gian làm việc của bạn

Tìm nạp các phần phụ thuộc bên ngoài dưới dạng mô-đun Bazel

Ghi đè một phần phụ thuộc dưới dạng mô-đun Bazel

Tìm nạp các phần phụ thuộc bên ngoài bằng tiện ích mô-đun

Giải quyết các phần phụ thuộc bên ngoài xung đột bằng tiện ích mô-đun

Tích hợp trình quản lý gói của bên thứ ba

Phát hiện chuỗi công cụ trên máy chủ

Đăng ký chuỗi công cụ và nền tảng thực thi

Giới thiệu kho lưu trữ cục bộ

Mục tiêu liên kết

Tìm nạp so với Đồng bộ hoá

Di chuyển theo cách thủ công

Biết các phần phụ thuộc của bạn trong WORKSPACE

Kiểm tra phần phụ thuộc bên ngoài bằng tệp đã phân giải trong không gian làm việc

Kiểm tra phần phụ thuộc bên ngoài bằng bazel query

Các phần phụ thuộc mặc định có sẵn

Chế độ kết hợp để di chuyển dần

WORKSPACE.bzlmod

Chế độ hiển thị của kho lưu trữ

Quy trình di chuyển theo cách thủ công

Xuất bản các mô-đun Bazel

Các phương pháp hay nhất

Chia các mục tiêu thành nhiều gói để tránh tìm nạp các phần phụ thuộc không cần thiết.

Chỉ định các phần phụ thuộc dành cho quá trình phát triển

Tiến trình di chuyển cộng đồng

Báo cáo sự cố

Kiểm tra phần phụ thuộc bên ngoài bằng `bazel query`