Lệnh sửa đổi

Báo cáo vấn đề Xem nguồn Nightly · 7.4 .

Lệnh mod được giới thiệu trong Bazel 6.3.0 cung cấp một loạt công cụ để giúp người dùng hiểu biểu đồ phần phụ thuộc bên ngoài khi bật Bzlmod. Công cụ này cho phép bạn trực quan hoá biểu đồ phần phụ thuộc, tìm hiểu lý do một mô-đun hoặc phiên bản của một mô-đun nhất định xuất hiện trong biểu đồ, xem các định nghĩa của kho lưu trữ hỗ trợ các mô-đun, kiểm tra việc sử dụng các phần mở rộng của mô-đun và kho lưu trữ chúng tạo ra, cùng nhiều hàm khác.

Cú pháp

bazel mod <subcommand> [<options>] [<arg> [<arg>...]]

Các lệnh con hiện có và đối số bắt buộc tương ứng là:

  • graph: Hiển thị biểu đồ phần phụ thuộc đầy đủ của dự án, bắt đầu từ mô-đun gốc. Nếu bạn chỉ định một hoặc nhiều mô-đun trong --from, thì các mô-đun này sẽ hiển thị ngay trong thư mục gốc và biểu đồ chỉ mở rộng từ các mô-đun đó (xem ví dụ).

  • deps <arg>...: Hiển thị các phần phụ thuộc trực tiếp đã phân giải của từng mô-đun được chỉ định, tương tự như graph.

  • all_paths <arg>...: Hiển thị tất cả các đường dẫn hiện có từ gốc đến <arg>... được chỉ định. Nếu bạn chỉ định một hoặc nhiều mô-đun trong --from, thì các mô-đun này sẽ hiển thị ngay trong thư mục gốc và biểu đồ sẽ chứa mọi đường dẫn hiện có từ mô-đun --from đến mô-đun đối số (xem ví dụ).

  • path <arg>...: Có ngữ nghĩa giống như all_paths, nhưng chỉ hiển thị một đường dẫn từ một trong các mô-đun --from đến một trong các mô-đun đối số.

  • explain <arg>...: Cho biết tất cả vị trí mà các mô-đun đã chỉ định xuất hiện trong biểu đồ phần phụ thuộc, cùng với các mô-đun trực tiếp phụ thuộc vào các mô-đun đó. Về cơ bản, kết quả của lệnh explain là một phiên bản đã cắt bớt của lệnh all_paths, chứa 1) mô-đun gốc; 2) các phần phụ thuộc trực tiếp của mô-đun gốc dẫn đến mô-đun đối số; 3) các phần phụ thuộc trực tiếp của mô-đun đối số; và 4) chính các mô-đun đối số (xem ví dụ).

  • show_repo <arg>...: Hiển thị định nghĩa của các kho lưu trữ đã chỉ định (xem ví dụ).

  • show_extension <extension>...: Hiển thị thông tin về từng tiện ích được chỉ định: danh sách các kho lưu trữ được tạo cùng với các mô-đun nhập các tiện ích đó bằng use_repo và danh sách cách sử dụng tiện ích đó trong mỗi mô-đun được sử dụng tiện ích, chứa các thẻ được chỉ định và lệnh gọi use_repo (xem ví dụ).

<arg> đề cập đến một hoặc nhiều mô-đun hoặc kho lưu trữ. Đó có thể là một trong những loại sau:

  • Chuỗi ký tự <root>: Mô-đun gốc đại diện cho dự án hiện tại của bạn.

  • <name>@<version>: Mô-đun <name> ở phiên bản <version>. Đối với một mô-đun có cơ chế ghi đè không phải cơ quan đăng ký, hãy sử dụng dấu gạch dưới (_) làm <version>.

  • <name>: Tất cả phiên bản hiện tại của mô-đun <name>.

  • @<repo_name>: Kho lưu trữ có tên rõ ràng đã cho trong bối cảnh --base_module.

  • @@<repo_name>: Kho lưu trữ có tên chuẩn hoá đã cho.

Trong ngữ cảnh yêu cầu chỉ định mô-đun, bạn cũng có thể sử dụng <arg> tham chiếu đến các kho lưu trữ tương ứng với mô-đun (thay vì kho lưu trữ do tiện ích tạo). Ngược lại, trong bối cảnh yêu cầu chỉ định kho lưu trữ, <arg> tham chiếu đến các mô-đun có thể thay thế cho các kho lưu trữ tương ứng.

