O comando mod
, introduzido no Bazel 6.3.0, fornece uma variedade de ferramentas para ajudar
o usuário a entender o gráfico de dependência externa quando o Bzlmod está ativado. Ele
permite visualizar o gráfico de dependências, descobrir por que um determinado módulo ou
versão de um módulo está presente no gráfico, visualizar os módulos de apoio
de definições de repo, inspecionar usos de extensões de módulo e repositórios gerados, entre
outras funções.
Sintaxe
bazel mod <subcommand> [<options>] [<arg> [<arg>...]]
Os subcomandos disponíveis e seus respectivos argumentos obrigatórios são:
graph
: mostra o gráfico de dependências completo do projeto, começando pelo módulo raiz. Se um ou mais módulos forem especificados em--from
, eles serão mostrados diretamente abaixo da raiz, e o gráfico só será expandido a partir deles (consulte o exemplo).deps <arg>...
: mostra as dependências diretas resolvidas de cada um dos módulos especificados, de forma semelhante agraph
.all_paths <arg>...
: mostra todos os caminhos existentes da raiz até o<arg>...
especificado. Se um ou mais módulos forem especificados em--from
, eles serão mostrados diretamente abaixo da raiz, e o gráfico vai conter qualquer caminho existente dos módulos--from
para os módulos de argumentos (consulte o exemplo).path <arg>...
: tem a mesma semântica deall_paths
, mas exibe apenas um único caminho de um dos módulos--from
para um dos módulos de argumentos.explain <arg>...
: mostra todos os locais em que os módulos especificados aparecem no gráfico de dependência, junto com os módulos que dependem diretamente deles. A saída do comandoexplain
é essencialmente uma versão reduzida do comandoall_paths
, contendo 1) o módulo raiz; 2) as dependências diretas do módulo raiz que levam aos módulos de argumentos; 3) os dependentes diretos dos módulos de argumentos; e 4) os próprios módulos de argumento (consulte o exemplo).show_repo <arg>...
: mostra a definição dos repositórios especificados (consulte o exemplo).show_extension <extension>...
: mostra informações sobre cada uma das extensões especificadas: uma lista dos repositórios gerados com os módulos que as importam usandouse_repo
e uma lista dos usos dessa extensão em cada um dos módulos em que ela é usada, contendo as tags especificadas e as chamadasuse_repo
(veja o exemplo).
<arg>
refere-se a um ou mais módulos ou repositórios. Pode ser:
A string literal
<root>
: o módulo raiz que representa seu projeto atual.<name>@<version>
: o módulo<name>
na versão<version>
. Em um módulo com uma substituição que não seja do registro, use um sublinhado (_
) como<version>
.<name>
: todas as versões atuais do módulo<name>
.@<repo_name>
: o repositório com o nome aparente fornecido no contexto do--base_module
.@@<repo_name>
: o repositório com o nome canônico fornecido.
Em um contexto que exige a especificação de módulos, também é possível usar <arg>
s que se referem a repositórios
correspondentes a módulos (em oposição a repositórios gerados por extensões). Por outro lado, em um contexto que requer a especificação de repositórios, <arg>
s que se referem aos
módulos podem substituir os repositórios correspondentes.
<extension>
precisa estar no formato <arg><label_to_bzl_file>%<extension_name>
.
A parte <label_to_bzl_file>
precisa ser um rótulo relativo ao repositório (por exemplo,
//pkg/path:file.bzl
).
As opções a seguir afetam apenas os subcomandos que mostram gráficos (graph
, deps
, all_paths
, path
e explain
):
--from <arg>[,<arg>[,...]]
padrão:<root>
: os módulos de onde o gráfico é expandido emgraph
,all_paths
,path
eexplain
. Confira as descrições dos subcomandos para mais detalhes.--verbose
default: "false": inclui no gráfico de saída mais informações sobre a resolução da versão de cada módulo. Se a versão do módulo mudou durante a resolução, mostre qual versão a substituiu ou qual era a original, por que ela foi substituída e quais módulos solicitaram a nova versão, se o motivo foi Seleção de versão mínima.--include_unused
default: "false": inclui no gráfico de saída os módulos que estavam originalmente presentes no gráfico de dependências, mas que se tornaram usados após a resolução do módulo.--extension_info <mode>
: inclui informações sobre os usos da extensão do módulo como parte do gráfico de saída. Confira o exemplo. O<mode>
pode ser um dos seguintes:hidden
(padrão): não mostra nada sobre extensões.usages
: mostra as extensões em cada módulo em que elas são usadas. Eles são mostrados na forma de$<extension>
.repos
: além deusages
, mostre o repositório importado usandouse_repo
em cada uso da extensão.all
: além deusages
erepos
, também mostra repositórios gerados por extensão que não são importados por nenhum módulo. Esses repositórios extras são mostrados na primeira ocorrência da extensão gerada na saída e estão conectados com uma borda pontilhada.
--extension_filter <extension>[,<extension>[,...]]
: se especificado, o gráfico de saída inclui apenas módulos que usam as extensões especificadas e os caminhos que levam a esses módulos. Especificar uma lista de extensões vazia (como em--extension_filter=
) equivale a especificar todas as extensões usadas por qualquer módulo no gráfico de dependência.--depth <N>
: a profundidade do gráfico de saída. Uma profundidade de 1 exibe apenas a raiz e as dependências diretas dela. O padrão é 1 paraexplain
, 2 paradeps
e infinito para os outros.--cycles
default: "false": inclui as bordas do ciclo no gráfico de saída.--include_builtin
default: "false": inclui módulos integrados (como@bazel_tools
) no gráfico de saída. Essa flag é desativada por padrão, já que os módulos integrados dependem implicitamente dos outros, o que polui muito a saída.--charset <charset>
default: utf8: especifica o conjunto de caracteres a ser usado para a saída de texto. Os valores válidos são"utf8"
e"ascii"
. A única diferença significativa são os caracteres especiais usados para desenhar o gráfico no formato de saída"text"
, que não existem no conjunto de caracteres"ascii"
. Portanto, o conjunto de caracteres"ascii"
está presente para oferecer suporte ao uso em plataformas legadas que não podem utilizar Unicode.--output <mode>
: inclui informações sobre os usos da extensão do módulo como parte do gráfico de saída.<mode
> pode ser:text
(padrão): uma representação legível por humanos do gráfico de saída (nivelado como uma árvore).json
: gera o gráfico na forma de um objeto JSON (nivelado como uma árvore).graph
: gera o gráfico na representação de ponto do Graphviz.
bazel mod graph --output graph | dot -Tsvg > /tmp/graph.svg
Outras opções incluem:
--base_module <arg>
padrão:<root>
: especifica um módulo em relação ao qual os nomes de repositórios aparentes nos argumentos são interpretados. Observe que esse argumento em si pode estar na forma de@<repo_name>
, que sempre é interpretado em relação ao módulo raiz.--extension_usages <arg>[,<arg>[,...]]
: filtrashow_extension
para mostrar apenas os usos de extensões dos módulos especificados.
Exemplos
Alguns usos possíveis do comando mod
em um projeto real do Bazel são mostrados
abaixo para dar uma ideia geral de como ele pode ser usado para inspecionar as
dependências externas do projeto.
Arquivo 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")
|
|
Mostre todo o gráfico de dependências do projeto.
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 ...
Mostre todo o gráfico de dependência, incluindo módulos não utilizados e com informações extras sobre a resolução da versão.
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)
Exiba o gráfico de dependências expandido em alguns 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 ...
Exiba todos os caminhos entre dois dos seus 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 ...
Confira por que e como seu projeto depende de alguns 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 ...
Ver a regra subjacente de alguns repositórios de 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>
Confira quais extensões de módulo são usadas no gráfico de dependência.
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 ...
Veja quais repositórios são gerados e importados de alguma extensão específica como parte do gráfico de dependência.
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 ...
Consulte a lista de repositórios gerados de uma extensão e como ela é usada em 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)... )
Consulte a regra subjacente de alguns repositórios gerados por extensão.
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>