diff --git a/external/mod-command.mdx b/external/mod-command.mdx new file mode 100644 index 0000000..388b994 --- /dev/null +++ b/external/mod-command.mdx @@ -0,0 +1,528 @@ +--- +title: 'mod Command' +--- + +The `mod` command provides a range of tools to help the user understand their +external dependency graph. It lets you visualize the dependency graph, find out +why a certain module or a version of a module is present in the graph, view the +repo definitions backing modules, inspect usages of module extensions and repos +they generate, among other functions. + +## Syntax + +```sh +bazel mod [] [ [...]] +``` + +The available subcommands and their respective required arguments are: + +* `graph`: Displays the full dependency graph of the project, starting from + the root module. If one or more modules are specified in `--from`, these + modules are shown directly under the root, and the graph is only expanded + starting from them (see [example](#mod-example1)). + +* `deps ...`: Displays the resolved direct dependencies of each of the + specified modules, similarly to `graph`. + +* `all_paths ...`: Displays all dependency paths from the --from modules + to the target modules. To simplify the output, only the first shortest path + is shown when multiple paths share the same suffix. For example, A -> B -> X + would be shown, but the longer A -> C -> B -> X would be omitted. In other + words, for every module Y that directly depends on the target module X, the + output contains only the shortest path going through Y to reach X. + +* `path ...`: Has the same semantics as `all_paths`, but only display a + single path from one of the `--from` modules to one of the argument modules. + +* `explain ...`: Shows all the places where the specified modules appear + in the dependency graph, along with the modules that directly depend on + them. The output of the `explain` command is essentially a pruned version of + the `all_paths` command, containing 1) the root module; 2) the root module's + direct dependencies that lead to the argument modules; 3) the argument + modules' direct dependents; and + 4) the argument modules themselves (see [example](#mod-example5)). + +* `show_repo ...`: Displays the definition of the specified repos (see + [example](#mod-example6)). + +* `show_extension ...`: Displays information about each of the + specified extensions: a list of the generated repos along with the modules + that import them using `use_repo`, and a list of the usages of that + extension in each of the modules where it is used, containing the specified + tags and the `use_repo` calls (see [example](#mod-example8)). + +`` refers to one or more modules or repos. It can be one of: + +* The literal string ``: The root module representing your current + project. + +* `@`: The module `` at version ``. For a module + with a non-registry override, use an underscore (`_`) as the ``. + +* ``: All present versions of the module ``. + +* `@`: The repo with the given [apparent + name](/external/overview#apparent-repo-name) in the context of the `--base_module`. + +* `@@`: The repo with the given [canonical + name](/external/overview#canonical-repo-name). + +In a context requiring specifying modules, ``s referring to repos that +correspond to modules (as opposed to extension-generated repos) can also be +used. Conversely, in a context requiring specifying repos, ``s referring to +modules can stand in for the corresponding repos. + +`` must be of the form `%`. +The `` part must be a repo-relative label (for example, +`//pkg/path:file.bzl`). + +The following options only affect the subcommands that print graphs (`graph`, +`deps`, `all_paths`, `path`, and `explain`): + +* `--from [,[,...]]` *default: ``*: The module(s) from which + the graph is expanded in `graph`, `all_paths`, `path`, and `explain`. Check + the subcommands' descriptions for more details. + +* `--verbose` *default: "false"*: Include in the output graph extra + information about the version resolution of each module. If the module + version changed during resolution, show either which version replaced it or + what was the original version, the reason it was replaced, and which modules + requested the new version if the reason was [Minimal Version + Selection](/external/module#version-selection). + +* `--include_unused` *default: "false"*: Include in the output graph the + modules which were originally present in the dependency graph, but became + unused after module resolution. + +* `--extension_info `: Include information about the module extension + usages as part of the output graph (see [example](#mod-example7)). `` + can be one of: + + * `hidden` *(default)*: Don't show anything about extensions. + + * `usages`: Show extensions under each module where they are used. They + are printed in the form of `$`. + + * `repos`: In addition to `usages`, show the repo imported using + `use_repo` under each extension usage. + + * `all`: In addition to `usages` and `repos`, also show + extension-generated repos that are not imported by any module. These + extra repos are shown under the first occurrence of their generating + extension in the output, and are connected with a dotted edge. + +* `--extension_filter [,[,...]]`: If specified, the + output graph only includes modules that use the specified extensions, and + the paths that lead to those modules. Specifying an empty extension list (as + in `--extension_filter=`) is equivalent to specifying _all_ extensions used + by any module in the dependency graph. + +* `--depth `: The depth of the output graph. A depth of 1 only displays the + root and its direct dependencies. Defaults to 1 for `explain`, 2 for `deps` + and infinity for the others. + +* `--cycles` *default: "false"*: Include cycle edges in the output graph. + +* `--include_builtin` *default: "false"*: Include built-in modules (such as + `@bazel_tools`) in the output graph. This flag is disabled by default, as + built-in modules are implicitly depended on by every other module, which + greatly clutters the output. + +* `--charset ` *default: utf8*: Specify the charset to use for text + output. Valid values are `"utf8"` and `"ascii"`. The only significant + difference is in the special characters used to draw the graph in the + `"text"` output format, which don't exist in the `"ascii"` charset. + Therefore, the `"ascii"` charset is present to also support the usage on + legacy platforms which cannot use Unicode. + +* `--output `: Include information about the module extension usages as + part of the output graph. ` can be one of: + + * `text` *(default)*: A human-readable representation of the output graph + (flattened as a tree). + + * `json`: Outputs the graph in the form of a JSON object (flattened as a + tree). + + * `graph`: Outputs the graph in the Graphviz *dot* representation. + + + Use the following command to pipe the output through the *dot* engine + and export the graph representation as an SVG image. + + ```sh + bazel mod graph --output graph | dot -Tsvg > /tmp/graph.svg + ``` + + +The available options are listed in the following section. See also the +[Command-Line Reference](/reference/command-line-reference#mod) for a +comprehensive list of options for all bazel commands. + +Other options include: + +* `--base_module ` *default: ``*: Specify a module relative to + which apparent repo names in arguments are interpreted. Note that this + argument itself can be in the form of `@`; this is always + interpreted relative to the root module. + +* `--extension_usages [,[,...]]`: Filters `show_extension` to only + display extension usages from the specified modules. + +## Examples + +Some possible usages of the `mod` command on a real Bazel project are showcased +below to give you a general idea on how you can use it to inspect your project's +external dependencies. + +`MODULE.bazel` file: + +```python +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") +``` + + + + Graph Before Resolution + + + + Graph After Resolution + + + +
+### Example 1: Display the whole dependency graph + +Display the whole dependency graph of your project. + +```sh +bazel mod graph +``` + +```none + (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 ... +``` + + +The `...` symbol indicates that the node has already been expanded +somewhere else and was not expanded again to reduce noise. + +
+ +
+### Example 2: Display graph with unused modules + +Display the whole dependency graph (including unused modules and with extra information about version resolution). + +```sh +bazel mod graph --include_unused --verbose +``` + +```none + (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 , 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 , 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) +``` +
+ +
+### Example 3: Display graph from specific modules + +Display the dependency graph expanded from some specific modules. + +```sh +bazel mod graph --from rules_java --include_unused +``` + +```none + (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 ... +``` + + +The dotted line is used to indicate an *indirect* (transitive) +dependency edge between two nodes. + +
+ +
+### Example 4: Display all paths between modules + +Display all paths between two of your modules. + +```sh +bazel mod all_paths bazel_skylib@1.1.1 --from rules_proto +``` + +```none + (my_project@1.0) +└╌╌rules_proto@4.0.0 + ├───bazel_skylib@1.1.1 + └───rules_cc@0.0.1 + └───bazel_skylib@1.1.1 ... +``` +
+ +
+### Example 5: Explain module dependencies + +See why and how your project depends on some module(s). + +```sh +bazel mod explain @skylib1 --verbose --include_unused +``` + +```none + (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 ... +``` +
+ +
+### Example 6: Show repo definitions + +See the underlying rule of some your modules' repos. + +```sh +bazel mod show_repo rules_cc stardoc +``` + +```none +## rules_cc@0.0.1: +# +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 + +## stardoc: +# +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 +``` +
+ +
+### Example 7: Show module extensions + +See what module extensions are used in your dependency graph. + +```sh +bazel mod graph --extension_info=usages --extension_filter=all +``` + +```none + (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 ... +``` +
+ +
+### Example 8: Show extension repos + +See what repositories are generated and imported from some specific extension as part of the dependency graph. + +```sh +bazel mod show_extension @@rules_java+5.0.0//java:extensions.bzl%toolchains +``` + +```none + (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 ... +``` +
+ +### Example 9: Show extension usage details + +See the list of generated repositories of an extension and how that extension is used in each module. + +```sh +bazel mod graph --extension_info=all --extension_filter=@rules_java//java:extensions.bzl%toolchains +``` + +```none +## @@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 ) + - remotejdk11_linux + - remotejdk11_linux_aarch64 + - remotejdk11_linux_ppc64le + - remotejdk11_linux_s390x + - remotejdk11_macos +...(some lines omitted)... + +# Usage in at /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)... +) +``` + +### Example 10: Show repo from another module's perspective + +See the underlying rule of some extension-generated repositories. + +```sh +bazel mod show_repo --base_module=rules_java @remote_java_tools +``` + +```none +## @remote_java_tools: +# +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 +```