<extension> phải ở dạng <arg><label_to_bzl_file>%<extension_name>. Phần <label_to_bzl_file> phải là nhãn tương đối lưu trữ (ví dụ: //pkg/path:file.bzl).

Các tuỳ chọn sau chỉ ảnh hưởng đến các lệnh con in biểu đồ (graph, deps, all_paths, path và explain):

  • --from <arg>[,<arg>[,...]] mặc định: <root>: (Các) mô-đun mà từ đó biểu đồ được mở rộng trong graph, all_paths, path và explain. Hãy xem nội dung mô tả của các lệnh con để biết thêm thông tin chi tiết.

  • --verbose mặc định: "false": Thêm vào biểu đồ đầu ra thông tin bổ sung về độ phân giải phiên bản của từng mô-đun. Nếu phiên bản mô-đun thay đổi trong quá trình phân giải, hãy cho biết phiên bản nào đã thay thế phiên bản đó hoặc phiên bản ban đầu là gì, lý do thay thế phiên bản đó và mô-đun nào đã yêu cầu phiên bản mới nếu lý do là Lựa chọn phiên bản tối thiểu.

  • --include_unused mặc định: "false": Đưa vào biểu đồ đầu ra các mô-đun ban đầu có trong biểu đồ phần phụ thuộc nhưng không được sử dụng sau khi phân giải mô-đun.

  • --extension_info <mode>: Thêm thông tin về cách sử dụng tiện ích mô-đun vào biểu đồ đầu ra (xem ví dụ). <mode> có thể là một trong những loại sau:

    • hidden (mặc định): Không hiển thị thông tin nào về tiện ích.

    • usages: Hiển thị các tiện ích trong mỗi mô-đun nơi chúng được sử dụng. Các mã này được in ở dạng $<extension>.

    • repos: Ngoài usages, hãy hiển thị kho lưu trữ được nhập bằng use_repo trong mỗi lần sử dụng tiện ích.

    • all: Ngoài usages và repos, cũng hiển thị các kho lưu trữ do tiện ích tạo mà không có mô-đun nào nhập. Các kho lưu trữ bổ sung này xuất hiện trong lần đầu tiên tạo tiện ích trong dữ liệu đầu ra và được kết nối với một cạnh có dấu chấm.

  • --extension_filter <extension>[,<extension>[,...]]: Nếu được chỉ định, biểu đồ đầu ra chỉ bao gồm các mô-đun sử dụng các tiện ích đã chỉ định và các đường dẫn dẫn đến các mô-đun đó. Việc chỉ định danh sách tiện ích trống (như trong --extension_filter=) tương đương với việc chỉ định tất cả tiện ích mà bất kỳ mô-đun nào trong biểu đồ phần phụ thuộc sử dụng.

  • --depth <N>: Chiều sâu của biểu đồ đầu ra. Độ sâu 1 chỉ hiển thị thư mục gốc và các phần phụ thuộc trực tiếp của thư mục gốc đó. Giá trị mặc định là 1 cho explain, 2 cho deps và vô hạn cho các giá trị khác.

  • --cycles mặc định: "false": Bao gồm các cạnh chu kỳ trong biểu đồ đầu ra.

  • --include_builtin default: "false": Đưa các mô-đun tích hợp sẵn (chẳng hạn như @bazel_tools) vào biểu đồ đầu ra. Cờ này bị tắt theo mặc định, vì các mô-đun tích hợp sẵn bị ngầm phụ thuộc vào mọi mô-đun khác, làm lộn xộn đầu ra.

  • --charset <charset> mặc định: utf8: Chỉ định bộ ký tự để sử dụng cho đầu ra văn bản. Các giá trị hợp lệ là "utf8" và "ascii". Điểm khác biệt đáng kể duy nhất là ở các ký tự đặc biệt dùng để vẽ biểu đồ ở định dạng đầu ra "text", không có trong bộ ký tự "ascii". Do đó, bộ ký tự "ascii" cũng hỗ trợ việc sử dụng trên các nền tảng cũ không thể sử dụng Unicode.

  • --output <mode>: Thêm thông tin về cách sử dụng tiện ích mô-đun vào biểu đồ đầu ra. <mode> có thể là một trong những giá trị sau:

    • text (mặc định): Biểu diễn mà con người có thể đọc được của biểu đồ đầu ra (được làm phẳng dưới dạng cây).

    • json: Xuất biểu đồ dưới dạng đối tượng JSON (được làm phẳng dưới dạng cây).

    • graph: Xuất biểu đồ ở dạng dot của Graphviz.

    bazel mod graph --output graph | dot -Tsvg > /tmp/graph.svg

Các lựa chọn khác bao gồm:

  • --base_module <arg> mặc định: <root>: Chỉ định một mô-đun liên quan đến tên kho lưu trữ rõ ràng trong các đối số được diễn giải. Xin lưu ý rằng đối số này có thể ở dạng @<repo_name>; đối số này luôn được diễn giải tương ứng với mô-đun gốc.

  • --extension_usages <arg>[,<arg>[,...]]: Lọc show_extension để chỉ hiển thị các trường hợp sử dụng tiện ích từ các mô-đun đã chỉ định.

Ví dụ

Một số cách sử dụng có thể có của lệnh mod trên một dự án Bazel thực tế được giới thiệu bên dưới để giúp bạn có ý tưởng chung về cách sử dụng lệnh này để kiểm tra các phần phụ thuộc bên ngoài của dự án.

Tệp MODULE.bazel:

module(
  name = "my_project",
  version = "1.0",
)

bazel_dep(name = "bazel_skylib", version = "1.1.1", repo_name = "skylib1")
bazel_dep(name = "bazel_skylib", version = "1.2.0", repo_name = "skylib2")
multiple_version_override(module_name = "bazel_skylib", versions = ["1.1.1", "1.2.0"])

bazel_dep(name = "stardoc", version = "0.5.0")
bazel_dep(name = "rules_java", version = "5.0.0")

toolchains = use_extension("@rules_java//java:extensions.bzl", "toolchains")
use_repo(toolchains, my_jdk="remotejdk17_linux")
Biểu đồ trước khi phân giải
Biểu đồ trước khi phân giải
Biểu đồ sau khi phân giải
Biểu đồ sau khi phân giải

  1. Hiển thị toàn bộ biểu đồ phần phụ thuộc của dự án.

    bazel mod graph

    <root> (my_project@1.0)
├───bazel_skylib@1.1.1
│   └───platforms@0.0.4
├───bazel_skylib@1.2.0
│   └───platforms@0.0.4 ...
├───rules_java@5.0.0
│   ├───platforms@0.0.4 ...
│   ├───rules_cc@0.0.1
│   │   ├───bazel_skylib@1.1.1 ...
│   │   └───platforms@0.0.4 ...
│   └───rules_proto@4.0.0
│       ├───bazel_skylib@1.1.1 ...
│       └───rules_cc@0.0.1 ...
└───stardoc@0.5.0
    ├───bazel_skylib@1.1.1 ...
    └───rules_java@5.0.0 ...

  2. Hiển thị toàn bộ biểu đồ phần phụ thuộc (bao gồm cả các mô-đun không dùng đến và thông tin bổ sung về độ phân giải phiên bản).

    bazel mod graph --include_unused --verbose

    <root> (my_project@1.0)
├───bazel_skylib@1.1.1
│   └───platforms@0.0.4
├───bazel_skylib@1.2.0
│   └───platforms@0.0.4 ...
├───rules_java@5.0.0
│   ├───platforms@0.0.4 ...
│   ├───rules_cc@0.0.1
│   │   ├───bazel_skylib@1.0.3 ... (to 1.1.1, cause multiple_version_override)
│   │   ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)
│   │   └───platforms@0.0.4 ...
│   └───rules_proto@4.0.0
│       ├───bazel_skylib@1.0.3 ... (to 1.1.1, cause multiple_version_override)
│       ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)
│       └───rules_cc@0.0.1 ...
└───stardoc@0.5.0
    ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)
    ├───rules_java@5.0.0 ... (was 4.0.0, cause <root>, bazel_tools@_)
    ├───bazel_skylib@1.0.3 (to 1.1.1, cause multiple_version_override)
    │   └───platforms@0.0.4 ...
    └───rules_java@4.0.0 (to 5.0.0, cause <root>, bazel_tools@_)
        ├───bazel_skylib@1.0.3 ... (to 1.1.1, cause multiple_version_override)
        └───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)

  3. Hiển thị biểu đồ phần phụ thuộc được mở rộng từ một số mô-đun cụ thể.

    bazel mod graph --from rules_java --include_unused

    <root> (my_project@1.0)
