Perintah mod

Laporkan masalah Lihat sumber Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Perintah mod, yang diperkenalkan pada Bazel 6.3.0, menyediakan berbagai alat untuk membantu pengguna memahami grafik dependensi eksternal saat Bzlmod diaktifkan. Alat ini memungkinkan Anda memvisualisasikan grafik dependensi, mencari tahu penyebab modul tertentu atau versi modul ada dalam grafik, melihat modul pendukung definisi repo, memeriksa penggunaan ekstensi modul dan repositori yang dihasilkan, di antara fungsi-fungsi lainnya.

Sintaksis

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

Subperintah yang tersedia dan argumen masing-masing yang diperlukan adalah:

  • graph: Menampilkan grafik dependensi lengkap project, mulai dari modul root. Jika satu atau beberapa modul ditentukan di --from, modul ini akan ditampilkan langsung di bawah root, dan grafik hanya diperluas mulai dari modul tersebut (lihat contoh).

  • deps <arg>...: Menampilkan dependensi langsung yang di-resolve dari setiap modul yang ditentukan, mirip dengan graph.

  • all_paths <arg>...: Menampilkan semua jalur yang ada dari root ke <arg>... yang ditentukan. Jika satu atau beberapa modul ditentukan di --from, modul ini ditampilkan langsung di bawah root, dan grafik berisi jalur yang ada dari modul --from ke modul argumen (lihat contoh).

  • path <arg>...: Memiliki semantik yang sama dengan all_paths, tetapi hanya menampilkan satu jalur dari salah satu modul --from ke salah satu modul argumen.

  • explain <arg>...: Menampilkan semua tempat di mana modul tertentu muncul dalam grafik dependensi, bersama dengan modul yang bergantung langsung pada modul tersebut. Output perintah explain pada dasarnya adalah versi pemangkasan dari perintah all_paths, yang berisi 1) modul root; 2) dependensi langsung modul root yang mengarah ke modul argumen; 3) dependen langsung modul argumen; dan 4) modul argumen itu sendiri (lihat contoh).

  • show_repo <arg>...: Menampilkan definisi repositori yang ditentukan (lihat contoh).

  • show_extension <extension>...: Menampilkan informasi tentang setiap ekstensi yang ditentukan: daftar repositori yang dihasilkan beserta modul yang mengimpornya menggunakan use_repo, dan daftar penggunaan ekstensi tersebut di setiap modul tempat ekstensi tersebut digunakan, yang berisi tag yang ditentukan dan panggilan use_repo (lihat contoh).

<arg> merujuk ke satu atau beberapa modul atau repo. Dapat berupa salah satu dari:

  • String literal <root>: Modul root yang mewakili project Anda saat ini.

  • <name>@<version>: Modul <name> pada versi <version>. Untuk modul dengan penggantian non-registry, gunakan garis bawah (_) sebagai <version>.

  • <name>: Semua versi modul <name> yang ada.

  • @<repo_name>: Repo dengan nama yang terlihat yang diberikan dalam konteks --base_module.

  • @@<repo_name>: Repo dengan nama kanonik tertentu.

Dalam konteks yang memerlukan penentuan modul, <arg> yang merujuk ke repositori yang sesuai dengan modul (bukan repositori yang dihasilkan ekstensi) juga dapat digunakan. Sebaliknya, dalam konteks yang memerlukan penentuan repo, <arg> yang merujuk ke modul dapat menggantikan repositori yang sesuai.

