Comando mod

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

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 dependencias externas cuando Bzlmod está habilitado. Te permite visualizar el gráfico de dependencias, averiguar por qué un módulo determinado o una versión de un módulo está presente en el gráfico, ver las definiciones de repositorios que respaldan los módulos, inspeccionar los usos de las extensiones de módulos 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 dependencias completo del proyecto, comenzando desde el módulo raíz. Si se especifican uno o más módulos en --from, estos módulos se muestran directamente debajo de la raíz, y el gráfico solo se expande 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 a graph.
all_paths <arg>...: Muestra todas las rutas de dependencias desde los módulos --from hasta los módulos de destino. Para simplificar el resultado, solo se muestra la primera ruta más corta cuando varias rutas comparten el mismo sufijo. Por ejemplo, se mostraría A -> B -> X, pero se omitiría la ruta más larga A -> C -> B -> X. En otras palabras, para cada módulo Y que depende directamente del módulo de destino X, el resultado contiene solo la ruta más corta que pasa por Y para llegar a X.
path <arg>...: Tiene la misma semántica que all_paths, pero solo muestra una ruta de acceso desde uno de los módulos --from a uno de los módulos de argumentos.
explain <arg>...: Muestra todos los lugares en los que aparecen los módulos especificados en el gráfico de dependencias, junto con los módulos que dependen directamente de ellos. El resultado del comando explain es, esencialmente, una versión podada de el comando all_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 argumentos, 3) los dependientes directos de los módulos de argumentos y 4) los módulos de argumentos en sí (consulta el ejemplo).
show_repo <arg>...: Muestra la definición de los repositorios especificados (consulta el ejemplo). Usa --all_repos para mostrar las definiciones de todos los repositorios en todo el gráfico de dependencias o --all_visible_repos para mostrar las definiciones de todos los repositorios visibles desde --base_module.
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 con use_repo y una lista de los usos de esa extensión en cada uno de los módulos en los que se usa, que contiene las etiquetas especificadas y las llamadas use_repo (consulta el ejemplo).

<arg> hace referencia a uno o más módulos o repositorios. Puede ser uno de los siguientes:

La cadena literal <root>: El módulo raíz que representa tu proyecto actual.
<name>@<version>: El módulo <name> en la versión <version>. Para un módulo con una anulación que no sea de registro, usa un guion bajo (_) como el <version>.
<name>: Todas las versiones presentes del módulo <name>.
@<repo_name>: 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, <arg>s que hacen referencia a repositorios que corresponden a módulos (en lugar de repositorios generados por extensiones) también se pueden usar. Por el contrario, en un contexto que requiere especificar repositorios, los <arg>s que hacen referencia a módulos pueden sustituir a 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).

Opciones del comando graph

Las siguientes opciones solo afectan a los subcomandos que imprimen gráficos (graph, deps, all_paths, path, y explain):

--from <arg>[,<arg>[,...]] default: <root>: Los módulos desde los que se expande el gráfico en graph, all_paths, path, y explain. Consulta las descripciones de los subcomandos para obtener más detalles.
--verbose default: "false": Incluye en el gráfico de salida información adicional sobre la resolución de versiones 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 versión nueva 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 dependencias, pero que dejaron de usarse 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 salida (consulta el ejemplo). <mode> puede ser uno de los siguientes:
- hidden (predeterminado): No muestra nada sobre las extensiones.
- usages: Muestra las extensiones en cada módulo en el que se usan. Se imprimen en forma de $<extension>.
- repos: Además de usages, muestra el repositorio importado con use_repo en cada uso de extensión.
- all: Además de usages y repos, también muestra los repositorios generados por extensiones que no importa ningún módulo. Estos repositorios adicionales se muestran en la primera aparición de su extensión generadora en el resultado y se conectan con un borde punteado.
--extension_filter <extension>[,<extension>[,...]]: Si se especifica, el gráfico de salida solo incluye los 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 en el gráfico de dependencias.
--depth <N>: La profundidad del gráfico de salida. Una profundidad de 1 solo muestra la raíz y sus dependencias directas. El valor predeterminado es 1 para explain, 2 para deps y el infinito para los demás.
--cycles default: "false": Incluye bordes de ciclo en el gráfico de salida.
--include_builtin default: "false": Incluye módulos integrados (como @bazel_tools) en el gráfico de salida. Esta marca está inhabilitada de forma predeterminada, ya que todos los demás módulos dependen implícitamente de los módulos integrados, lo que desordena mucho el resultado.
--charset <charset> default: utf8: Especifica el conjunto de caracteres que se usará para la salida de texto Los valores válidos son "utf8" y "ascii". La única diferencia significativa está en los caracteres especiales que se usan para dibujar el gráfico en el "text" formato de salida, que no existen en el "ascii" conjunto de caracteres. Por lo tanto, el conjunto de caracteres "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 la extensión del módulo como parte del gráfico de salida. <mode> puede ser uno de los siguientes:
- text (predeterminado): Una representación legible del gráfico de salida (aplanado como un árbol).
- json: Genera el gráfico en forma de objeto JSON (aplanado como un árbol).
- graph: Genera el gráfico en la representación dot de Graphviz.
Sugerencia: Usa el siguiente comando para canalizar el resultado a través del motor dot y exportar la representación del gráfico como una imagen SVG.
```
bazel mod graph --output graph | dot -Tsvg > /tmp/graph.svg
```

Opciones de show_repo

show_repo admite un conjunto diferente de formatos de salida:

--output <mode>: Cambia la forma en que se muestran las definiciones de repositorios. <mode> puede ser uno de los siguientes:
- text (default): Muestra las definiciones de repositorios en Starlark.
- streamed_proto: Imprime una transmisión delimitada por longitud de búferes de Repository protocolo.
- streamed_jsonproto: Similar a --output streamed_proto, imprime una transmisión de Repository búferes de protocolo, pero en formato NDJSON.

Otras opciones

Estas son otras opciones:

--base_module <arg> default: <root>: Especifica un módulo en relación con el cual se interpretan los nombres de repositorios aparentes en los argumentos. Ten en cuenta que este argumento puede tener el formato @<repo_name>; siempre se interpreta en relación con el módulo raíz.
--extension_usages <arg>[,<arg>[,...]]: Filtra show_extension para mostrar solo 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 para 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 todo el gráfico de dependencias 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 dependencias (incluidos los módulos sin usar y con información adicional sobre la resolución de versiones).

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 dependencias expandido desde 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 ...

Consulta por qué y cómo depende tu proyecto 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 tus módulos.

bazel mod show_repo rules_cc stardoc

## rules_cc@0.0.1:
load("@@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
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,
)

## stardoc:
load("@@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
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,
)

bazel mod show_repo también funciona con repositorios importados por use_repo y repositorios creados con use_repo_rule. Si se invoca show_repo con un nombre de repositorio aparente o --all_visible_repos, el nombre de repositorio aparente se muestra en una línea con el prefijo ##.

bazel mod show_repo @jq_linux_arm64
bazel mod show_repo --all_visible_repos

## @jq_linux_arm64:
load("@@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
http_file(
    name = "+http_file+jq_linux_arm64",
    executable = True,
    integrity = "sha256-TdLYoGYd8LIvG7mh+YMPBrbzuPfZEhGh7118TwaotKU=",
    urls = ["https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-linux-arm64"],
)

Consulta qué extensiones de módulos se usan en tu gráfico de dependencias.

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

Consulta qué repositorios se generan y se importan desde alguna extensión específica como parte del gráfico de dependencias.

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 esa extensión 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>