Guia de início rápido de consultas

Este tutorial aborda como trabalhar com o Bazel para rastrear dependências no código usando um projeto do Bazel pré-criado.

Para detalhes sobre a linguagem e a flag --output, consulte os manuais de referência de consulta do Bazel e de cquery do Bazel. Para receber ajuda no ambiente de desenvolvimento integrado, digite bazel help query ou bazel help cquery na linha de comando.

Objetivo

Este guia mostra um conjunto de consultas básicas que podem ser usadas para saber mais sobre as dependências de arquivos do projeto. Ele é destinado a novos desenvolvedores do Bazel com conhecimento básico de como o Bazel e os arquivos BUILD funcionam.

Pré-requisitos

Comece instalando o Bazel, se ainda não tiver feito isso. Este tutorial usa o Git para controle de origem. Para melhores resultados, instale Git também.

Para visualizar gráficos de dependência, a ferramenta Graphviz é usada. Faça o download dela para acompanhar.

Acessar o projeto de amostra

Em seguida, recupere o app de amostra do repositório de exemplos do Bazel executando o seguinte na ferramenta de linha de comando de sua preferência:

git clone https://github.com/bazelbuild/examples.git

O projeto de amostra deste tutorial está no examples/query-quickstart diretório.

Primeiros passos

O que são consultas do Bazel?

As consultas ajudam a aprender sobre uma base de código do Bazel analisando as relações entre arquivos BUILD e examinando a saída resultante para informações úteis. Este guia mostra algumas funções de consulta básicas, mas para mais opções, consulte o guia de consulta. As consultas ajudam a aprender sobre dependências em projetos de grande escala sem navegar manualmente pelos arquivos BUILD.

Para executar uma consulta, abra o terminal de linha de comando e insira:

bazel query 'query_function'

Cenário

Imagine um cenário que se aprofunda na relação entre o Cafe Bazel e o chef. Esse café vende exclusivamente pizza e macarrão com queijo. Confira abaixo como o projeto está estruturado:

bazelqueryguide
├── BUILD
├── src
│   └── main
│       └── java
│           └── com
│               └── example
│                   ├── customers
│                   │   ├── Jenny.java
│                   │   ├── Amir.java
│                   │   └── BUILD
│                   ├── dishes
│                   │   ├── Pizza.java
│                   │   ├── MacAndCheese.java
│                   │   └── BUILD
│                   ├── ingredients
│                   │   ├── Cheese.java
│                   │   ├── Tomatoes.java
│                   │   ├── Dough.java
│                   │   ├── Macaroni.java
│                   │   └── BUILD
│                   ├── restaurant
│                   │   ├── Cafe.java
│                   │   ├── Chef.java
│                   │   └── BUILD
│                   ├── reviews
│                   │   ├── Review.java
│                   │   └── BUILD
│                   └── Runner.java
└── MODULE.bazel

Ao longo deste tutorial, a menos que seja indicado de outra forma, tente não procurar nos arquivos BUILD as informações necessárias e use apenas a função de consulta.

Um projeto consiste em diferentes pacotes que compõem um café. Eles são separados em: restaurant, ingredients, dishes, customers e reviews. As regras nesses pacotes definem diferentes componentes do café com várias tags e dependências.

Executar uma versão

Esse projeto contém um método principal em Runner.java que pode ser executado para imprimir um cardápio do café. Crie o projeto usando o Bazel com o comando bazel build e use : para indicar que o destino se chama runner. Consulte os nomes de destino para saber como referenciar destinos.

Para criar esse projeto, cole este comando em um terminal:

bazel build :runner

A saída será parecida com esta se a criação for bem-sucedida.

INFO: Analyzed target //:runner (49 packages loaded, 784 targets configured).
INFO: Found 1 target...
Target //:runner up-to-date:
  bazel-bin/runner.jar
  bazel-bin/runner
INFO: Elapsed time: 16.593s, Critical Path: 4.32s
INFO: 23 processes: 4 internal, 10 darwin-sandbox, 9 worker.
INFO: Build completed successfully, 23 total actions

Depois de criado, execute o aplicativo colando este comando:

