Tutorial do Bazel: criar um app Android

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1
Observação:há limitações conhecidas no uso do Bazel para criar apps Android. Acesse a página de problemas do rules_android (link em inglês) para conferir a lista de problemas conhecidos. Embora a equipe do Bazel e os colaboradores de software de código aberto (OSS) trabalhem ativamente para resolver problemas conhecidos, os usuários precisam saber que o Android Studio não oferece suporte oficial a projetos do Bazel.

Este tutorial aborda como criar um app Android simples usando o Bazel.

O Bazel oferece suporte à criação de apps Android usando as regras do Android.

Este tutorial é destinado a usuários do Windows, macOS e Linux e não exige experiência com o Bazel ou o desenvolvimento de apps Android. Não é necessário escrever nenhum código Android neste tutorial.

O que você vai aprender

Neste tutorial, você vai aprender a:

  • Configurar seu ambiente instalando o Bazel e o Android Studio e fazendo o download do projeto de exemplo.
  • Configurar um espaço de trabalho do Bazel que contenha o código-fonte do app e um arquivo MODULE.bazel que identifique o nível superior do diretório do espaço de trabalho.
  • Atualizar o arquivo MODULE.bazel para conter referências às dependências externas necessárias, como o SDK do Android.
  • Criar um arquivo BUILD.
  • Criar o app com o Bazel.
  • Implantar e executar o app em um emulador Android ou dispositivo físico.

Antes de começar

Instalar o Bazel

Antes de começar o tutorial, instale o seguinte software:

  • Bazel. Para instalar, siga as instruções de instalação.
  • Android Studio. Para instalar, siga as etapas para fazer o download do Android Studio. Execute o assistente de configuração para fazer o download do SDK e configurar seu ambiente.
  • (Opcional) Git. Use git para fazer o download do projeto do app Android.

Acessar o projeto de exemplo

Para o projeto de exemplo, use o projeto do app Android do tutorial no repositório de exemplos do Bazel.

Esse app tem um único botão que imprime uma saudação quando clicado:

Saudação do botão

Figura 1. Saudação do botão do app Android.

Clone o repositório com git (ou faça o download do arquivo ZIP diretamente):

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

O projeto de exemplo para este tutorial está em examples/android/tutorial. Para o restante do tutorial, você vai executar comandos nesse diretório.

Analisar os arquivos de origem

Confira os arquivos de origem do app.

.
├── README.md
└── src
    └── main
        ├── AndroidManifest.xml
        └── java
            └── com
                └── example
                    └── bazel
                        ├── AndroidManifest.xml
                        ├── Greeter.java
                        ├── MainActivity.java
                        └── res
                            ├── layout
                            │   └── activity_main.xml
                            └── values
                                ├── colors.xml
                                └── strings.xml

Os principais arquivos e diretórios são:

Nome Local
Arquivos de manifesto do Android src/main/AndroidManifest.xml e src/main/java/com/example/bazel/AndroidManifest.xml
Arquivos de origem do Android src/main/java/com/example/bazel/MainActivity.java e Greeter.java
Diretório de arquivos de recursos src/main/java/com/example/bazel/res/

Criação com o Bazel

Configurar o espaço de trabalho

Um espaço de trabalho é um diretório que contém os arquivos de origem de um ou mais projetos de software e tem um arquivo MODULE.bazel na raiz.

O arquivo MODULE.bazel pode estar vazio ou conter referências a dependências externas necessárias para criar seu projeto.

Primeiro, execute o comando a seguir para criar um arquivo MODULE.bazel vazio:

SO Comando
Linux, macOS touch MODULE.bazel
Windows (prompt de comando) type nul > MODULE.bazel
Windows (PowerShell) New-Item MODULE.bazel -ItemType file

Executar o Bazel

Agora você pode verificar se o Bazel está sendo executado corretamente com o comando:

bazel info workspace

Se o Bazel mostrar o caminho do diretório atual, você poderá continuar. Se o arquivo MODULE.bazel não existir, uma mensagem de erro como esta será exibida:

ERROR: The 'info' command is only supported from within a workspace.

Integrar com o SDK do Android

O Bazel precisa executar as ferramentas de build do SDK do Android para criar o app. Isso significa que você precisa adicionar algumas informações ao arquivo MODULE.bazel para que o Bazel saiba onde encontrá-las.

Adicione a linha a seguir ao arquivo MODULE.bazel:

bazel_dep(name = "rules_android", version = "0.6.6")

remote_android_extensions = use_extension(
    "@rules_android//bzlmod_extensions:android_extensions.bzl",
    "remote_android_tools_extensions")
use_repo(remote_android_extensions, "android_tools")