├───rules_java@5.0.0
│   ├───platforms@0.0.4
│   ├───rules_cc@0.0.1
│   │   ├───bazel_skylib@1.0.3 ... (unused)
│   │   ├───bazel_skylib@1.1.1 ...
│   │   └───platforms@0.0.4 ...
│   └───rules_proto@4.0.0
│       ├───bazel_skylib@1.0.3 ... (unused)
│       ├───bazel_skylib@1.1.1 ...
│       └───rules_cc@0.0.1 ...
└╌╌rules_java@4.0.0 (unused)
    ├───bazel_skylib@1.0.3 (unused)
    │   └───platforms@0.0.4 ...
    └───bazel_skylib@1.1.1
        └───platforms@0.0.4 ...

  4. Hiển thị tất cả đường dẫn giữa hai mô-đun.

    bazel mod all_paths bazel_skylib@1.1.1 --from rules_proto

    <root> (my_project@1.0)
└╌╌rules_proto@4.0.0
    ├───bazel_skylib@1.1.1
    └───rules_cc@0.0.1
        └───bazel_skylib@1.1.1 ...

  5. Xem lý do và cách dự án của bạn phụ thuộc vào một số mô-đun.

    bazel mod explain @skylib1 --verbose --include_unused

    <root> (my_project@1.0)