bazel-bin/runner

--------------------- MENU -------------------------

Pizza - Cheesy Delicious Goodness
Macaroni & Cheese - Kid-approved Dinner

----------------------------------------------------

Isso deixa você com uma lista dos itens do cardápio e uma breve descrição.

Como explorar destinos

O projeto lista ingredientes e pratos nos próprios pacotes. Para usar uma consulta para conferir as regras de um pacote, execute o comando bazel query package/…

Nesse caso, você pode usar isso para conferir os ingredientes e pratos que esse café tem executando:

bazel query //src/main/java/com/example/dishes/...

bazel query //src/main/java/com/example/ingredients/...

Se você consultar os destinos do pacote de ingredientes, a saída será parecida com esta:

//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/ingredients:dough
//src/main/java/com/example/ingredients:macaroni
//src/main/java/com/example/ingredients:tomato

Encontrar dependências

Em quais destinos o runner depende para ser executado?

Digamos que você queira se aprofundar na estrutura do projeto sem investigar o sistema de arquivos (o que pode ser inviável para projetos grandes). Quais regras o Cafe Bazel usa?

Se, como neste exemplo, o destino do runner for runner, descubra as dependências subjacentes do destino executando o comando:

bazel query --noimplicit_deps "deps(target)"

bazel query --noimplicit_deps "deps(:runner)"

//:runner
//:src/main/java/com/example/Runner.java
//src/main/java/com/example/dishes:MacAndCheese.java
//src/main/java/com/example/dishes:Pizza.java
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:Cheese.java
//src/main/java/com/example/ingredients:Dough.java
//src/main/java/com/example/ingredients:Macaroni.java
//src/main/java/com/example/ingredients:Tomato.java
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/ingredients:dough
//src/main/java/com/example/ingredients:macaroni
//src/main/java/com/example/ingredients:tomato
//src/main/java/com/example/restaurant:Cafe.java
//src/main/java/com/example/restaurant:Chef.java
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

Na maioria dos casos, use a função de consulta deps() para conferir as dependências de saída individuais de um destino específico.

Visualizar o gráfico de dependência (opcional)

A seção descreve como visualizar os caminhos de dependência de uma consulta específica. O Graphviz ajuda a conferir o caminho como uma imagem de gráfico acíclico dirigido, em vez de uma lista nivelada. É possível alterar a exibição do gráfico de consulta do Bazel usando várias opções de linha de comando --output. Consulte Formatos de saída para opções.

Comece executando a consulta desejada e adicione a flag --noimplicit_deps para remover dependências excessivas de ferramentas. Em seguida, siga a consulta com a flag de saída e armazene o gráfico em um arquivo chamado graph.in para criar uma representação de texto do gráfico.

Para pesquisar todas as dependências do destino :runner e formatar a saída como um gráfico:

bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph.in

Isso cria um arquivo chamado graph.in, que é uma representação de texto do gráfico de build. O Graphviz usa dot – uma ferramenta que processa texto em uma visualização – para criar um PNG:

dot -Tpng < graph.in > graph.png

Se você abrir graph.png, verá algo parecido com isto. O gráfico abaixo foi simplificado para deixar os detalhes essenciais do caminho mais claros neste guia.

Isso ajuda quando você quer conferir as saídas das diferentes funções de consulta neste guia.

Encontrar dependências inversas

Se você tiver um destino que gostaria de analisar quais outros destinos o usam, use uma consulta para examinar quais destinos dependem de uma determinada regra. Isso é chamado de "dependência inversa". O uso de rdeps() pode ser útil ao editar um arquivo em uma base de código que você não conhece e pode evitar que você quebre outros arquivos que dependiam dele.

Por exemplo, você quer fazer algumas edições no ingrediente cheese. Para evitar problemas no Cafe Bazel, é necessário verificar quais pratos dependem de cheese.

Para conferir quais destinos dependem de um destino/pacote específico, use rdeps(universe_scope, target). A função de consulta rdeps() usa pelo menos dois argumentos: um universe_scope (o diretório relevante) e um target. O Bazel pesquisa as dependências inversas do destino no universe_scope fornecido. O operador rdeps() aceita um terceiro argumento opcional: um literal inteiro que especifica o limite superior na profundidade da pesquisa.