android_sdk_repository_extension = use_extension("@rules_android//rules/android_sdk_repository:rule.bzl", "android_sdk_repository_extension")
use_repo(android_sdk_repository_extension, "androidsdk")

Isso vai usar o SDK do Android no caminho referenciado pela variável de ambiente ANDROID_HOME e detectar automaticamente o nível da API mais alto e a versão mais recente das ferramentas de build instaladas nesse local.

Você pode definir a variável ANDROID_HOME para o local do SDK do Android. Encontre o caminho para o SDK instalado usando o SDK Manager do Android Studio. Supondo que o SDK esteja instalado nos locais padrão, você pode usar os comandos a seguir para definir a variável ANDROID_HOME:

SO Comando
Linux export ANDROID_HOME=$HOME/Android/Sdk/
macOS export ANDROID_HOME=$HOME/Library/Android/sdk
Windows (prompt de comando) set ANDROID_HOME=%LOCALAPPDATA%\Android\Sdk
Windows (PowerShell) $env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"

Os comandos acima definem a variável apenas para a sessão de shell atual. Para torná-los permanentes, execute os seguintes comandos:

SO Comando
Linux echo "export ANDROID_HOME=$HOME/Android/Sdk/" >> ~/.bashrc
macOS echo "export ANDROID_HOME=$HOME/Library/Android/Sdk/" >> ~/.bashrc
Windows (prompt de comando) setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"
Windows (PowerShell) [System.Environment]::SetEnvironmentVariable('ANDROID_HOME', "$env:LOCALAPPDATA\Android\Sdk", [System.EnvironmentVariableTarget]::User)

Opcional: se você quiser compilar código nativo no seu app Android, também precisará fazer o download do Android NDK e usar rules_android_ndk adicionando a linha a seguir ao arquivo MODULE.bazel:

bazel_dep(name = "rules_android_ndk", version = "0.1.3")

Para mais informações, leia Como usar o Android Native Development Kit com o Bazel.

Não é necessário definir os níveis da API com o mesmo valor para o SDK e o NDK. Esta página contém um mapa de versões do Android para níveis da API com suporte do NDK.

Criar um arquivo BUILD

Um arquivo BUILD descreve a relação entre um conjunto de saídas de build, como recursos compilados do Android de aapt ou arquivos de classe de javac, e as dependências deles. Essas dependências podem ser arquivos de origem (Java, C++) no seu espaço de trabalho ou outras saídas de build. Os arquivos BUILD são escritos em uma linguagem chamada Starlark.

Os arquivos BUILD fazem parte de um conceito no Bazel conhecido como hierarquia de pacotes. A hierarquia de pacotes é uma estrutura lógica que sobrepõe a estrutura de diretórios no seu espaço de trabalho. Cada pacote é um diretório (e os subdiretórios dele) que contém um conjunto relacionado de arquivos de origem e um arquivo BUILD. O pacote também inclui todos os subdiretórios, exceto aqueles que contêm o próprio arquivo BUILD. O nome do pacote é o caminho para o arquivo BUILD em relação ao arquivo MODULE.bazel.

A hierarquia de pacotes do Bazel é conceitualmente diferente da hierarquia de pacotes Java do diretório do app Android em que o arquivo BUILD está localizado, embora os diretórios possam ser organizados de forma idêntica.

Para o app Android simples neste tutorial, os arquivos de origem em src/main/ compreendem um único pacote do Bazel. Um projeto mais complexo pode ter muitos pacotes aninhados.

Adicionar uma regra android_library

Um arquivo BUILD contém vários tipos diferentes de declarações para o Bazel. O tipo mais importante é a regra de build, que informa ao Bazel como criar uma saída de software intermediária ou final de um conjunto de arquivos de origem ou outras dependências. O Bazel oferece duas regras de build, android_library e android_binary, que podem ser usadas para criar um app Android.

Para este tutorial, você vai usar primeiro a regra android_library para informar ao Bazel que crie um módulode biblioteca do Android com o código-fonte do app e os arquivos de recursos. Em seguida, você vai usar a regra android_binary para informar ao Bazel como criar o pacote de aplicativos Android.

Crie um arquivo BUILD no diretório src/main/java/com/example/bazel e declare um novo destino android_library:

src/main/java/com/example/bazel/BUILD:

load("@rules_android//rules:rules.bzl", "android_library")

package(
    default_visibility = ["//src:__subpackages__"],
)

android_library(
    name = "greeter_activity",
    srcs = [
        "Greeter.java",
        "MainActivity.java",
    ],
    manifest = "AndroidManifest.xml",
    resource_files = glob(["res/**"]),
)

A regra de build android_library contém um conjunto de atributos que especificam as informações necessárias para que o Bazel crie um módulo de biblioteca com os arquivos de origem. Observe também que o nome da regra é greeter_activity. Você vai referenciar a regra usando esse nome como uma dependência na regra android_binary.