├───bazel_skylib@1.1.1
├───rules_java@5.0.0
│   ├───rules_cc@0.0.1
│   │   └───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)
│   └───rules_proto@4.0.0
│       ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)
│       └───rules_cc@0.0.1 ...
└───stardoc@0.5.0
    ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)
    ├╌╌rules_cc@0.0.1
    │   └───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)
    └╌╌rules_proto@4.0.0
        ├───bazel_skylib@1.1.1 ... (was 1.0.3, cause multiple_version_override)
        └───rules_cc@0.0.1 ...

  6. Xem quy tắc cơ bản của một số kho lưu trữ mô-đun.

    bazel mod show_repo rules_cc stardoc

    ## rules_cc@0.0.1:
# <builtin>
http_archive(
  name = "rules_cc~0.0.1",
  urls = ["https://bcr.bazel.build/test-mirror/github.com/bazelbuild/rules_cc/releases/download/0.0.1/rules_cc-0.0.1.tar.gz", "https://github.com/bazelbuild/rules_cc/releases/download/0.0.1/rules_cc-0.0.1.tar.gz"],
  integrity = "sha256-Tcy/0iwN7xZMj0dFi9UODHFI89kgAs20WcKpamhJgkE=",
  strip_prefix = "",
  remote_patches = {"https://bcr.bazel.build/modules/rules_cc/0.0.1/patches/add_module_extension.patch": "sha256-g3+zmGs0YT2HKOVevZpN0Jet89Ylw90Cp9XsIAY8QqU="},
  remote_patch_strip = 1,
)
# Rule http_archive defined at (most recent call last):
#   /home/user/.cache/bazel/_bazel_user/6e893e0f5a92cc4cf5909a6e4b2770f9/external/bazel_tools/tools/build_defs/repo/http.bzl:355:31 in <toplevel>

## stardoc:
# <builtin>
http_archive(
  name = "stardoc~0.5.0",
  urls = ["https://bcr.bazel.build/test-mirror/github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz", "https://github.com/bazelbuild/stardoc/releases/download/0.5.0/stardoc-0.5.0.tar.gz"],
  integrity = "sha256-yXlNzIAmow/2fPfPkeviRcopSyCwcYRdEsGSr+JDrXI=",
  strip_prefix = "",
  remote_patches = {},
  remote_patch_strip = 0,
)
# Rule http_archive defined at (most recent call last):
#   /home/user/.cache/bazel/_bazel_user/6e893e0f5a92cc4cf5909a6e4b2770f9/external/bazel_tools/tools/build_defs/repo/http.bzl:355:31 in <toplevel>

  7. Xem tiện ích mô-đun nào được sử dụng trong biểu đồ phần phụ thuộc.

    bazel mod graph --extension_info=usages --extension_filter=all

    <root> (my_project@1.0)
├───$@@rules_java.5.0.0//java:extensions.bzl%toolchains
├───rules_java@5.0.0 #
│   ├───$@@rules_java.5.0.0//java:extensions.bzl%toolchains
│   ├───rules_cc@0.0.1 #
│   │   └───$@@rules_cc.0.0.1//bzlmod:extensions.bzl%cc_configure
│   └───rules_proto@4.0.0
│       └───rules_cc@0.0.1 ...
└───stardoc@0.5.0
    └───rules_java@5.0.0 ...

  8. Xem những kho lưu trữ được tạo và nhập từ một số phần mở rộng cụ thể trong biểu đồ phần phụ thuộc.

    bazel mod show_extension @@rules_java~5.0.0//java:extensions.bzl%toolchains

    <root> (my_project@1.0)