<extension> harus dalam bentuk <arg><label_to_bzl_file>%<extension_name>. Bagian <label_to_bzl_file> harus berupa label relatif repo (misalnya, //pkg/path:file.bzl).

Opsi berikut hanya memengaruhi subperintah yang mencetak grafik (graph, deps, all_paths, path, dan explain):

  • --from <arg>[,<arg>[,...]] default: <root>: Modul tempat grafik diperluas di graph, all_paths, path, dan explain. Periksa deskripsi subperintah untuk detail selengkapnya.

  • --verbose default: "false": Menyertakan informasi tambahan tentang resolusi versi setiap modul dalam grafik output. Jika versi modul berubah selama resolusi, tampilkan versi mana yang menggantikannya atau versi aslinya, alasan versi tersebut diganti, dan modul mana yang meminta versi baru jika alasannya adalah Minimal Version Selection.

  • --include_unused default: "false": Sertakan dalam grafik output modul yang awalnya ada dalam grafik dependensi, tetapi menjadi tidak digunakan setelah resolusi modul.

  • --extension_info <mode>: Menyertakan informasi tentang penggunaan ekstensi modul sebagai bagian dari grafik output (lihat contoh). <mode> dapat berupa salah satu dari:

    • hidden (default): Jangan tampilkan apa pun tentang ekstensi.

    • usages: Menampilkan ekstensi di bawah setiap modul tempat ekstensi digunakan. Kolom ini dicetak dalam bentuk $<extension>.

    • repos: Selain usages, tampilkan repo yang diimpor menggunakan use_repo di setiap penggunaan ekstensi.

    • all: Selain usages dan repos, tampilkan juga repositori yang dihasilkan ekstensi yang tidak diimpor oleh modul apa pun. Repositori tambahan ini ditampilkan di bawah kemunculan pertama ekstensi yang dihasilkan di output, dan terhubung dengan tepi putus-putus.

  • --extension_filter <extension>[,<extension>[,...]]: Jika ditentukan, grafik output hanya menyertakan modul yang menggunakan ekstensi yang ditentukan, dan jalur yang mengarah ke modul tersebut. Menentukan daftar ekstensi kosong (seperti dalam --extension_filter=) setara dengan menentukan semua ekstensi yang digunakan oleh modul apa pun dalam grafik dependensi.

  • --depth <N>: Kedalaman grafik output. Kedalaman 1 hanya menampilkan root dan dependensi langsungnya. Default-nya adalah 1 untuk explain, 2 untuk deps, dan tak terbatas untuk yang lainnya.

  • --cycles default: "false": Menyertakan tepi siklus dalam grafik output.

  • --include_builtin default: "false": Menyertakan modul bawaan (seperti @bazel_tools) dalam grafik output. Tanda ini dinonaktifkan secara default, karena modul bawaan secara implisit bergantung pada oleh setiap modul lain, yang akan sangat mengacaukan output.

  • --charset <charset> default: utf8: Menentukan charset yang akan digunakan untuk output teks. Nilai yang valid adalah "utf8" dan "ascii". Satu-satunya perbedaan signifikan adalah pada karakter khusus yang digunakan untuk menggambar grafik dalam format output "text", yang tidak ada dalam set karakter "ascii". Oleh karena itu, set karakter "ascii" juga ada untuk mendukung penggunaan di platform lama yang tidak dapat menggunakan Unicode.

  • --output <mode>: Sertakan informasi tentang penggunaan ekstensi modul sebagai bagian dari grafik output. <mode> dapat berupa salah satu dari:

    • text (default): Representasi grafik output yang dapat dibaca manusia (diratakan sebagai hierarki).

    • json: Menghasilkan grafik dalam bentuk objek JSON (yang diratakan sebagai hierarki).

    • graph: Menghasilkan grafik dalam representasi titik Graphviz.

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

Opsi lainnya mencakup:

  • --base_module <arg> default: <root>: Tentukan modul yang relatif terhadap nama repo yang terlihat dalam argumen yang ditafsirkan. Perhatikan bahwa argumen ini dapat berbentuk @<repo_name> yang selalu ditafsirkan secara relatif terhadap modul root.

  • --extension_usages <arg>[,<arg>[,...]]: Memfilter show_extension agar hanya menampilkan penggunaan ekstensi dari modul yang ditentukan.

Contoh

Beberapa kemungkinan penggunaan perintah mod pada project Bazel sebenarnya ditampilkan di bawah ini untuk memberi Anda gambaran umum tentang cara menggunakannya untuk memeriksa dependensi eksternal project Anda.

File 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")
Grafik Sebelum Penyelesaian
Grafik Sebelum Resolusi
Grafik Setelah Resolusi
Grafik Setelah Resolusi

  1. Menampilkan seluruh grafik dependensi project Anda.

    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. Menampilkan seluruh grafik dependensi (termasuk modul yang tidak digunakan dan dengan informasi tambahan tentang resolusi versi).

    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. Menampilkan grafik dependensi yang diperluas dari beberapa modul tertentu.

    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. Menampilkan semua jalur di antara dua modul.

    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. Lihat alasan dan cara project Anda bergantung pada beberapa modul.

    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. Lihat aturan dasar dari beberapa repo modul Anda.

    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. Lihat ekstensi modul yang digunakan dalam grafik dependensi Anda.

    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. Lihat repositori yang dihasilkan dan diimpor dari beberapa ekstensi tertentu sebagai bagian dari grafik dependensi.

    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. Lihat daftar repositori ekstensi yang dihasilkan dan cara ekstensi tersebut digunakan dalam setiap modul.

    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. Lihat aturan dasar dari beberapa repositori yang dihasilkan ekstensi.

    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>