Para procurar dependências inversas do destino cheese no escopo de todo o projeto "//…", execute o comando:

bazel query "rdeps(universe_scope, target)"

ex) bazel query "rdeps(//... , //src/main/java/com/example/ingredients:cheese)"

//:runner
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

O retorno da consulta mostra que o queijo é usado tanto na pizza quanto no macarrão com queijo. Que surpresa!

Encontrar destinos com base em tags

Dois clientes entram no Bazel Cafe: Amir e Jenny. Não há nada conhecido sobre eles, exceto os nomes. Felizmente, os pedidos deles estão marcados no arquivo BUILD "customers". Como acessar essa tag?

Os desenvolvedores podem marcar destinos do Bazel com diferentes identificadores, geralmente para fins de teste. Por exemplo, as tags em testes podem anotar o papel de um teste no processo de depuração e lançamento, especialmente para testes em C++ e Python, que não têm capacidade de anotação de ambiente de execução. O uso de tags e elementos de tamanho oferece flexibilidade na montagem de conjuntos de testes com base na política de check-in de uma base de código.

Neste exemplo, as tags são pizza ou macAndCheese para representar os itens do cardápio. Esse comando consulta destinos que têm tags correspondentes ao identificador em um determinado pacote.

bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)'

Essa consulta retorna todos os destinos no pacote "customers" que têm uma tag de "pizza".

Teste seus conhecimentos

Use essa consulta para saber o que Jenny quer pedir.

Adicionar uma nova dependência

O Cafe Bazel expandiu o cardápio. Agora os clientes podem pedir um smoothie. Esse smoothie específico consiste nos ingredientes Strawberry e Banana.

Primeiro, adicione os ingredientes de que o smoothie depende: Strawberry.java e Banana.java. Adicione as classes Java vazias.

src/main/java/com/example/ingredients/Strawberry.java

package com.example.ingredients;

public class Strawberry {

}

src/main/java/com/example/ingredients/Banana.java

package com.example.ingredients;

public class Banana {

}

Em seguida, adicione Smoothie.java ao diretório apropriado: dishes.

src/main/java/com/example/dishes/Smoothie.java

package com.example.dishes;

public class Smoothie {
    public static final String DISH_NAME = "Smoothie";
    public static final String DESCRIPTION = "Yummy and Refreshing";
}

Por fim, adicione esses arquivos como regras nos arquivos BUILD apropriados. Crie uma nova biblioteca Java para cada novo ingrediente, incluindo o nome, a visibilidade pública e o arquivo "src" recém-criado. Você vai acabar com este arquivo BUILD atualizado:

src/main/java/com/example/ingredients/BUILD

java_library(
    name = "cheese",
    visibility = ["//visibility:public"],
    srcs = ["Cheese.java"],
)

java_library(
    name = "dough",
    visibility = ["//visibility:public"],
    srcs = ["Dough.java"],
)

java_library(
    name = "macaroni",
    visibility = ["//visibility:public"],
    srcs = ["Macaroni.java"],
)

java_library(
    name = "tomato",
    visibility = ["//visibility:public"],
    srcs = ["Tomato.java"],
)

java_library(
    name = "strawberry",
    visibility = ["//visibility:public"],
    srcs = ["Strawberry.java"],
)

java_library(
    name = "banana",
    visibility = ["//visibility:public"],
    srcs = ["Banana.java"],
)

No arquivo BUILD de pratos, adicione uma nova regra para Smoothie. Isso inclui o arquivo Java criado para Smoothie como um arquivo "src" e as novas regras criadas para cada ingrediente do smoothie.

src/main/java/com/example/dishes/BUILD

java_library(
    name = "macAndCheese",
    visibility = ["//visibility:public"],
    srcs = ["MacAndCheese.java"],
    deps = [
        "//src/main/java/com/example/ingredients:cheese",
        "//src/main/java/com/example/ingredients:macaroni",
    ],
)