Adicionar uma regra android_binary

A regra android_binary cria o pacote de aplicativos Android (arquivo .apk) para seu app.

Crie um arquivo BUILD no diretório src/main/ e declare um novo destino android_binary:

src/main/BUILD:

load("@rules_android//rules:rules.bzl", "android_binary")

android_binary(
    name = "app",
    manifest = "//src/main/java/com/example/bazel:AndroidManifest.xml",
    deps = ["//src/main/java/com/example/bazel:greeter_activity"],
)

Aqui, o atributo deps referencia a saída da regra greeter_activity que você adicionou ao arquivo BUILD acima. Isso significa que, quando o Bazel cria a saída dessa regra, ele verifica primeiro se a saída da regra da biblioteca greeter_activity foi criada e está atualizada. Caso contrário, o Bazel a cria e usa essa saída para criar o arquivo de pacote de aplicativos.

Agora, salve e feche o arquivo.

Criar o app

Tente criar o app. Execute o comando a seguir para criar o destino android_binary:

bazel build //src/main:app

O build subcomando instrui o Bazel a criar o destino que segue. O destino é especificado como o nome de uma regra de build dentro de um arquivo BUILD, com o caminho do pacote relativo ao diretório do espaço de trabalho. Para este exemplo, o destino é app e o caminho do pacote é //src/main/.

Às vezes, é possível omitir o caminho do pacote ou o nome do destino, dependendo do diretório de trabalho atual na linha de comando e do nome do destino. Para mais detalhes sobre rótulos e caminhos de destino, consulte Rótulos.

O Bazel vai começar a criar o app de exemplo. Durante o processo de build, a saída será semelhante a esta:

INFO: Analysed target //src/main:app (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
Target //src/main:app up-to-date:
  bazel-bin/src/main/app_deploy.jar
  bazel-bin/src/main/app_unsigned.apk
  bazel-bin/src/main/app.apk

Localizar as saídas de build

O Bazel coloca as saídas de operações de build intermediárias e finais em um conjunto de diretórios de saída por usuário e por espaço de trabalho. Esses diretórios são vinculados simbolicamente dos seguintes locais no nível superior do diretório do projeto, em que o arquivo MODULE.bazel está:

  • bazel-bin armazena executáveis binários e outras saídas de build executáveis
  • bazel-genfiles armazena arquivos de origem intermediários gerados pelas regras do Bazel
  • bazel-out armazena outros tipos de saídas de build

O Bazel armazena o arquivo .apk do Android gerado usando a regra android_binary no diretório bazel-bin/src/main, em que o nome do subdiretório src/main é derivado do nome do pacote do Bazel.

Em um prompt de comando, liste o conteúdo desse diretório e encontre o arquivo app.apk:

SO Comando
Linux, macOS ls bazel-bin/src/main
Windows (prompt de comando) dir bazel-bin\src\main
Windows (PowerShell) ls bazel-bin\src\main

Executar o app

Agora você pode implantar o app em um dispositivo Android conectado ou emulador na linha de comando usando bazel mobile-install. Esse comando usa o Android Debug Bridge (adb) para se comunicar com o dispositivo. Você precisa configurar o dispositivo para usar adb seguindo as instruções no Android Debug Bridge antes da implantação. Também é possível instalar o app no emulador Android incluído no Android Studio. Verifique se o emulador está em execução antes de executar o comando abaixo.

Digite o seguinte:

bazel mobile-install //src/main:app \
  --mode=skylark \
  --mobile_install_aspect=@rules_android//mobile_install:mi.bzl \
  --mobile_install_supported_rules=android_binary \
  --java_runtime_version=17 \
  --java_language_version=17 \
  --tool_java_runtime_version=17 \
  --tool_java_language_version=17

As flags extras necessárias para a instalação em dispositivos móveis podem ser adicionadas ao seu arquivo bazelrc do projeto. As flags específicas para instalação em dispositivos móveis (--mode, --mobile_install*) não serão mais necessárias a partir do Bazel 8.4.0. As várias flags Java para linguagem e versão de ambiente de execução podem ser necessárias, dependendo da configuração Java do seu espaço de trabalho. As subferramentas de instalação em dispositivos móveis exigem um nível de linguagem e ambiente de execução de 17 ou mais recente.

Agora, o "Bazel Tutorial App" será instalado e iniciado automaticamente:

App tutorial do Bazel

Figura 2. App do tutorial do Bazel.

Parabéns! Você acabou de instalar seu primeiro app Android criado pelo Bazel.

Leitura adicional

Para mais detalhes, consulte estas páginas:

Divirta-se criando!