├───$@@rules_java.5.0.0//java:extensions.bzl%toolchains
│   ├───remotejdk17_linux
│   ├╌╌remotejdk11_linux
│   ├╌╌remotejdk11_linux_aarch64
│   ├╌╌remotejdk11_linux_ppc64le
│   ├╌╌remotejdk11_linux_s390x
...(some lines omitted)...
├───rules_java@5.0.0 #
│   └───$@@rules_java.5.0.0//java:extensions.bzl%toolchains ...
│       ├───local_jdk
│       ├───remote_java_tools
│       ├───remote_java_tools_darwin
│       ├───remote_java_tools_linux
│       ├───remote_java_tools_windows
│       ├───remotejdk11_linux_aarch64_toolchain_config_repo
│       ├───remotejdk11_linux_ppc64le_toolchain_config_repo
...(some lines omitted)...
└───stardoc@0.5.0
    └───rules_java@5.0.0 ...

  9. Xem danh sách kho lưu trữ được tạo của một phần mở rộng và cách sử dụng phần mở rộng đó trong mỗi mô-đun.

    bazel mod graph --extension_info=all --extension_filter=@rules_java//java:extensions.bzl%toolchains

    ## @@rules_java.5.0.0//java:extensions.bzl%toolchains:

Fetched repositories:
  -   local_jdk (imported by bazel_tools@_, rules_java@5.0.0)
  -   remote_java_tools (imported by bazel_tools@_, rules_java@5.0.0)
  -   remote_java_tools_darwin (imported by bazel_tools@_, rules_java@5.0.0)
  -   remote_java_tools_linux (imported by bazel_tools@_, rules_java@5.0.0)
  -   remote_java_tools_windows (imported by bazel_tools@_, rules_java@5.0.0)
  -   remotejdk11_linux_aarch64_toolchain_config_repo (imported by rules_java@5.0.0)
  -   remotejdk11_linux_ppc64le_toolchain_config_repo (imported by rules_java@5.0.0)
...(some lines omitted)...
  -   remotejdk17_linux (imported by <root>)
  -   remotejdk11_linux
  -   remotejdk11_linux_aarch64
  -   remotejdk11_linux_ppc64le
  -   remotejdk11_linux_s390x
  -   remotejdk11_macos
...(some lines omitted)...

# Usage in <root> at <root>/MODULE.bazel:14:27 with the specified attributes:
use_repo(
  toolchains,
  my_jdk="remotejdk17_linux",
)

# Usage in bazel_tools@_ at bazel_tools@_/MODULE.bazel:23:32 with the specified attributes:
use_repo(
  toolchains,
  "local_jdk",
  "remote_java_tools",
  "remote_java_tools_linux",
  "remote_java_tools_windows",
  "remote_java_tools_darwin",
)

# Usage in rules_java@5.0.0 at rules_java@5.0.0/MODULE.bazel:30:27 with the specified attributes:
use_repo(
  toolchains,
  "remote_java_tools",
  "remote_java_tools_linux",
  "remote_java_tools_windows",
  "remote_java_tools_darwin",
  "local_jdk",
  "remotejdk11_linux_toolchain_config_repo",
  "remotejdk11_macos_toolchain_config_repo",
  "remotejdk11_macos_aarch64_toolchain_config_repo",
  ...(some lines omitted)...
)

  10. Xem quy tắc cơ bản của một số kho lưu trữ do tiện ích tạo.

    bazel mod show_repo --base_module=rules_java @remote_java_tools

    ## @remote_java_tools:
# <builtin>
http_archive(
  name = "rules_java~5.0.0~toolchains~remote_java_tools",
  urls = ["https://mirror.bazel.build/bazel_java_tools/releases/java/v11.5/java_tools-v11.5.zip", "https://github.com/bazelbuild/java_tools/releases/download/java_v11.5/java_tools-v11.5.zip"],
  sha256 = "b763ee80e5754e593fd6d5be6d7343f905bc8b73d661d36d842b024ca11b6793",
)
# Rule http_archive defined at (most recent call last):
#   /home/user/.cache/bazel/_bazel_user/6e893e0f5a92cc4cf5909a6e4b2770f9/external/bazel_tools/tools/build_defs/repo/http.bzl:355:31 in <toplevel>