mod 指令

回報問題 查看來源

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>...：顯示特定存放區的定義 (請參閱範例)。

  • show_extension <extension>...：顯示各個指定擴充功能的相關資訊：顯示產生的存放區清單，以及使用 use_repo 匯入這些擴充功能的模組清單，以及每個使用該擴充功能的模組中，該擴充功能使用情形的清單，包含指定標記和 use_repo 呼叫 (請參閱範例)。

<arg> 是指一或多個模組或存放區。可以是下列其中一項：

  • 常值字串 <root>：代表目前專案的根模組。

  • <name>@<version>：<name> 版的模組 <version>。若是採用非登錄檔覆寫設定的模組，請使用底線 (_) 做為 <version>。

  • <name>：模組 <name> 的所有現存版本。

  • @<repo_name>：在 --base_module 中含有指定 apparent name 的存放區。

  • @@<repo_name>：具有指定標準名稱的存放區。

在需要指定模組的情境中，您也可以使用 <arg> 參照與模組相對應的存放區 (相對於擴充功能產生的存放區)。相反地，在需要指定存放區的環境中，參照模組的 <arg> 可以停留在對應的存放區中。

<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>[,...]] 預設值：<root>：在 graph、all_paths、path 和 explain 中展開圖表的模組。詳情請參閱子指令的說明。

  • --verbose default: "false"：在輸出圖表中加入每個模組版本解析度的額外資訊。如果模組版本在解析期間有變更，請顯示取代版本或原始版本、替換原因，以及因選擇最小版本版本而要求新版本的模組。

  • --include_unused default: "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，其他則為無限大。

  • --cycles default: "false"：在輸出圖表中加入循環邊緣。

  • --include_builtin default: "false"：在輸出圖表中加入內建模組，例如 @bazel_tools。這個旗標預設為停用，因為內建模組是以隱含方式依附於其他模組，讓輸出內容看起來雜亂無章。

  • --charset <charset> default: utf8：指定要用於輸出文字的字元集。有效值為 "utf8" 和 "ascii"。唯一的顯著差異在於，使用 "text" 輸出格式繪製圖表時使用的特殊字元，並不存在於 "ascii" 字元集中。因此，系統提供 "ascii" 字元集，支援在無法使用萬國碼 (Unicode) 的舊版平台上使用。

  • --output <mode>：在輸出圖表中加入模組擴充功能使用情形的相關資訊。<mode> 可以是下列任一項：

    • text (預設)：使用者可理解的輸出圖表表示法 (以樹狀結構的形式平整合併)。

    • json：以 JSON 物件的形式輸出圖表 (以樹狀圖的形式整併)。

    • graph：輸出 Graphviz 點表示法的圖表。

    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")
解析度前的圖形
解析度前的圖形
解析度後的圖形
解析度修正的圖表

  1. 顯示專案的完整依附元件圖表。

    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. 顯示完整的依附元件圖表 (包括未使用的模組和版本解析額外資訊)。

    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. 顯示從某些特定模組展開的依附元件圖表。

    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. 顯示兩個模組之間的所有路徑。

    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. 瞭解專案依附於部分模組的原因和方式。

    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. 查看部分模組存放區的基本規則。

    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>

  7. 查看依附元件圖表中使用的模組擴充功能。

    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. 在依附元件圖表中，查看由特定擴充功能產生及匯入的存放區。

    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. 查看產生的擴充功能存放區清單，以及各模組如何使用該擴充功能。

    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. 查看部分擴充功能產生的存放區的基礎規則。

    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>