คำสั่ง mod

คำสั่ง mod ซึ่งเปิดตัวใน Bazel 6.3.0 มีเครื่องมือมากมายเพื่อช่วยให้ผู้ใช้เข้าใจกราฟทรัพยากร Dependency ภายนอกเมื่อเปิดใช้ Bzlmod ซึ่งช่วยให้คุณเห็นภาพกราฟทรัพยากร Dependency เพื่อดูสาเหตุที่มีบางโมดูลหรือโมดูลบางเวอร์ชันในกราฟ ดูคำจำกัดความของที่เก็บสำรองโมดูล ตรวจสอบการใช้งานส่วนขยายโมดูล และที่เก็บที่สร้างขึ้น รวมถึงฟังก์ชันอื่นๆ

ไวยากรณ์

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

คำสั่งย่อยที่ใช้ได้และอาร์กิวเมนต์ที่จำเป็นที่เกี่ยวข้องมีดังนี้

  • graph: แสดงกราฟความเกี่ยวข้องทั้งหมดของโปรเจ็กต์โดยเริ่มจากโมดูลรูท หากระบุโมดูลอย่างน้อย 1 รายการใน --from โมดูลเหล่านี้จะแสดงใต้รูทโดยตรง และกราฟจะขยายออกโดยเริ่มจากโมดูลดังกล่าวเท่านั้น (ดูตัวอย่าง)

  • deps <arg>...: แสดงทรัพยากร Dependency โดยตรงที่แก้ไขแล้วของแต่ละโมดูลที่ระบุ เช่นเดียวกับ graph

  • all_paths <arg>...: แสดงเส้นทางที่มีอยู่ทั้งหมดจากรูทไปยัง <arg>... ที่ระบุ หากระบุโมดูลอย่างน้อย 1 รายการใน --from โมดูลเหล่านี้จะแสดงใต้รูทโดยตรง และกราฟจะมีเส้นทางที่มีอยู่จากโมดูล --from ไปยังโมดูลอาร์กิวเมนต์ (ดูตัวอย่าง)

  • path <arg>...: มีความหมายเหมือนกับ all_paths แต่แสดงเฉพาะเส้นทางเดียวจากหนึ่งในโมดูล --from ไปยังหนึ่งในโมดูลอาร์กิวเมนต์

  • explain <arg>...: แสดงตำแหน่งทั้งหมดที่โมดูลที่ระบุปรากฏในกราฟทรัพยากร Dependency พร้อมกับโมดูลที่ขึ้นต่อกันโดยตรง เอาต์พุตของคำสั่ง explain เป็นเวอร์ชันที่ถูกตัดออกของคำสั่ง all_paths ซึ่งประกอบด้วย 1) โมดูลราก 2) การขึ้นต่อกันโดยตรงของโมดูลรากที่นำไปสู่โมดูลอาร์กิวเมนต์ 3) การอ้างอิงโดยตรงของโมดูลอาร์กิวเมนต์ และ 4) โมดูลอาร์กิวเมนต์เอง (ดูตัวอย่าง)

  • show_repo <arg>...: แสดงคำจำกัดความของที่เก็บที่ระบุ (ดูตัวอย่าง)

  • show_extension <extension>...: แสดงข้อมูลเกี่ยวกับส่วนขยายที่ระบุแต่ละรายการ ได้แก่ รายการที่เก็บข้อมูลที่สร้างขึ้นพร้อมกับโมดูลที่นําเข้าโดยใช้ use_repo และรายการการใช้งานส่วนขยายนั้นในแต่ละโมดูลที่ใช้ โดยมีแท็กที่ระบุและการเรียกใช้ use_repo (ดูตัวอย่าง)

<arg> หมายถึงโมดูลหรือที่เก็บอย่างน้อย 1 รายการ ซึ่งอาจเป็นค่าใดค่าหนึ่งต่อไปนี้

  • สตริงลิเทอรัล <root>: โมดูลรูทที่แสดงโปรเจ็กต์ปัจจุบัน

  • <name>@<version>: โมดูล <name> ในเวอร์ชัน <version> สำหรับโมดูลที่มีการลบล้างที่ไม่ใช่รีจิสทรี ให้ใช้เครื่องหมายขีดล่าง (_) เป็น <version>

  • <name>: โมดูล <name> เวอร์ชันปัจจุบันทั้งหมด

  • @<repo_name>: ที่เก็บที่มีชื่อที่ปรากฏที่ระบุในบริบทของ --base_module

  • @@<repo_name>: ที่เก็บที่มีชื่อ Canonical ที่ระบุ

