Bazel 6.3.0 推出的 mod 指令提供一系列工具，協助使用者瞭解啟用 Bzlmod 時的外部依附元件圖。您可以使用這項工具，以視覺化方式呈現依附元件圖表、找出圖表中出現特定模組或模組版本的理由、查看支援模組的存放區定義、檢查模組擴充功能及其產生的存放區用法，以及其他功能。
語法
bazel mod <subcommand> [<options>] [<arg> [<arg>...]]
可用的子指令和各自的必要引數如下：
graph：顯示專案的完整依附元件圖表，從根模組開始。如果在--from中指定一或多個模組，這些模組會直接顯示在根目錄下方，且圖表只會從這些模組開始展開 (請參閱範例)。deps <arg>...：顯示每個指定模組的已解析直接依附元件，與graph類似。all_paths <arg>...：顯示從根目錄到指定<arg>...的所有現有路徑。如果--from中指定了一或多個模組，這些模組會直接顯示在根目錄下方，且圖表會包含從--from模組到引數模組的任何現有路徑 (請參閱範例)。path <arg>...：語意與all_paths相同，但只會顯示從其中一個--from模組到其中一個引數模組的路徑。explain <arg>...：顯示指定模組在依附關係圖表中的所有位置，以及直接依附於這些模組的模組。explain指令的輸出內容基本上是all_paths指令的修剪版本，包含：1) 根模組；2) 根模組的直接依附元件 (會導向引數模組)；3) 引數模組的直接依附元件；以及 4) 引數模組本身 (請參閱範例)。show_repo <arg>...：顯示指定 repo 的定義 (請參閱範例)。show_extension <extension>...：顯示每個指定擴充功能的相關資訊：產生的存放區清單，以及使用use_repo匯入這些存放區的模組；此外，還會列出每個使用擴充功能的模組中，該擴充功能的用法，包括指定的標記和use_repo呼叫 (請參閱範例)。
<arg> 是指一或多個模組或存放區。可以是下列其中一項：
字串常值
<root>：代表目前專案的根模組。<name>@<version>：版本<version>的模組<name>。如要使用非登錄檔覆寫的模組，請使用底線 (_) 做為<version>。<name>：模組<name>的所有現有版本。@<repo_name>：在--base_module的脈絡中，具有指定顯而易見名稱的存放區。@@<repo_name>：具有指定標準名稱的存放區。
在需要指定模組的情境中，也可以使用 <arg>s 參照對應模組的存放區 (而非擴充功能產生的存放區)。反之，在需要指定存放區的情境中，<arg>s 參照模組可代表對應的存放區。
<extension> 必須採用 <arg><label_to_bzl_file>%<extension_name> 格式。<label_to_bzl_file> 部分必須是與存放區相關的標籤 (例如 //pkg/path:file.bzl)。
下列選項只會影響列印圖表的子指令 (graph、deps、all_paths、path 和 explain)：
--from <arg>[,<arg>[,...]]default:<root>：圖表在graph、all_paths、path和explain中展開的模組。如需更多詳細資料，請參閱子指令的說明。--verbosedefault: "false"：在輸出圖表中加入每個模組版本解析度的額外資訊。如果模組版本在解析期間有所變更，請顯示取代的版本或原始版本、取代原因，以及要求新版本的模組 (如果原因是最低版本選取)。--include_unuseddefault: "false"：在輸出圖表中納入原本存在於依附元件圖表，但在模組解析後變成未使用的模組。--extension_info <mode>：在輸出圖表中加入模組擴充功能用法的相關資訊 (請參閱範例)。<mode>可以是下列任一值：hidden(預設)：不顯示任何有關擴充功能的內容。usages：在每個使用擴充功能的模組下方顯示擴充功能。這些內容會以$<extension>的形式列印。repos：除了usages之外，還會顯示在每個擴充功能用量下，使用use_repo匯入的存放區。all：除了usages和repos，也顯示任何模組未匯入的擴充功能產生的存放區。這些額外存放區會顯示在輸出內容中，產生擴充功能的第一次出現位置下方，並以虛線邊緣連線。
--extension_filter <extension>[,<extension>[,...]]：如果指定，輸出圖表只會包含使用指定擴充功能的模組，以及通往這些模組的路徑。指定空白擴充功能清單 (如--extension_filter=) 等於指定依附元件圖表中任何模組使用的「所有」擴充功能。--depth <N>：輸出圖的深度。深度為 1 時，只會顯示根目錄及其直接依附元件。explain預設為 1，deps預設為 2，其他則為無限。--cyclesdefault: "false"：在輸出圖表中加入週期邊緣。--include_builtin預設值：「false」：在輸出圖表中加入內建模組 (例如@bazel_tools)。這項標記預設為停用，因為每個其他模組都會隱含地依附內建模組，這會大幅增加輸出內容的雜亂程度。--charset <charset>default: utf8：指定用於文字輸出的字元集。有效值為"utf8"和"ascii"。唯一顯著的差異在於用於繪製"text"輸出格式圖表的特殊字元，這些字元在"ascii"字元集中不存在。因此，系統會提供"ascii"字元集，以便支援無法使用 Unicode 的舊版平台。--output <mode>：在輸出圖表中加入模組擴充功能用法的相關資訊。<mode> 可以是下列任一值：text(預設)：輸出圖表的人類可讀表示法 (以樹狀結構形式扁平化)。json：以 JSON 物件的形式輸出圖表 (以樹狀結構扁平化)。graph：以 Graphviz dot 表示法輸出圖表。
bazel mod graph --output graph | dot -Tsvg > /tmp/graph.svg
您也可以採取以下做法：
--base_module <arg>default:<root>：指定模組，用來解讀引數中明顯的存放區名稱。請注意，這個引數本身可以是@<repo_name>形式，這類引數一律會相對於根模組解讀。--extension_usages <arg>[,<arg>[,...]]：篩選show_extension，只顯示指定模組的擴充功能用量。
範例
以下列舉在實際 Bazel 專案中使用 mod 指令的幾種可能方式，讓您大致瞭解如何使用這項指令檢查專案的外部依附元件。
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")
|
|
顯示專案的完整依附元件圖表。
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 ...顯示整個依附元件圖表 (包括未使用的模組，以及版本解析的額外資訊)。
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)顯示從特定模組展開的依附元件圖表。
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 ...顯示兩個模組之間的所有路徑。
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 ...瞭解專案依附於某些模組的原因和方式。
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 ...查看部分模組存放區的基礎規則。
bazel mod show_repo rules_cc stardoc## rules_cc@0.0.1: # <builtin> http_archive( name = "rules_cc+", 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+", 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>查看依附元件圖表中使用哪些模組擴充功能。
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 ...查看從特定擴充功能產生及匯入的存放區，這些存放區是依附元件圖表的一部分。
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 ...查看擴充功能產生的存放區清單，以及每個模組中如何使用該擴充功能。
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)... )查看擴充功能產生的一些存放區的基礎規則。
bazel mod show_repo --base_module=rules_java @remote_java_tools## @remote_java_tools: # <builtin> http_archive( name = "rules_java++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>