Do những thiếu sót của WORKSPACE, Bzlmod sẽ tham gia thay thế hệ thống WORKSPACE cũ trong các bản phát hành Bazel sau này. Hướng dẫn này giúp bạn di chuyển dự án của mình sang Bzlmod và thả WORKSPACE để tìm nạp phần phụ thuộc.
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. Chiến dịch này 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 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. Có phiên bản Bazel
trước phiên bản 6.3 vẫn phải có tệp WORKSPACE
hoặc WORKSPACE.bazel
tại
thư mục gốc Workspace của bạn, có thể bằng 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ờ áp dụng mỗi khi chạy Bazel. Để bật
Bzlmod, sử dụng cờ --enable_bzlmod
và áp dụng cho lệnh common
để
quy tắ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
KHÔNG GIAN LÀM VIỆC
Hàm
workspace
được sử 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 mục tiêu//foo:bar
trong không gian làm việc để được tham chiếu là@<workspace name>//foo:bar
. Nếu không được chỉ định, tên kho lưu trữ mặc định cho không gian làm việc 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 với Cú pháp
//foo:bar
không có@<repo name>
. Nhưng nếu bạn cần cú pháp cũ , bạn có thể sử dụng tên mô-đun được chỉ định bởi Hàmmodule
đóng vai trò là 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ủamodule
để 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ể phụ thuộc vào nó như một Mô-đun Bazel khi mô-đun này cũng sử dụng Bzlmod.
KHÔNG GIAN LÀM VIỆC
Với WORKSPACE, người dùng thường sử dụng
http_archive
hoặcgit_repository
quy tắc lưu trữ để 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ô hình phổ biến mà người dùng cần để tải bắc cầu từ macro của phần phụ thuộc. Giả sử cả
bazel_skylib
vàrules_java
phụ thuộc vàoplatform
, phiên bản chính xác củaplatform
đượ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 Bazel tuỳ chỉnh của bạn , bạn có thể chỉ cần phụ thuộc vào tên miền đó bằng
bazel_dep
.## MODULE.bazel bazel_dep(name = "bazel_skylib", version = "1.4.2") bazel_dep(name = "rules_java", version = "6.1.1")
Bzlmod phân giải các phần phụ thuộc của mô-đun Bazel theo cách bắc cầu bằng cách sử dụng MVS. Do đó, giá trị tối đa phiên bản bắt buộc của
platform
được chọn tự động.
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 của mô-đun Bazel trong nhiều phần phụ thuộc nhiều cách.
Vui lòng đọc phần ghi đè để biết thêm của bạn.
Bạn có thể tìm thấy một số ví dụ về cách sử dụng trong ví dụ kho lưu trữ.
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 thuộc dự án Bazel hoặc chưa có trong bất kỳ dự án Bazel nào
sổ đăng ký tên miền, bạn có thể giới thiệu nó bằng cách sử dụng
use_repo_rule
hoặc mô-đun
tiện ích.
KHÔNG GIAN LÀM VIỆC
Tải tệp xuống bằng
http_file
quy tắc kho lưu trữ.## 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 MODULE.bazel để tạo trực tiếp 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", )
Về sau, việc này được triển khai bằng cách sử dụng tiện ích mô-đun. Nếu bạn cần thực hiện logic phức tạp hơn là chỉ gọi quy tắc repo, bạn cũng có thể tự triển khai 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 tiện ích mô-đun để tải macro phần phụ thuộc. Bạn có thể xác định trong cùng một tệp
.bzl
của macro, nhưng để duy trì khả năng tương thích với phiên bản Bazel cũ hơn, bạn nên xác định tệp này 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, )
Để dự án gốc hiển thị kho lưu trữ, bạn nên khai báo cách sử dụng đuôi 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 macro giới thiệu kho lưu trữ bên ngoài dựa trên đầu vào từ phương thức gọi. Nhưng nếu có nhiều người gọi trong biểu đồ phần phụ thuộc và chúng có gây ra xung đột không?
Giả sử dự án foo
cung cấp macro sau đây, lấy version
làm
một đố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 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
, quá trình này cũng phụ thuộc vào@foo
nhưng yêu cầu một phiên bản dữ liệu khác phần phụ thuộc.## 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 macro trong WORKSPACE để tải phiên bản họ cần. Đây là một trong những khó khăn lớn nhất điểm với WORKSPACE vì điều này không thực sự mang lại một cách hợp lý để phân giải 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 để phân giải 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 giữa 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ộcbar
yêu cầu3.0
. Tiện ích mô-đun trongfoo
có thể chính xác giải quyết xung đột này và tự động chọn phiên bản3.0
cho dữ liệu phần phụ thuộc.
Tích hợp trình quản lý gói của bên thứ ba
Tiếp nối phần trước, vì tiện ích mô-đun cung cấp 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 phần phụ thuộc và gọi quy tắc kho lưu trữ để giới thiệu các kho lưu trữ bên ngoài, cung cấp 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 phần mở rộng về 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 tập 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 về việc tích hợp trình quản lý gói giả tại ví dụ kho lưu trữ.
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 của Bazel cần phát hiện những chuỗi công cụ có trên máy chủ lưu trữ của bạn chúng sử dụng các quy tắc kho lưu trữ để kiểm tra máy chủ lưu trữ và tạo 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 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 tiện ích mô-đun, tương tự như việc giới thiệu kho lưu trữ
@data_file
trong .## 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 tệp 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ụ & nền tảng thực thi
Tiếp tục phần cuối, sau khi giới thiệu chuỗi công cụ lưu trữ kho lưu trữ
(ví dụ: local_config_sh
), bạn có thể muốn đăng ký
chuỗi công cụ.
KHÔNG GIAN LÀM VIỆC
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ụ cho tệp
.bzl
và tải macro trong 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ý 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,
register_toolchains
vàregister_execution_platforms
Các API 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 tuân theo các bước sau
thứ tự ưu tiên 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 mô-đun gốc
Tệp
MODULE.bazel
. - chuỗi công cụ và nền tảng thực thi đã đăng ký trong
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 các phần phụ thuộc (chuyển tiếp) của mô-đun gốc.
- khi không sử dụng
WORKSPACE.bzlmod
: chuỗi công cụ đã đăng ký trongWORKSPACE
hậu tố.
Ra mắt kho lưu trữ cục bộ
Bạn có thể phải giới thiệu một phần phụ thuộc làm kho lưu trữ cục bộ khi cần một phần phụ thuộc 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 trong không gian làm việc của mình dưới dạng 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,
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
đến 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", )
Bạn cũng có thể giới thiệu một kho lưu trữ cục bộ có đuôi mô-đun. Tuy nhiên, bạn không thể gọi
native.local_repository
trong tiện ích mô-đun, Chúng tôi vẫn đang nỗ lực làm rõ tất cả các quy tắc kho lưu trữ gốc (xem #18285 để xem tiến trình). Sau đó, bạn có thể gọi starlarklocal_repository
tương ứng trong một mô-đun tiện ích. Việc triển khai phiên bản tuỳ chỉnh củalocal_repository
quy tắc kho lưu trữ nếu đây là vấn đề gây trở ngại cho bạn.
Liên kết các 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. Tính năng này được ra mắt để tạo bí danh cho một mục tiêu trong
gói //external
đặc biệt. Tất cả người dùng phụ thuộc vào tuỳ chọn này sẽ di chuyển khỏi nhóm.
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
tránh xa điều 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 xây dựng
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-lib
.
Di chuyển
Phần này cung cấp thông tin và hướng dẫn hữu ích để bạn di chuyển Bzlmod của chúng tôi.
Tìm hiểu về 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 xem bạn có những phần phụ thuộc nào. Nó
có thể khó biết được chính xác phần phụ thuộc nào được đưa vào trong
Tệp WORKSPACE vì các phần phụ thuộc bắc cầu thường được tải bằng *_deps
macro.
Kiểm tra phần phụ thuộc bên ngoài bằng tệp đã giải quyết không gian làm việc
Rất may, lá cờ
--experimental_repository_resolved_file
có thể giúp bạn. Về cơ bản, cờ này tạo một "tệp khoá" trong tất cả tìm nạp bên ngoài
trong lệnh Bazel gần đây nhất. Bạn có thể xem thêm thông tin chi tiết trên blog này
bài đăng.
Có thể sử dụng theo hai 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 nhằm 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ả các phần phụ thuộc được xác định trong Tệp WORKSPACE, bao gồm:bind
lượt sử dụngregister_toolchains
vàregister_execution_platforms
lần sử dụng
Tuy nhiên, nếu dự án của bạn sử dụng nhiều nền tảng, thì tính năng đồng bộ hoá bazel có thể gặp lỗi trên một số vì một số quy tắc về kho lưu trữ chỉ có thể chạy chính xác trên nền tảng.
Sau khi chạy lệnh, bạn sẽ có thông tin về
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ữ thông qua
bazel query --output=build //external:<repo name>
Mặc dù thuận tiện hơn và nhanh hơn nhiều, truy vấn bazel có thể nói về phiên bản phần phụ thuộc bên ngoài nên hãy thận trọng khi sử dụng! Truy vấn và kiểm tra bên ngoài với Bzlmod sẽ đạt được bằng cách lệnh con.
Phần phụ thuộc mặc định tích hợp sẵn
Nếu bạn 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 của bạn.
Điều này là do trên thực tế, Bazel đã thêm các tiền tố và hậu tố vào WORKSPACE của người dùng
nội dung tệp để chèn một số phần phụ thuộc mặc định, thường được yêu cầu bởi
quy tắc gốc (ví dụ: @bazel_tools
, @platforms
và @remote_java_tools
). Bằng
Bzlmod, các phần phụ thuộc đó được đưa vào bằng một mô-đun tích hợp sẵn
bazel_tools
là phần phụ thuộc mặc định cho mỗi phần tử khác
Mô-đun Bazel.
Chế độ kết hợp để di chuyển dần
Bzlmod và WORKSPACE có thể hoạt động song song với nhau, cho phép di chuyển các phần phụ thuộc từ tệp WORKSPACE sang Bzlmod thành một quá trình dần dần.
WORKSPACE.bzlmod
Trong quá trình di chuyển, người dùng Bazel có thể cần phải chuyển đổi giữa các bản dựng có và mà không bật Bzlmod. Dịch vụ hỗ trợ WORKSPACE.bzlmod được triển khai để giúp 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 Workspace:
WORKSPACE.bzlmod
có hiệu lực và nội dung củaWORKSPACE
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 tắt Bzlmod, bạn sẽ quay lại tìm nạp các phần phụ thuộc từ tệp WORKSPACE gốc.
- 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 xem kho lưu trữ nào khác được hiển thị từ một kho lưu trữ cụ thể kho lưu trữ, hãy kiểm tra tên kho lưu trữ và phần phụ thuộc để biết thêm chi tiết.
Sau đây là bản tóm tắt về khả năng hiển thị của kho lưu trữ từ các loại kho lưu trữ khi cũng cân nhắc đến WORKSPACE.
Từ 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 | 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 | Hiển thị |
Kho lưu trữ mô-đun Bazel | Phần phụ thuộc Direct | Phần phụ thuộc Direct | 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 Direct | Phần phụ thuộc Direct | 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 | Tất cả đều hiển thị | Không hiển thị | Không hiển thị | Tất cả đều hiển thị |
Quá trình di chuyển
Quy trình di chuyển Bzlmod điển hình có thể có dạng 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 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 của tệp WORKSPACE.
- Xây dựng 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ữ còn thiếu trong phần phụ thuộc đã được phân giải .
- Ra mắt phần phụ thuộc còn thiếu dưới dạng mô-đun Bazel thông qua một mô-đun hoặc để tiện ích này trong WORKSPACE.bzlmod để di chuyển sau này.
- Quay lại 4 và lặp lại cho đến khi tất cả phần phụ thuộc đều xuất hiện.
Công cụ di chuyển
Có một tập lệnh trình trợ giúp di chuyển Bzlmod tương tác có thể giúp bạn bắt đầu.
Tập lệnh thực hiện những việc sau:
- Tạo và phân tích cú pháp tệp đã giải quyết WORKSPACE.
- In thông tin kho lưu trữ từ tệp đã phân giải theo cách mà con người có thể đọc được.
- Chạy lệnh bản dựng bazel, phát hiện các thông báo lỗi đã nhận dạng và đề xuất di chuyển.
- Kiểm tra xem phần phụ thuộc đã 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 sau đây:
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à phần phụ thuộc của các dự án khác, bạn có thể xuất bản dự án này trong Bazel Central Registry (Sổ đăng ký trung tâm Bazel).
Để 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 bản 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 bản 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 rằng 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 hãy đả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 là trên GitHub, hãy tạo và tải một 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ác bản lưu trữ nguồn được tạo trên nhu cầu của bạn. Một cách ngắn gọn, URL có dạng
https://github.com/<org>/<repo>/releases/download/...
được coi là ổn định trong khihttps://github.com/<org>/<repo>/archive/...
thì không. Kiểm tra GitHub Lưu trữ giá trị tổng kiểm Ngừng dịch vụ để biết thêm ngữ cảnh.Đả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 bản phân phối tệp lưu trữ có kích thước giảm bằng cách loại bỏ các nguồn không cần thiết, hãy đảm bảo cây nguồn bị loại bỏ là một tập con của cây nguồn ban đầu. Chiến dịch này giúp người dùng cuối dễ dàng ghi đè mô-đun thành một bản phát hành không phải bản phát hành phiên bản của
archive_override
vàgit_override
.Thêm mô-đun kiểm thử trong một thư mục con giúp kiểm thử các mô-đun phổ biến nhất API.
Mô-đun kiểm thử là một dự án Bazel có WORKSPACE và MODULE.bazel riêng tệp 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ế được xuất bản. URL này nên 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. Séc mô-đun kiểm thử để tìm hiểu cách thiết lập.
Khi bạn đã có sẵn URL lưu trữ nguồn, hãy làm theo nội dung đóng góp của BCR hướng dẫn để gửi mô-đun của bạn đến BCR bằng một GitHub Yêu cầu lấy dữ liệu.
Bạn nên thiết lập tuỳ chọn Xuất bản lên Ứng dụng GitHub của BCR cho kho lưu trữ này để tự động hoá quy trình gửi mô-đun của bạn đế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 làm theo để quản lý các phần phụ thuộc bên ngoài.
Phân tách 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.
Xem #12835, trong đó nhà phát triển buộc phải tìm nạp các phần phụ thuộc cho chương trình kiểm thử một cách không cần thiết để tạo bản dựng các mục tiêu không cần chúng. Đây không phải là Bzlmod cụ thể, 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 chính xác các phần phụ thuộc của nhà phát triển.
Chỉ định phần phụ thuộc nhà phát triển
Bạn có thể đặt thuộc tính dev_dependency
thành true cho
bazel_dep
và
use_extension
để
chúng không lan truyền
đến các dự án phụ thuộc. Là mô-đun gốc, bạn có thể sử dụng
--ignore_dev_dependency
gắn cờ để xác minh xem các mục tiêu của bạn có phải là
vẫn tạo được mà không có phần phụ thuộc của nhà phát triển.
Tiến trình di chuyển cộng đồng
Bạn có thể kiểm tra Sổ đăng ký Bazel Central Registry để tìm nếu các phần phụ thuộc của bạn đã có sẵn. Nếu không, hãy tham gia Thảo luận trên GitHub tới tán thành 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 đề của Bazel GitHub để biết các Bzlmod đã biết vấn đề. Bạn có thể thoải mái 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 của bạn!