ในบริบทที่กำหนดให้ระบุโมดูล คุณสามารถใช้ <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 ค่าเริ่มต้น: "false": รวมข้อมูลเพิ่มเติมเกี่ยวกับความละเอียดของเวอร์ชันของโมดูลแต่ละรายการไว้ในกราฟเอาต์พุต หากเวอร์ชันของข้อบังคับมีการเปลี่ยนแปลงระหว่างการแก้ไข ให้แสดงเวอร์ชันที่แทนที่หรือเวอร์ชันเดิม เหตุผลที่แทนที่ และข้อบังคับที่ขอเวอร์ชันใหม่หากเหตุผลคือการเลือกเวอร์ชันขั้นต่ำ

  • --include_unused ค่าเริ่มต้น: "เท็จ": รวมโมดูลเดิมที่อยู่ในกราฟความเกี่ยวข้องไว้ในกราฟเอาต์พุต แต่ไม่ได้ใช้งานหลังจากการแก้ไขโมดูล

  • --extension_info <mode>: ใส่ข้อมูลเกี่ยวกับการใช้งานส่วนขยายของข้อบังคับในกราฟเอาต์พุต (ดูตัวอย่าง) <mode> อาจเป็นอย่างใดอย่างหนึ่งต่อไปนี้

    • hidden (ค่าเริ่มต้น): ไม่แสดงข้อมูลใดๆ เกี่ยวกับส่วนขยาย

    • usages: แสดงชิ้นงานในส่วนต่างๆ ของโมดูลที่ใช้ชิ้นงานนั้น โดยพิมพ์ในรูปแบบ $<extension>

    • repos: นอกเหนือจาก usages ให้แสดงที่เก็บที่นำเข้าโดยใช้ use_repo ในส่วนการใช้ส่วนขยายแต่ละรายการด้วย

    • all: นอกเหนือจาก usages และ repos แล้ว ยังแสดงรีพอสิทที่สร้างขึ้นจากส่วนขยายซึ่งไม่มีโมดูลใดนำเข้า รีพอสิทเพิ่มเติมเหล่านี้จะแสดงอยู่ใต้การปรากฏครั้งแรกของนามสกุลที่ทำให้เกิดในเอาต์พุต และเชื่อมต่อกันด้วยเส้นประ

  • --extension_filter <extension>[,<extension>[,...]]: หากระบุไว้ กราฟเอาต์พุตจะมีเฉพาะโมดูลที่ใช้ส่วนขยายที่ระบุและเส้นทางที่นำไปยังโมดูลเหล่านั้น การระบุรายการส่วนขยายว่าง (เช่น ใน --extension_filter=) เทียบเท่ากับการระบุส่วนขยายทั้งหมดที่โมดูลใดก็ตามในกราฟ Dependency ใช้

  • --depth <N>: ความลึกของกราฟเอาต์พุต ความลึก 1 จะแสดงเฉพาะรูทและรายการที่ขึ้นต่อกันโดยตรงเท่านั้น ค่าเริ่มต้นคือ 1 สำหรับ explain, 2 สำหรับ deps และอินฟินิตี้สำหรับรายการอื่นๆ

  • --cycles ค่าเริ่มต้น: "false": รวมขอบวงจรในกราฟเอาต์พุต

  • --include_builtin ค่าเริ่มต้น: "เท็จ": รวมโมดูลในตัว (เช่น @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 เพื่อแสดงเฉพาะการใช้ส่วนขยายจากโมดูลที่ระบุ

ตัวอย่าง

ด้านล่างนี้คือตัวอย่างการใช้งานคำสั่ง mod ในโปรเจ็กต์ Bazel จริงด้านล่างเพื่อให้คุณเห็นภาพทั่วไปว่าจะใช้คำสั่ง mod เพื่อตรวจสอบทรัพยากร Dependency ภายนอกของโปรเจ็กต์ได้อย่างไร

ไฟล์ 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. แสดงกราฟทรัพยากร Dependency ทั้งหมดของโปรเจ็กต์

    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. แสดงกราฟทรัพยากร Dependency ที่ขยายจากโมดูลที่เฉพาะเจาะจงบางรายการ

    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. แสดงเส้นทางทั้งหมดระหว่าง 2 โมดูล

    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~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. ดูการใช้ส่วนขยายโมดูลในกราฟการอ้างอิง

    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. ดูว่าที่เก็บใดสร้างขึ้นและนำเข้าจากส่วนขยายบางรายการในกราฟทรัพยากร Dependency

    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~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>