Este tutorial aborda os conceitos básicos da criação de aplicativos Java com o Bazel. Você vai configurar seu espaço de trabalho e criar um projeto Java simples que
ilustra os principais conceitos do Bazel, como destinos e arquivos BUILD
.
Tempo estimado de conclusão: 30 minutos.
O que você vai aprender
Neste tutorial, você vai aprender a:
- Criar um destino
- Visualizar as dependências do projeto
- Dividir o projeto em vários destinos e pacotes
- Controlar a visibilidade do destino em pacotes
- Fazer referência a destinos com rótulos
- Implantar um destino
Antes de começar
Instalar o Bazel
Para se preparar para o tutorial, instale o Bazel se ele ainda não estiver instalado.
Instalar o JDK
Instale o Java JDK (a versão preferencial é a 11, mas há suporte para versões entre 8 e 15).
Defina a variável de ambiente JAVA_HOME para apontar para o JDK.
No Linux/macOS:
export JAVA_HOME="$(dirname $(dirname $(realpath $(which javac))))"
No Windows:
- Abra o Painel de Controle.
- Acesse "Sistema e segurança" > "Sistema" > "Configurações avançadas do sistema" > guia "Avançado" > "Variáveis de ambiente..." .
- Na lista "Variáveis do usuário" (a que está na parte de cima), clique em "Nova".
- No campo "Nome da variável", insira
JAVA_HOME
. - Clique em "Procurar diretório...".
- Navegue até o diretório JDK (por exemplo,
C:\Program Files\Java\jdk1.8.0_152
). - Clique em "OK" em todas as janelas de diálogo.
Fazer o download do projeto de exemplo
Extraia o projeto de exemplo do repositório do GitHub do Bazel:
git clone https://github.com/bazelbuild/examples
O projeto de amostra deste tutorial está no diretório examples/java-tutorial
e é estruturado da seguinte maneira:
java-tutorial
├── BUILD
├── src
│ └── main
│ └── java
│ └── com
│ └── example
│ ├── cmdline
│ │ ├── BUILD
│ │ └── Runner.java
│ ├── Greeting.java
│ └── ProjectRunner.java
└── MODULE.bazel
Criação com o Bazel
Configurar o espaço de trabalho
Antes de criar um projeto, é preciso configurar o espaço de trabalho dele. Um espaço de trabalho é um diretório que contém os arquivos de origem do seu projeto e as saídas de build do Bazel. Ele também contém arquivos que o Bazel reconhece como especiais:
O arquivo
MODULE.bazel
, que identifica o diretório e o conteúdo dele como um espaço de trabalho do Bazel e reside na raiz da estrutura de diretórios do projeto.Um ou mais arquivos
BUILD
, que informam ao Bazel como criar diferentes partes do projeto. Um diretório no espaço de trabalho que contém um arquivoBUILD
é um pacote. Você vai aprender sobre pacotes mais adiante neste tutorial.)
Para designar um diretório como um espaço de trabalho do Bazel, crie um arquivo vazio chamado
MODULE.bazel
nesse diretório.
Quando o Bazel cria o projeto, todas as entradas e dependências precisam estar no mesmo espaço de trabalho. Os arquivos em espaços de trabalho diferentes são independentes uns dos outros, a menos que estejam vinculados, o que está fora do escopo deste tutorial.
Entenda o arquivo BUILD
Um arquivo BUILD
contém vários tipos diferentes de instruções para o Bazel.
O tipo mais importante é a regra de build, que informa ao Bazel como criar as
saídas que você quer, como binários ou bibliotecas executáveis. Cada instância
de uma regra de build no arquivo BUILD
é chamada de target e aponta para um
conjunto específico de arquivos de origem e dependências. Um destino também pode apontar para outros
destinos.
Dê uma olhada no arquivo java-tutorial/BUILD
:
java_binary(
name = "ProjectRunner",
srcs = glob(["src/main/java/com/example/*.java"]),
)
No nosso exemplo, o destino ProjectRunner
instancia a regra
java_binary
integrada do Bazel. A regra instrui o Bazel a
criar um arquivo .jar
e um script de shell wrapper (ambos com o nome do destino).
Os atributos no destino declaram explicitamente as dependências e opções.
Embora o atributo name
seja obrigatório, muitos são opcionais. Por exemplo, no
destino da regra ProjectRunner
, name
é o nome do destino, srcs
especifica
os arquivos de origem que o Bazel usa para criar o destino, e main_class
especifica
a classe que contém o método principal. Você pode ter notado que nosso exemplo
usa glob para transmitir um conjunto de arquivos de origem ao Bazel
em vez de listá-los um por um.
Criar o projeto
Para criar seu projeto de exemplo, navegue até o diretório java-tutorial
e execute:
bazel build //:ProjectRunner
No rótulo de destino, a parte //
é o local do arquivo BUILD
em relação à raiz do espaço de trabalho (nesse caso, a própria raiz), e ProjectRunner
é o nome do destino no arquivo BUILD
. Você vai
aprender mais sobre os rótulos de destino no final deste tutorial.
O Bazel produz uma saída semelhante a esta:
INFO: Found 1 target...
Target //:ProjectRunner up-to-date:
bazel-bin/ProjectRunner.jar
bazel-bin/ProjectRunner
INFO: Elapsed time: 1.021s, Critical Path: 0.83s
Parabéns, você acabou de criar seu primeiro destino do Bazel. Ele coloca as saídas de compilação no diretório bazel-bin
na raiz do espaço de trabalho. Navegue
pelo conteúdo para ter uma ideia da estrutura de saída do Bazel.
Agora teste o binário recém-criado:
bazel-bin/ProjectRunner
Analisar o gráfico de dependência
O Bazel exige que as dependências de build sejam declaradas explicitamente nos arquivos BUILD. O Bazel usa essas instruções para criar o gráfico de dependência do projeto, que permite builds incrementais precisos.
Para visualizar as dependências do projeto de exemplo, gere uma representação de texto do gráfico de dependência executando este comando na raiz do espaço de trabalho:
bazel query --notool_deps --noimplicit_deps "deps(//:ProjectRunner)" --output graph
O comando acima instrui o Bazel a procurar todas as dependências do destino
//:ProjectRunner
(exceto o host e as dependências implícitas) e formatar a
saída como um gráfico.
Depois, cole o texto no GraphViz.
Como você pode ver, o projeto tem um único destino que gera dois arquivos de origem sem dependências adicionais:
Depois de configurar seu espaço de trabalho, criar seu projeto e examinar as dependências, você pode adicionar um pouco de complexidade.
Refinar o build do Bazel
Embora um único destino seja suficiente para projetos pequenos, é possível dividir projetos maiores em vários destinos e pacotes para permitir builds incrementais rápidos, ou seja, apenas reconstruir o que mudou, e acelerar seus builds criando várias partes de um projeto de uma só vez.
Especificar vários destinos de build
É possível dividir o build do projeto de amostra em dois destinos. Substitua o conteúdo do
arquivo java-tutorial/BUILD
pelo seguinte:
java_binary(
name = "ProjectRunner",
srcs = ["src/main/java/com/example/ProjectRunner.java"],
main_class = "com.example.ProjectRunner",
deps = [":greeter"],
)
java_library(
name = "greeter",
srcs = ["src/main/java/com/example/Greeting.java"],
)
Com essa configuração, o Bazel primeiro cria a biblioteca greeter
e depois o
binário ProjectRunner
. O atributo deps
em java_binary
informa ao Bazel que
a biblioteca greeter
é necessária para criar o binário ProjectRunner
.
Para criar essa nova versão do projeto, execute o seguinte comando:
bazel build //:ProjectRunner
O Bazel produz uma saída semelhante a esta:
INFO: Found 1 target...
Target //:ProjectRunner up-to-date:
bazel-bin/ProjectRunner.jar
bazel-bin/ProjectRunner
INFO: Elapsed time: 2.454s, Critical Path: 1.58s
Agora teste o binário recém-criado:
bazel-bin/ProjectRunner
Se você modificar ProjectRunner.java
e recriar o projeto, o Bazel vai
recompilá-lo.
Analisando o gráfico de dependência, é possível ver que ProjectRunner
depende das
mesmas entradas que antes, mas a estrutura do build é diferente:
Você criou o projeto com dois destinos. O destino ProjectRunner
cria
dois arquivos de origem e depende de um outro destino (:greeter
), que cria
um arquivo de origem extra.
Usar vários pacotes
Agora vamos dividir o projeto em vários pacotes. Se você olhar o
diretório src/main/java/com/example/cmdline
, vai notar que ele também contém
um arquivo BUILD
, além de alguns arquivos de origem. Portanto, para o Bazel, o espaço de trabalho agora
contém dois pacotes, //src/main/java/com/example/cmdline
e //
, já que
há um arquivo BUILD
na raiz do espaço de trabalho.
Confira o arquivo src/main/java/com/example/cmdline/BUILD
:
java_binary(
name = "runner",
srcs = ["Runner.java"],
main_class = "com.example.cmdline.Runner",
deps = ["//:greeter"],
)
O destino runner
depende do destino greeter
no pacote //
(por isso
o rótulo de destino //:greeter
). O Bazel sabe disso pelo atributo deps
.
Confira o gráfico de dependência:
No entanto, para que o build seja bem-sucedido, é necessário dar explicitamente o destino runner
em visibilidade //src/main/java/com/example/cmdline/BUILD
para destinos em
//BUILD
usando o atributo visibility
. Isso acontece porque, por padrão, as segmentações
são visíveis apenas para outras segmentações no mesmo arquivo BUILD
. O Bazel usa a visibilidade
de destino para evitar problemas, como bibliotecas que contêm detalhes de implementação
vazando para APIs públicas.
Para fazer isso, adicione o atributo visibility
ao destino greeter
em
java-tutorial/BUILD
, conforme mostrado abaixo:
java_library(
name = "greeter",
srcs = ["src/main/java/com/example/Greeting.java"],
visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
)
Agora você pode criar o novo pacote executando o seguinte comando na raiz do espaço de trabalho:
bazel build //src/main/java/com/example/cmdline:runner
O Bazel produz uma saída semelhante a esta:
INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner up-to-date:
bazel-bin/src/main/java/com/example/cmdline/runner.jar
bazel-bin/src/main/java/com/example/cmdline/runner
INFO: Elapsed time: 1.576s, Critical Path: 0.81s
Agora teste o binário recém-criado:
./bazel-bin/src/main/java/com/example/cmdline/runner
Agora você modificou o projeto para criar dois pacotes, cada um contendo um destino, e entendeu as dependências entre eles.
Usar rótulos para fazer referência a destinos
Em arquivos BUILD
e na linha de comando, o Bazel usa rótulos de destino para fazer referência
a destinos, por exemplo, //:ProjectRunner
ou
//src/main/java/com/example/cmdline:runner
. A sintaxe é a seguinte:
//path/to/package:target-name
Se o destino for um destino de regra, path/to/package
será o caminho para o
diretório que contém o arquivo BUILD
, e target-name
será o nome que você deu ao
destino no arquivo BUILD
(o atributo name
). Se o destino for um destino de
arquivo, path/to/package
será o caminho para a raiz do pacote e
target-name
será o nome do arquivo de destino, incluindo o caminho completo.
Ao fazer referência a destinos na raiz do repositório, o caminho do pacote fica vazio.
Basta usar //:target-name
. Ao referenciar destinos no mesmo arquivo BUILD
,
é possível pular o identificador raiz do espaço de trabalho //
e usar apenas
:target-name
.
Por exemplo, para destinos no arquivo java-tutorial/BUILD
, não era necessário
especificar um caminho de pacote, já que a raiz do espaço de trabalho é um pacote (//
) e
os dois rótulos de destino eram simplesmente //:ProjectRunner
e //:greeter
.
No entanto, para destinos no arquivo //src/main/java/com/example/cmdline/BUILD
,
você precisa especificar o caminho completo do pacote de //src/main/java/com/example/cmdline
e o rótulo de destino era //src/main/java/com/example/cmdline:runner
.
Criar um pacote de destino Java para implantação
Agora, vamos empacotar um destino Java para implantação criando o binário com todas as dependências do ambiente de execução. Isso permite executar o binário fora do ambiente de desenvolvimento.
Como você se lembra, a regra de compilação java_binary produz um .jar
e um script de shell de wrapper. Confira o conteúdo de
runner.jar
usando este comando:
jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar
O conteúdo é o seguinte:
META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class
Como você pode ver, runner.jar
contém Runner.class
, mas não a dependência
Greeting.class
. O script runner
gerado pelo Bazel adiciona greeter.jar
ao classpath. Se você deixar assim, ele será executado localmente, mas
não será executado de forma independente em outra máquina. Felizmente, a regra java_binary
permite criar um binário independente e implantável. Para criá-lo, anexe
_deploy.jar
ao nome do destino:
bazel build //src/main/java/com/example/cmdline:runner_deploy.jar
O Bazel produz uma saída semelhante a esta:
INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date:
bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
INFO: Elapsed time: 1.700s, Critical Path: 0.23s
Você acabou de criar runner_deploy.jar
, que pode ser executado de forma independente do
ambiente de desenvolvimento, já que contém as dependências de execução
necessárias. Confira o conteúdo desse JAR independente usando o
mesmo comando de antes:
jar tf bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
O conteúdo inclui todas as classes necessárias para execução:
META-INF/
META-INF/MANIFEST.MF
build-data.properties
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class
com/example/Greeting.class
Leitura adicional
Confira mais detalhes em:
rules_jvm_external para regras para gerenciar dependências do Maven transitivas.
Dependências externas para saber mais sobre como trabalhar com repositórios locais e remotos.
As outras regras para saber mais sobre o Bazel.
Confira o tutorial de build C++ para começar a criar projetos C++ com o Bazel.
O tutorial de aplicativos Android e tutorial de aplicativos iOS (links em inglês) para começar a criar aplicativos para dispositivos móveis para Android e iOS com o Bazel.
Boa construção!