Do những thiếu sót của WORKSPACE, Bzlmod sẽ thay thế hệ thống WORKSPACE cũ trong các bản phát hành sau này của Bazel. Hướng dẫn này giúp bạn di chuyển dự án sang Bzlmod và bỏ WORKSPACE để tìm nạp các phần phụ thuộc bên ngoài.
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ú 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ể trong WORKSPACE sang Bzlmod.
Xác định gốc của không gian làm việc Bazel
Tệp WORKSPACE đánh dấu gốc nguồn của 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 phiên bản Bazel trước 6.3, bạn vẫn nên có tệp WORKSPACE
hoặc WORKSPACE.bazel
ở thư mục gốc của không gian làm việc, có thể với các nhận xét như:
KHÔNG gian làm việc
# This file marks the root of the Bazel workspace. # See MODULE.bazel for external dependencies setup.
Bật Bzlmod trong bazelrc của bạn
.bazelrc
cho phép bạn đặt cờ sẽ áp dụng mỗi khi bạn chạy Bazel. Để bật Bzlmod, hãy sử dụng cờ --enable_bzlmod
và áp dụng cho lệnh common
để á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
KHÔNG gian làm việc
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. Việc này cho phép//foo:bar
mục tiêu trong không gian làm việc được tham chiếu là@<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 đến 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>
. Tuy nhiên, nếu cần cú pháp cũ, bạn có thể sử dụng tên mô-đun do hàmmodule
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ínhrepo_name
của hàmmodule
để 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, bạn có thể dựa vào dự án đó dưới dạng mô-đun Bazel khi nó cũng sử dụng Bzlmod.
KHÔNG gian làm việc
Với WORKSPACE, bạn thường sử dụng quy tắc kho lưu trữ
http_archive
hoặcgit_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, đó 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àoplatform
, phiên bản chính xác của phần phụ thuộcplatform
được xác định theo thứ tự của macro.Bzlmod
Với Bzlmod, miễn là phần phụ thuộc của bạn có trong Bazel Central Registry hoặc Cơ quan đăng ký Bazel tuỳ chỉnh, bạn chỉ cần dựa vào phần phụ thuộc đó bằng lệnh
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 mô-đun Bazel theo cách bắc cầu bằng thuật toán MVS. Do đó, phiên bản cần thiết tối đa của
platform
sẽ tự động được chọn.
Ghi đè 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 mô-đun Bazel theo nhiều cách.
Vui lòng đọc phần overrides để biết thêm thông tin.
Bạn có thể xem một số cách sử dụng mẫu trong kho lưu trữ ví dụ.
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ỳ cơ quan quản lý nào của Bazel, 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 phần mở rộng của mô-đun.
KHÔNG gian làm việc
Tải một 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ể sử dụng lệnh
use_repo_rule
trong tệp MODULE.bazel để tạo bản sao kho lưu trữ trực tiếp:## 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", )
Về sau, việc này được triển khai bằng tiện ích mô-đun. Nếu cần thực hiện logic phức tạp hơn thay vì chỉ gọi quy tắc repo, bạn cũng có thể tự triển khai phần mở rộng mô-đun. Bạn sẽ cần di chuyển phần định nghĩa vào tệp
.bzl
. Việc này cũng cho phép bạn chia sẻ định nghĩa giữa WORKSPACE và Bzlmod trong quá trình 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 tiện ích mô-đun để tải macro phần phụ thuộc. Bạn có thể xác định các biến này trong cùng một tệp
.bzl
của macro, nhưng để giữ khả năng tương thích với các phiên bản Bazel cũ, tốt hơn là bạn nên xác định trong một tệp.bzl
riêng.## 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, )
Để hiển thị kho lưu trữ cho dự án gốc, bạn nên khai báo các trường hợp sử dụng 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ừ phương thức gọi của dự án đó. Nhưng điều gì sẽ xảy ra nếu có nhiều phương thức gọi trong biểu đồ phần phụ thuộc và chúng gây ra xung đột?
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
)
KHÔNG gian làm việc
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@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 cẩn thận điều chỉnh thứ tự của các macro trong WORKSPACE để có được phiên bản họ cần. Đây là một trong những vấn đề lớn nhất với WORKSPACE vì công cụ này 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ở rộng mô-đun để giải quyết xung đột. Ví dụ: giả sử bạn nên luôn chọn phiên bản tối đa cần thiết 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 khibar
phần phụ thuộc của mô-đun đó yêu cầu3.0
. Tiện ích mô-đun trongfoo
có thể giải quyết chính xác xung đột này và tự động chọn phiên bản3.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
Tiếp theo phần cuối, 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à quy tắc kho lưu trữ lệnh gọi để giới thiệu các kho lưu trữ bên ngoài, nên đây là một cách tuyệt vời để tác giả quy tắc cải thiện tập hợp 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 bộ quy tắc đã sử 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 thiểu tích hợp trình quản lý gói giả trong kho lưu trữ ví dụ.
Phát hiện chuỗi công cụ trên máy chủ lưu trữ
Khi các quy tắc xây dựng Bazel cần phát hiện những chuỗi công cụ có sẵn trên máy chủ của bạn, các quy tắc đó sẽ dùng các quy tắc kho lưu trữ để kiểm tra máy chủ và tạo thông tin chuỗi công cụ dưới dạng kho lưu trữ bên ngoài.
KHÔNG gian làm việc
Cho trước quy tắc kho lưu trữ sau đây để phát hiện 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 phần mở rộng mô-đun, tương tự như việc giới thiệu kho lưu trữ
@data_file
trong phần trước.## 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 đó sử dụng đuôi 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
Tiếp theo phần cuối, 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
), bạn nên đăng ký chuỗi công cụ.
KHÔNG gian làm việc
Bạn có thể đăng ký chuỗi công cụ theo những cách sau với WORKSPACE.
Bạn có thể đăng ký chuỗi công cụ 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()
Bạn cũng có thể đăng ký trực tiếp chuỗi công cụ 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ọinative.register_toolchains
trong 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 đã đăng ký trong WORKSPACE
, WORKSPACE.bzlmod
và tệp MODULE.bazel
của mỗi mô-đun Bazel đều tuân theo thứ tự ưu tiên sau trong quá trình lựa chọn chuỗi công cụ (từ cao nhất đến thấp nhất):
- chuỗi công cụ và nền tảng thực thi đã đăng ký trong tệp
MODULE.bazel
của mô-đun gốc. - chuỗi công cụ và nền tảng thực thi đã đăng ký trong tệp
WORKSPACE
hoặcWORKSPACE.bzlmod
. - chuỗi công cụ và nền tảng thực thi được đăng ký bởi các mô-đun là phần phụ thuộc ( bắc cầu) của mô-đun gốc.
- khi không sử dụng
WORKSPACE.bzlmod
: chuỗi công cụ được đăng ký trong hậu tốWORKSPACE
.
Ra mắt 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 phiên bản cục bộ của phần phụ thuộc để gỡ lỗi hoặc khi muốn tích hợp một thư mục trong không gian làm việc của mình làm kho lưu trữ bên ngoài.
KHÔNG gian làm việc
Với WORKSPACE, điều này đạt được nhờ hai quy tắc kho lưu trữ gốc là
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ể sử dụng
local_path_override
để ghi đè mô-đun có đườ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", )
Bạn cũng có thể giới thiệu một kho lưu trữ cục bộ có phần mở rộng mô-đun. Tuy nhiên, bạn không thể gọi
native.local_repository
trong phần mở rộng của mô-đun, chúng tôi vẫn đang nỗ lực xác định rõ tất cả các quy tắc của kho lưu trữ gốc (hãy kiểm tra #18285 để biết tiến trình). Sau đó, bạn có thể gọi starlarklocal_repository
tương ứng trong một tiện ích mô-đun. Việc 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 đề ngăn chặn bạn cũng gặp phải vấn đề.
Liên kết mục tiêu
Quy tắc bind
trong WORKSPACE không được dùng nữa và không được hỗ trợ trong Bzlmod. Phương thức này được giới thiệu để cung cấp cho một mục tiêu một bí danh trong gói //external
đặc biệt. Tất cả người dùng phụ thuộc vào chế độ cài đặt này sẽ di chuyển khỏi tài khoả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 trạng thái này bằng cách:
Thay thế mọi cách sử dụng của
//external:openssl
bằng@my-ssl//src:openssl-lib
.Hoặc sử dụng quy tắc tạo
alias
Xác định mục tiêu sau trong một gói (ví dụ:
//third_party
)## third_party/BUILD alias( name = "openssl", actual = "@my-ssl//src:openssl-lib", )
Thay thế mọi cách sử dụng của
//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 các kho lưu trữ đó. Đôi khi, bạn cũng có thể cho phép tạo bản dựng ở chế độ 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 một bản dựng.
KHÔNG gian làm việc
Tính năng đồng bộ hoá thực hiện việc buộc tìm nạp đối với tất cả các kho lưu trữ hoặc một tập hợp kho lưu trữ cụ thể đã định cấu hình, trong khi tính năng 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 quá trình tìm nạp cung cấp nhiều tuỳ 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ữ liên quan đến quá trình phân giải phần phụ thuộc và 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 tuỳ chọn
--force
trong quá trình tìm nạp.
Di chuyển
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 của bạn.
Tìm hiểu các phần phụ thuộc 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 bạn có. Bạn có thể khó tìm ra các phần phụ thuộc chính xác nào được đưa vào 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 không gian làm việc
Rất may là cờ --experimental_repository_resolved_file
có thể hỗ trợ bạn. Về cơ bản, cờ này 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ể tìm thêm chi tiết trong bài đăng trên blog này.
Có thể sử dụng theo 2 cách:
Để tìm nạp thông tin của các phần phụ thuộc bên ngoài cần thiết cho việc xây dựng một số 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ả 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ả phần phụ thuộc được xác định trong tệp WORKSPACE, bao gồm:bind
trường hợp sử dụng- Trường hợp sử dụng
register_toolchains
vàregister_execution_platforms
Tuy nhiên, nếu dự án của bạn có nhiều nền tảng, thì tính năng đồng bộ hoá bazel có thể gặp sự cố trên một số nền tảng nhất định vì một số quy tắc kho lưu trữ có thể chỉ chạy đúng cách trên các nền tảng được hỗ trợ.
Sau khi chạy lệnh, bạn sẽ có thông tin của 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 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ù phương thức này thuận tiện và nhanh hơn nhiều, nhưng truy vấn Bazel có thể thông tin 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 phương pháp này! Việc truy vấn và kiểm tra các phần phụ thuộc bên ngoài bằng Bzlmod sẽ đạt được bằng một lệnh con mới.
Các phần phụ thuộc mặc định tích hợp 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 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, thường là bắt buộc theo 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 đưa vào bằng 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 nhau, cho phép việc di chuyển các phần phụ thuộc từ tệp WORKSPACE sang Bzlmod sẽ diễn ra 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 đã bật và không bật Bzlmod. Tính năng hỗ trợ WORKSPACE.bzlmod được triển khai để giúp quá trình hoạt động trơn tru 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ủaWORKSPACE
sẽ bị bỏ qua.- Không 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 dễ dàng hơn vì:
- Khi Bzlmod bị tắt, 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 để di chuyển bằng WORKSPACE.bzlmod.
Chế độ hiển thị kho lưu trữ
Bzlmod có thể kiểm soát những kho lưu trữ nào khác sẽ hiển thị trong một kho lưu trữ nhất định, hãy xem tên kho lưu trữ và phần phụ thuộc nghiêm ngặt để biết thêm thông tin chi tiết.
Dưới đây là bản tóm tắt về chế độ hiển thị của kho lưu trữ từ các loại kho lưu trữ khác nhau khi cũng xem xét WORKSPACE.
Trong kho lưu trữ chính | Từ kho lưu trữ mô-đun Bazel | Từ kho lưu trữ tiện ích mô-đun | Từ kho lưu trữ WORKSPACE | |
---|---|---|---|---|
Kho lưu trữ chính | Khả năng hiển thị | Nếu mô-đun gốc là phần phụ thuộc trực tiếp | Nếu mô-đun gốc là phần phụ thuộc trực tiếp của mô-đun lưu trữ tiện ích mô-đun | Khả năng hiển thị |
Kho lưu trữ mô-đun Bazel | Phần phụ thuộc trực tiếp | Phần phụ thuộc trực tiếp | Phần phụ thuộc trực tiếp của mô-đun lưu trữ tiện ích mô-đun | Phần phụ thuộc trực tiếp của mô-đun gốc |
Kho lưu trữ tiện ích mô-đun | Phần phụ thuộc trực tiếp | Phần phụ thuộc trực tiếp | 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ữ được tạo bởi cùng một tiện ích mô-đun | Phần phụ thuộc trực tiếp của mô-đun gốc |
Kho lưu trữ WORKSPACE | Hiển thị tất cả | Không hiển thị | Không hiển thị | Hiển thị tất cả |
Quá trình di chuyển
Quy trình di chuyển Bzlmod thông thường có thể diễn ra như sau:
- Tìm hiểu những phần phụ thuộc bạn có trong WORKSPACE.
- Thêm một tệp MODULE.bazel trống tại 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 mục tiêu khi bật Bzlmod 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.
- Ra mắt 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.
- Quay lại 4 và lặp lại cho đến khi tất cả phần phụ thuộc đều có sẵn.
Công cụ di chuyển
Có một tập lệnh trợ giúp di chuyển Bzlmod có thể tương tác để giúp bạn bắt đầu.
Tập lệnh sẽ thực hiện những việc sau:
- Tạo và phân tích cú pháp tệp đã phân giải WORKSPACE.
- In thông tin kho lưu trữ từ tệp đã phân giải theo cách có thể đọc được.
- Chạy lệnh tạo bản dựng bazel, phát hiện các thông báo lỗi đã nhận dạng được và đề xuất cách di chuyển.
- Kiểm tra xem đã có phần phụ thuộc trong BCR hay chưa.
- Thêm phần phụ thuộc vào tệp MODULE.bazel.
- Thêm phần phụ thuộc thông qua tiện ích mô-đun.
- Thêm phần phụ thuộc vào tệp WORKSPACE.bzlmod.
Để sử dụng công cụ này, hãy đảm bảo bạn đã cài đặt bản phát hành Bazel mới nhất và chạy lệnh sau:
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>
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ể phát hành dự án đó trong Bazel Central Registry.
Để có thể kiểm tra dự án trong BCR, bạn cần có một 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 tệp lưu trữ trỏ đến một phiên bản cụ thể.
BCR chỉ có thể chấp nhận các phiên bản lưu trữ nguồ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 tệp lưu trữ bằng một giá trị băm. Vì vậy, bạn nên đảm bảo giá trị tổng kiểm của tệp đã tải xuống không bao giờ thay đổi. Nếu URL đến từ GitHub, vui lòng tạo và tải bản lưu trữ bản phát hành lên trang phát hành. GitHub không đảm bảo tổng kiểm tra của các bản lưu trữ nguồn được tạo theo yêu cầu. Tóm lại, các URL ở dạng
https://github.com/<org>/<repo>/releases/download/...
được coi là ổn định cònhttps://github.com/<org>/<repo>/archive/...
thì không ổn định. Hãy xem Kho lưu trữ giá trị tổng hợp của 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ữ gốc.
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 giảm kích thước 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 đã bị xoá là một tậ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 lên một 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 thư mục con kiểm thử các API phổ biến nhất.
Mô-đun kiểm thử là một dự án Bazel có tệp WORKSPACE và MODULE.bazel riêng nằm trong thư mục con của kho lưu trữ nguồn phụ thuộc vào mô-đun thực tế sẽ được xuất bản. Tệp này sẽ 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 xem mô-đun kiểm thử để tìm hiểu cách thiết lập.
Khi bạn đã có 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 tới BCR bằng Yêu cầu kéo GitHub.
Bạn nên thiết lập Ứng dụng GitHub Phát hành lên BCR cho kho lưu trữ để tự động hoá quy trình gửi mô-đun cho 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 làm theo để quản lý hiệu quả hơn các phần phụ thuộc bên ngoài.
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 cho kiểm thử buộc phải 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. Phương thức này không thực sự không cụ thể với Bzlmod, nhưng việc làm theo các phương pháp này sẽ giúp bạn dễ dàng chỉ định các phần phụ thuộc của nhà phát triển hơn một cách chính xác.
Chỉ định các phần phụ thuộc của nhà phát triển
Bạn có thể đặt thuộc tính dev_dependency
thành true cho các lệnh bazel_dep
và use_extension
để chúng 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 mục tiêu của bạn có còn tạo bản dựng mà không có phần phụ thuộc nhà phát triển hay không.
Tiến trình di chuyển của cộng đồng
Bạn có thể kiểm tra Bazel Central Registry để tìm hiểu xem các phần phụ thuộc của bạn đã có sẵn hay chưa. Nếu không, đừng ngại tham gia cuộc thảo luận trên GitHub này để ủng hộ 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 vấn đề
Vui lòng xem danh sách vấn đề Bazel trên GitHub để biết các vấn đề Bzlmod đã biết. Bạn có thể gửi vấn đề hoặc yêu cầu về tính năng mới để có thể giúp bỏ chặn quá trình di chuyển!