O comando mod, introduzido no Bazel 6.3.0, oferece 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ência, descobrir por que um determinado módulo ou uma
versão de um módulo está presente no gráfico, conferir as definições de repositório de módulos de apoio, inspecionar usos de extensões de módulo e repositórios que eles geram, entre
outras funções.
Sintaxe
bazel mod <subcommand> [<options>] [<arg> [<arg>...]]
Os subcomandos disponíveis e os respectivos argumentos obrigatórios são:
graph: mostra o gráfico de dependência completo do projeto, começando por o módulo raiz. Se um ou mais módulos forem especificados em--from, estes módulos serão mostrados diretamente na raiz, e o gráfico será expandido apenas a partir deles (consulte o exemplo).deps <arg>...: mostra as dependências diretas resolvidas de cada um dos módulos especificados, de maneira semelhante agraph.all_paths <arg>...: mostra todos os caminhos existentes da raiz para o especificado<arg>.... Se um ou mais módulos forem especificados em--from, eles serão mostrados diretamente na raiz, e o gráfico vai conter qualquer caminho existente dos módulos--frompara os módulos de argumento (consulte o exemplo).path <arg>...: tem a mesma semântica queall_paths, mas mostra apenas um único caminho de um dos módulos--frompara um dos módulos de argumento.explain <arg>...: mostra todos os lugares em que os módulos especificados aparecem no gráfico de dependência, junto com os módulos que dependem diretamente de eles. 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 argumento; 3) os dependentes diretos dos módulos de argumento; 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, juntamente com os módulos que os 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(consulte o exemplo).
<arg> se refere a um ou mais módulos ou repositórios. Pode ser um destes:
A string literal
<root>: o módulo raiz que representa seu projeto atual.<name>@<version>: o módulo<name>na versão<version>. Para um módulo com uma substituição não registrada, use um sublinhado (_) como o<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, <arg>s que se referem a repositórios que
correspondem a módulos (em vez de repositórios gerados por extensão) também podem ser
usados. Por outro lado, em um contexto que exige a especificação de repositórios, <arg>s que se referem a
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 imprimem gráficos (graph,
deps, all_paths, path, e explain):
--from <arg>[,<arg>[,...]]padrão:<root>: os módulos em que o gráfico é expandido emgraph,all_paths,path, eexplain. Confira as descrições dos subcomandos para mais detalhes.--verbosepadrão: "false": inclui no gráfico de saída informações extras sobre a resolução de versão de cada módulo. Se a versão do módulo tiver sido alterada durante a resolução, mostre qual versão a substituiu ou qual era a versão original, o motivo da substituição e quais módulos solicitaram a nova versão se o motivo foi a seleção de versão mínima.--include_unusedpadrão: "false": inclui no gráfico de saída os módulos que estavam originalmente presentes no gráfico de dependência, mas ficaram sem uso 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 (consulte o exemplo).<mode>pode ser um destes:hidden(padrão): não mostra nada sobre extensões.usages: mostra extensões em cada módulo em que são usadas. Elas são impressas no formato$<extension>.repos: além deusages, mostra o repositório importado usandouse_repoem cada uso de extensão.all: além deusageserepos, 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 geradora na saída e sã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=) é equivalente 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 mostra apenas a raiz e as dependências diretas. O padrão é 1 paraexplain, 2 paradepse infinito para os outros.--cyclespadrão: "false": inclui bordas de ciclo no gráfico de saída.--include_builtinpadrão: "false": inclui módulos integrados (como@bazel_tools) no gráfico de saída. Essa flag está desativada por padrão, porque os módulos integrados dependem implicitamente de todos os outros módulos, o que dificulta muito a saída.--charset <charset>padrão: utf8: especifica o conjunto de caracteres a ser usado para saída de texto. Os valores válidos são"utf8"e"ascii". A única diferença significativa está nos caracteres especiais usados para desenhar o gráfico no"text"formato de saída, que não existem no"ascii"conjunto de caracteres. Portanto, o conjunto de caracteres"ascii"também está presente para oferecer suporte ao uso em plataformas legadas que não podem usar 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 um destes:text(padrão): uma representação legível do gráfico de saída (achatado como uma árvore).json: gera o gráfico na forma de um objeto JSON (achatado como uma árvore).graph: gera o gráfico na representação dot 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ório aparentes nos argumentos são interpretados. Esse argumento pode estar no formato@<repo_name>; ele sempre é interpretado em relação ao módulo raiz.--extension_usages <arg>[,<arg>[,...]]: filtrashow_extensionpara mostrar apenas os usos de extensão 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 usá-lo para inspecionar as dependências externas do seu 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")
|
|
Mostra todo o gráfico de dependência do seu 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 ...Mostra todo o gráfico de dependência (incluindo módulos não usados e com informações extras sobre a resolução de 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)Mostra o gráfico de dependência expandido de 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 ...Mostra 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 ...Mostra 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 ...Mostra 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>Mostra quais extensões de módulo são usadas no seu 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 ...Mostra 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 ...Mostra a lista de repositórios gerados de uma extensão e como essa extensão é 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)... )Mostra 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>