As inscrições para a BazelCon 2024 já estão abertas.

Esta página foi traduzida pela API Cloud Translation.

Comando mod

Informar um problema Ver código-fonte Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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ências, 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órios que são os módulos, inspecionar os 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ê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 a graph.
all_paths <arg>...: mostra todos os caminhos existentes da raiz até o <arg>... especificado. Se um ou mais módulos forem especificados em --from, esses módulos serão mostrados diretamente na raiz, e o gráfico conterá qualquer caminho existente dos módulos --from para os módulos de argumento (consulte o exemplo).
path <arg>...: tem a mesma semântica que all_paths, mas exibe apenas um caminho de um dos módulos --from para 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 deles. A saída do comando explain é basicamente uma versão simplificada do comando all_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 e dos módulos que as importam usando use_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 chamadas use_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 sem registro, 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 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ões) 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 de que o gráfico é expandido em graph, all_paths, path e explain. Confira as descrições dos subcomandos para mais detalhes.
--verbose Padrão: "false": inclui no gráfico de saída informações adicionais sobre a resolução da versão de cada módulo. Se a versão do módulo mudar 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 pediram a nova versão se o motivo foi Seleção de versão mínima.
--include_unused padrão: "false": inclui no gráfico de saída os módulos que estavam originalmente presentes no gráfico de dependência, mas que foram desativados após a resolução do módulo.
--extension_info <mode>: incluir 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:
- 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. Elas são impressas no formato $<extension>.
- repos: além de usages, mostre o repositório importado usando use_repo em cada uso de extensão.
- all: além de usages e repos, também mostra repositórios gerados por extensões que não são importados por nenhum módulo. Esses repos extras são mostrados na primeira ocorrência da extensão de geração 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ências.
--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 para explain, 2 para deps e infinito para os outros.
--cycles padrão: "false": inclui arestas de ciclo no gráfico de saída.
--include_builtin padrão: "false": inclui módulos integrados (como @bazel_tools) no gráfico de saída. Essa flag fica desativada por padrão, já que os módulos integrados são implicitamente dependentes de todos os outros módulos, o que confunde bastante a saída.
--charset <charset> padrão: utf8: especifique 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 é nos 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 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 por humanos do gráfico de saída (achatada 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.
Dica: use o comando a seguir para canalizar a saída pelo mecanismo dot e exportar a representação do gráfico como uma imagem SVG.
```
bazel mod graph --output graph | dot -Tsvg > /tmp/graph.svg
```

Outras opções incluem:

--base_module <arg> padrão: <root>: especifique um módulo relativo a quais nomes de repositório aparentes nos argumentos são interpretados. Esse argumento pode estar na forma de @<repo_name>. Ele é sempre interpretado em relação ao módulo raiz.
--extension_usages <arg>[,<arg>[,...]]: filtra show_extension para mostrar apenas os usos de extensão dos módulos especificados.

Exemplos

Algumas possíveis utilizações do comando mod em um projeto real do Bazel são mostradas 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")

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

Mostra o gráfico de dependências completo (incluindo módulos não usados e com informações extras sobre a resolução de versões).

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)

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

Conferir a regra subjacente de alguns repositórios dos seus 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ências.

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

Confira quais repositórios são gerados e importados de uma extensão específica como parte do gráfico de dependências.

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

Confira 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ões.

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>