java_library(
    name = "pizza",
    visibility = ["//visibility:public"],
    srcs = ["Pizza.java"],
    deps = [
        "//src/main/java/com/example/ingredients:cheese",
        "//src/main/java/com/example/ingredients:dough",
        "//src/main/java/com/example/ingredients:tomato",
    ],
)

java_library(
    name = "smoothie",
    visibility = ["//visibility:public"],
    srcs = ["Smoothie.java"],
    deps = [
        "//src/main/java/com/example/ingredients:strawberry",
        "//src/main/java/com/example/ingredients:banana",
    ],
)

Por fim, inclua o smoothie como uma dependência no arquivo BUILD do chef.

src/main/java/com/example/restaurant/BUILD

java\_library(
    name = "chef",
    visibility = ["//visibility:public"],
    srcs = [
        "Chef.java",
    ],

    deps = [
        "//src/main/java/com/example/dishes:macAndCheese",
        "//src/main/java/com/example/dishes:pizza",
        "//src/main/java/com/example/dishes:smoothie",
    ],
)

java\_library(
    name = "cafe",
    visibility = ["//visibility:public"],
    srcs = [
        "Cafe.java",
    ],
    deps = [
        ":chef",
    ],
)

Crie cafe novamente para confirmar que não há erros. Se a criação for bem-sucedida, parabéns! Você adicionou uma nova dependência para o "Cafe". Caso contrário, procure erros de ortografia e nomenclatura de pacotes. Para mais informações sobre como gravar arquivos BUILD, consulte o Guia de estilo de BUILD.

Agora, visualize o novo gráfico de dependência com a adição do Smoothie para comparar com o anterior. Para maior clareza, nomeie a entrada do gráfico como graph2.in e graph2.png.

bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph2.in

dot -Tpng < graph2.in > graph2.png

Ao analisar graph2.png, você pode conferir que Smoothie não tem dependências compartilhadas com outros pratos, mas é apenas outro destino de que o Chef depende.

somepath() e allpaths()

E se você quiser consultar por que um pacote depende de outro? Mostrar um caminho de dependência entre os dois fornece a resposta.

Duas funções podem ajudar você a encontrar caminhos de dependência: somepath() e allpaths(). Dado um destino inicial S e um ponto final E, encontre um caminho entre S e E usando somepath(S,E).

Explore as diferenças entre essas duas funções analisando as relações entre os destinos "Chef" e "Cheese". Há diferentes caminhos possíveis para ir de um destino para o outro:

• Chef → MacAndCheese → Cheese
• Chef → Pizza → Cheese

somepath() oferece um único caminho entre as duas opções, enquanto 'allpaths()' gera todos os caminhos possíveis.

Usando o Cafe Bazel como exemplo, execute o seguinte:

bazel query "somepath(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)"

//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/ingredients:cheese

A saída segue o primeiro caminho de Cafe → Chef → MacAndCheese → Cheese. Se você usar allpaths() em vez disso, receberá:

bazel query "allpaths(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)"

//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

A saída de allpaths() é um pouco mais difícil de ler, já que é uma lista nivelada das dependências. A visualização desse gráfico usando o Graphviz torna a relação mais clara.

Teste seus conhecimentos

Um dos clientes do Cafe Bazel fez a primeira avaliação do restaurante. Infelizmente, a avaliação não tem alguns detalhes, como a identidade do avaliador e a qual prato ela se refere. Felizmente, você pode acessar essas informações com o Bazel. O pacote reviews contém um programa que imprime uma avaliação de um cliente misterioso. Crie e execute com:

bazel build //src/main/java/com/example/reviews:review

bazel-bin/src/main/java/com/example/reviews/review

Usando apenas consultas do Bazel, tente descobrir quem escreveu a avaliação e qual prato estava descrevendo.

Conclusão

Parabéns! Agora você executou várias consultas básicas, que podem ser testadas em seus próprios projetos. Para saber mais sobre a sintaxe da linguagem de consulta, consulte a página de referência de consulta. Quer consultas mais avançadas? O guia de consulta mostra uma lista detalhada de mais casos de uso do que os abordados neste guia.