El comando mod
, que se introdujo en Bazel 6.3.0, proporciona una variedad de herramientas para ayudar al usuario a comprender su gráfico de dependencia externa cuando Bzlmod está habilitado. Te permite visualizar el gráfico de dependencia, descubrir por qué un módulo determinado o una versión de un módulo está presente en el gráfico, ver las definiciones de repositorio de los módulos de respaldo, inspeccionar los usos de las extensiones del módulo y los repositorios que generan, entre otras funciones.
Sintaxis
bazel mod <subcommand> [<options>] [<arg> [<arg>...]]
Los subcomandos disponibles y sus respectivos argumentos obligatorios son los siguientes:
graph
: Muestra el gráfico de dependencia completo del proyecto, a partir del módulo raíz. Si se especifican uno o más módulos en el archivo--from
, se mostrarán directamente debajo de la raíz y el gráfico solo se expandirá a partir de ellos (consulta el ejemplo).deps <arg>...
: Muestra las dependencias directas resueltas de cada uno de los módulos especificados, de manera similar agraph
.all_paths <arg>...
: Muestra todas las rutas existentes desde la raíz hasta el<arg>...
especificado. Si se especifican uno o más módulos en--from
, se mostrarán directamente debajo de la raíz, y el gráfico contendrá cualquier ruta existente desde los módulos--from
hasta los módulos de argumento (consulta el ejemplo).path <arg>...
: Tiene la misma semántica queall_paths
, pero solo muestra una única ruta de acceso de uno de los módulos--from
a uno de los módulos de argumento.explain <arg>...
: Muestra todos los lugares en los que aparecen los módulos especificados en el gráfico de dependencia, junto con los módulos que dependen directamente de ellos. El resultado del comandoexplain
es, en esencia, una versión reducida del comandoall_paths
, que contiene 1) el módulo raíz, 2) las dependencias directas del módulo raíz que conducen a los módulos de argumento, 3) las dependencias directas de los módulos de argumento y 4) los módulos de argumento en sí (consulta el ejemplo).show_repo <arg>...
: Muestra la definición de los repositorios especificados (consulta el ejemplo).show_extension <extension>...
: Muestra información sobre cada una de las extensiones especificadas: una lista de los repositorios generados junto con los módulos que los importan conuse_repo
y una lista de los usos de esa extensión en cada uno de los módulos donde se usa, que contiene las etiquetas especificadas y las llamadas ause_repo
(consulta el ejemplo).
<arg>
hace referencia a uno o más módulos o repositorios. Puede ser uno de los siguientes:
La string literal
<root>
: Es el módulo raíz que representa tu proyecto actual.<name>@<version>
: Es el módulo<name>
de la versión<version>
. Para un módulo con una anulación que no sea de registro, usa un guion bajo (_
) como<version>
.<name>
: Todas las versiones actuales del módulo<name>
@<repo_name>
: Es el repositorio con el nombre aparente determinado en el contexto de--base_module
.@@<repo_name>
: El repositorio con el nombre canónico determinado
En un contexto que requiere especificar módulos, también se pueden usar <arg>
que hacen referencia a repositorios que
corresponden a módulos (en lugar de repositorios generados por extensiones). Por el contrario, en un contexto que requiere especificar repositorios, los <arg>
que se refieren a los módulos pueden representar los repositorios correspondientes.
<extension>
debe tener el formato <arg><label_to_bzl_file>%<extension_name>
.
La parte <label_to_bzl_file>
debe ser una etiqueta relativa al repositorio (por ejemplo, //pkg/path:file.bzl
).
Las siguientes opciones solo afectan a los subcomandos que imprimen gráficos (graph
, deps
, all_paths
, path
y explain
):
--from <arg>[,<arg>[,...]]
default:<root>
: Son los módulos desde los que se expande el gráfico engraph
,all_paths
,path
yexplain
. Consulta las descripciones de los subcomandos para obtener más detalles.--verbose
default: "false": Incluye en el gráfico de resultados información adicional sobre la resolución de la versión de cada módulo. Si la versión del módulo cambió durante la resolución, muestra qué versión la reemplazó o cuál era la versión original, el motivo por el que se reemplazó y qué módulos solicitaron la nueva versión si el motivo fue la selección de versión mínima.--include_unused
default: "false": Incluye en el gráfico de salida los módulos que estaban presentes originalmente en el gráfico de dependencia, pero que se usaron después de la resolución del módulo.--extension_info <mode>
: Incluye información sobre los usos de la extensión del módulo como parte del gráfico de resultados (consulta el ejemplo).<mode>
puede ser uno de los siguientes:hidden
(predeterminado): No muestra nada sobre las extensiones.usages
: Muestra las extensiones debajo de cada módulo donde se usan. Se imprimen como$<extension>
.repos
: Además deusages
, muestra el repositorio importado conuse_repo
en cada uso de extensión.all
: Además deusages
yrepos
, también muestra repositorios generados por extensiones que ningún módulo importa. Estos repositorios adicionales se muestran en el primer caso de su extensión de generación en el resultado y están conectados con un borde punteado.
--extension_filter <extension>[,<extension>[,...]]
: Si se especifica, el gráfico de salida solo incluye módulos que usan las extensiones especificadas y las rutas que conducen a esos módulos. Especificar una lista de extensiones vacía (como en--extension_filter=
) equivale a especificar todas las extensiones que usa cualquier módulo del gráfico de dependencia.--depth <N>
: Es la profundidad del gráfico de resultados. Una profundidad de 1 solo muestra la raíz y sus dependencias directas. La configuración predeterminada es 1 paraexplain
, 2 paradeps
e infinito para las demás.--cycles
default: "false": Incluye aristas de ciclo en el gráfico de resultados.--include_builtin
default: "false": Incluye módulos integrados (como@bazel_tools
) en el gráfico de resultados. Esta marca está inhabilitada de forma predeterminada, ya que cada otro módulo depende de manera implícita de los módulos integrados, lo que desordena enormemente el resultado.--charset <charset>
default: utf8: Especifica el charset que se usará para la salida de texto. Los valores válidos son"utf8"
y"ascii"
. La única diferencia significativa son los caracteres especiales que se usan para dibujar el gráfico en el formato de salida"text"
, que no existen en el conjunto de caracteres"ascii"
. Por lo tanto, el charset"ascii"
también está presente para admitir el uso en plataformas heredadas que no pueden usar Unicode.--output <mode>
: Incluye información sobre los usos de extensión del módulo como parte del gráfico de resultados.<mode
> puede ser uno de los siguientes:text
(predeterminado): Es una representación legible por humanos del gráfico de resultados (aplanado como un árbol).json
: Muestra el grafo en forma de objeto JSON (acoplado como un árbol).graph
: Muestra el grafo en la representación punto de Graphviz.
bazel mod graph --output graph | dot -Tsvg > /tmp/graph.svg
Estas son otras opciones:
--base_module <arg>
default:<root>
: Especifica un módulo según el cual se interpretan los nombres aparentes de repositorio en los argumentos. Ten en cuenta que este argumento puede tener el formato@<repo_name>
. Esto siempre se interpreta en relación con el módulo raíz.--extension_usages <arg>[,<arg>[,...]]
: Filtrashow_extension
para que solo muestre los usos de extensiones de los módulos especificados.
Ejemplos
A continuación, se muestran algunos usos posibles del comando mod
en un proyecto real de Bazel
a fin de darte una idea general de cómo puedes usarlo para inspeccionar las dependencias externas
de tu proyecto.
Archivo 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")
Muestra el gráfico de dependencia completo de tu proyecto.
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 ...
Muestra todo el gráfico de dependencia (incluidos los módulos sin usar y con información adicional sobre la resolución de la versión).
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)
Muestra el gráfico de dependencia expandido de algunos módulos específicos.
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 ...
Muestra todas las rutas de acceso entre dos de tus módulos.
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 ...
Descubrir por qué y cómo tu proyecto depende de algunos módulos
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 ...
Consulta la regla subyacente de los repositorios de algunos de tus módulos.
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>
Consulta qué extensiones del módulo se usan en tu gráfico de dependencia.
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 ...
Observa qué repositorios se generan y se importan desde alguna extensión específica como parte del gráfico de dependencia.
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 ...
Consulta la lista de repositorios generados de una extensión y cómo se usa en cada módulo.
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)... )
Consulta la regla subyacente de algunos repositorios generados por extensiones.
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>