É possível executar todas as tarefas de build disponíveis para seu projeto do Android usando a
ferramenta de linha de comando Gradle Wrapper (link em inglês). Ele está disponível como um arquivo em lote para
Windows (gradlew.bat) e um script de shell para Linux e Mac (gradlew.sh) e
pode ser acessado na raiz de cada projeto criado com o Android Studio.
Para executar uma tarefa com o wrapper, use um dos seguintes comandos em uma janela do Terminal (no Android Studio, selecione View > Tool Windows > Terminal):
No shell de comandos do Windows:
gradlew task-nameNo Mac, Linux ou Windows PowerShell:
./gradlew task-name
Para ver uma lista de todas as tarefas de compilação disponíveis para seu
projeto, execute tasks:
gradlew tasks
O restante desta página descreve os conceitos básicos para criar e executar seu app com o wrapper do Gradle. Para mais informações sobre como configurar o build do Android, consulte Configurar o build.
Se preferir usar as ferramentas do Android Studio em vez das ferramentas de linha de comando, consulte Criar e executar o app.
Sobre tipos de compilação
Por padrão, há dois tipos de build disponíveis para cada app Android: um para depurar o app (o build de depuração) e outro para lançar o app para os usuários (o build de lançamento). A saída resultante de cada build precisa ser assinada com um certificado antes de implantar o app em um dispositivo. O build de depuração é assinado automaticamente com uma chave de depuração fornecida pelas ferramentas do SDK (não é seguro e não é possível publicar com ele na Google Play Store), e o build de lançamento precisa ser assinado com sua própria chave privada.
Se você quiser criar seu app para lançamento, também é importante assiná-lo com a chave de assinatura adequada. No entanto, se você estiver começando, pode executar rapidamente seus apps em um emulador ou dispositivo conectado criando um APK de depuração.
Também é possível definir um tipo de build personalizado no arquivo build.gradle.kts e
configurá-lo para ser assinado como um build de depuração incluindo debuggable true. Para
saber mais, consulte Configurar variantes de build.
Criar e implantar um APK
Embora criar um pacote de app seja a melhor maneira de empacotar seu app e fazer upload dele para o Play Console, criar um APK é mais adequado quando você quer testar rapidamente um build de depuração ou compartilhar seu app como um artefato implantável com outras pessoas.
Compilar um APK de depuração
Para testar e depurar o app de forma imediata, você pode compilar um APK de depuração.
O APK de depuração é assinado com uma chave de depuração fornecida pelas Ferramentas do SDK e
permite a depuração usando o
adb.
Para criar um APK de depuração, abra uma linha de comando e navegue até a raiz do
diretório do projeto. Para iniciar um build de depuração, invoque a
tarefa assembleDebug:
gradlew assembleDebug
Desse modo, você criará um APK chamado module_name-debug.apk em
project_name/module_name/build/outputs/apk/.
O arquivo já estará assinado com a chave de depuração e alinhado com
zipalign para você poder
instalá-lo em um dispositivo imediatamente.
Ou, para criar o APK e instalá-lo imediatamente em um emulador em execução ou
dispositivo conectado, invoque installDebug:
gradlew installDebug
A parte "Debug" nos nomes das tarefas é apenas uma
versão em letras concatenadas do nome da
variante de build.
Portanto, ela pode ser substituída por qualquer tipo ou
variante de build que você queira montar ou instalar. Por exemplo, se você tiver uma variação de produto "demo",
poderá criar a versão de depuração com a tarefa
assembleDemoDebug.
Para ver todas as tarefas de build e de instalação disponíveis para cada variante (incluindo
tarefas de desinstalação), execute a tarefa tasks.
Além disso, leia a seção abaixo sobre como executar o app no emulador e como executar o app em um dispositivo.
Criar um pacote de versão ou um APK
Quando estiver tudo pronto para lançar e distribuir o app, crie um APK ou pacote de versão final assinado com sua chave privada. Para ver mais informações, acesse a seção sobre como assinar seu app na linha de comando.
Implantar seu app no emulador
Para usar o Android Emulator, você precisa criar um dispositivo virtual Android (AVD, na sigla em inglês) usando o Android Studio.
Depois que tiver um AVD, inicie o Android Emulator e instale o app da seguinte forma:
Em uma linha de comando, navegue até
android_sdk/tools/e inicie o emulador especificando seu AVD:emulator -avd <var>avd_name</var>Se você não tiver certeza do nome do AVD, execute
emulator -list-avds.Agora você pode instalar o app usando uma das tarefas de instalação do Gradle mencionadas na seção sobre como criar um APK de depuração ou a ferramenta
adb.Se o APK for criado com um SDK de prévia para desenvolvedores (se
targetSdkVersionfor uma letra em vez de um número), você precisará incluir a opção-tcom o comandoinstallpara instalar um APK de teste.adb install <var>path/to/your_app</var>.apkTodos os APKs criados são salvos em
project_name/module_name/build/outputs/apk/.
Para saber mais, leia Executar apps no Android Emulator.
Implantar seu app em um dispositivo físico
Antes de executar o app em um dispositivo, você precisa ativar a depuração USB no dispositivo. Essa opção pode ser encontrada em Configurações > Opções do desenvolvedor.
Depois que o dispositivo estiver configurado e conectado por USB, você poderá instalar o app
usando as tarefas de instalação do Gradle mencionadas
na seção sobre como criar um APK de depuração ou a
ferramenta adb:
adb -d install path/to/your_app.apk
Todos os APKs que você cria são salvos em
project_name/module_name/build/outputs/apk/.
Para saber mais, consulte Executar apps em um dispositivo de hardware.
Criar um pacote de app
Os Android App Bundles incluem todo o código e os recursos compilados do app, mas adiam a geração e a assinatura do APK para o Google Play. Diferentemente de um APK, não é possível implantar um pacote de apps diretamente em um dispositivo. Por isso, se você quiser testar ou compartilhar rapidamente um APK com outra pessoa, crie um APK.
A maneira mais fácil de criar um pacote de apps é
usando o Android Studio. No entanto, se você precisar criar um
pacote de apps na linha de comando, use o Gradle ou o
bundletool, conforme descrito nas seções a seguir.
Criar um pacote de apps com o Gradle
Se você preferir gerar um pacote de apps na linha de comando, execute a
tarefa bundleVariant do Gradle no módulo de base do app.
Por exemplo, o comando abaixo cria um pacote de apps para a versão
de depuração do módulo base:
./gradlew :base:bundleDebug
Se você quiser criar um pacote assinado para fazer upload no Play Console, primeiro
configure o arquivo build.gradle.kts do módulo base com as informações de assinatura
do app. Para saber mais, vá para a seção sobre como
Configurar o Gradle para assinar seu app.
Em seguida, você poderá, por exemplo, criar a versão de lançamento do seu app, e o Gradle
gerará automaticamente um pacote de apps e o assinará com as informações de assinatura
fornecidas no arquivo build.gradle.kts.
Se você quiser assinar um pacote de apps como uma etapa separada, use o
jarsigner
para assinar o pacote de apps na linha de comando. O comando para criar um pacote de app é:
jarsigner -keystore pathToKeystore app-release.aab keyAliasCriar um pacote de apps usando o bundletool
O bundletool é uma ferramenta de linha de comando que o Android Studio, o Plug-in do Android
para Gradle e o Google Play usam para converter os recursos
e o código compilados do app em pacotes de apps e gerar APKs implantáveis desses pacotes.
Assim, embora seja útil
testar pacotes de apps com o bundletool e recriar
localmente como o Google Play gera APKs, normalmente você não precisará
invocar bundletool para criar o pacote de apps. Em vez disso,
use tarefas do Android Studio ou Gradle, conforme descrito nas seções anteriores.
No entanto, se você não quiser usar tarefas do Android Studio ou Gradle para criar
pacotes, por exemplo, se usar um conjunto de ferramentas de compilação personalizado, poderá usar bundletool
na linha de comando para criar um pacote de apps a partir dos recursos e
do código pré-compilados. Faça o download do bundletool no repositório do GitHub, caso ainda não tenha feito.
Esta seção descreve como empacotar os recursos e o código compilados do app
e como usar o bundletool na linha de comando para convertê-los em um
Android App Bundle.
Gerar o manifesto e recursos em formato .proto
O bundletool exige que determinadas informações sobre o projeto do seu app, como o manifesto e os recursos do app, estejam no
formato Buffer de protocolo do Google, que também
é conhecido como "protobuf" e usa a extensão de arquivo *.pb. Os protobufs
fornecem um mecanismo de neutralidade de idioma, plataforma neutra e extensível
para a serialização de dados estruturados. Eles são semelhantes ao XML, mas menores, mais rápidos e
mais simples.
Fazer o download do AAPT2
Você pode gerar o arquivo de manifesto e a tabela de recursos do seu app no formato protobuf usando a versão mais recente do AAPT2 do repositório Maven do Google.
Para fazer o download do AAPT2 do repositório Maven do Google, faça o seguinte:
- Navegue até com.android.tools.build > aapt2 no índice do repositório.
- Copie o nome da versão mais recente do AAPT2.
Insira o nome da versão que você copiou no seguinte URL e especifique seu sistema operacional de destino: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/ aapt2-version/aapt2-aapt2-version- [windows | linux | osx].jar
Por exemplo, para fazer o download da versão 3.2.0-alpha18-4804415 para Windows, use: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar
Navegue até o URL em um navegador. O download do AAPT2 é iniciado em seguida.
Descompacte o arquivo JAR que você acabou de transferir.
Compilar e vincular os recursos do seu app
Use o AAPT2 para compilar os recursos do seu app com o seguinte comando:
aapt2 compile \ project_root/module_root/src/main/res/drawable/Image1.png \ project_root/module_root/src/main/res/drawable/Image2.png \ -o compiled_resources/
Durante a fase de vinculação, em que o AAPT2 vincula os vários recursos compilados em um
único APK, instrua o AAPT2 a converter o manifesto e os recursos compilados do app
no formato protobuf incluindo a flag --proto-format, conforme mostrado
no exemplo a seguir:
aapt2 link --proto-format -o output.apk \ -I android_sdk/platforms/android_version/android.jar \ --manifest project_root/module_root/src/main/AndroidManifest.xml \ -R compiled_resources/*.flat \ --auto-add-overlay
Agora, é possível extrair o conteúdo do APK de saída, como o AndroidManifest.xml, resources.pb e outros arquivos de recurso do seu app,
no formato protobuf. Você precisa desses arquivos ao preparar a entrada que o
bundletool exige para criar seu pacote de apps, conforme descrito na seção a seguir.
Código e recursos pré-compilados do pacote
Antes de usar o bundletool para gerar um pacote de apps para seu app, forneça
arquivos ZIP que contenham os recursos e o código compilados para
determinado módulo de app. O conteúdo e a organização do arquivo ZIP de cada módulo é muito
semelhante ao do formato Android App Bundle.
Por exemplo, é necessário criar um arquivo base.zip para o módulo base do seu app e
organizar seu conteúdo da seguinte forma:
| Arquivo ou diretório | Descrição |
|---|---|
manifest/AndroidManifest.xml
|
O manifesto do módulo no formato protobuf. |
dex/...
|
Um diretório com um ou mais arquivos DEX compilados do seu app. Esses arquivos
precisam ser nomeados da seguinte maneira: classes.dex,
classes2.dex, classes3.dex etc.
|
res/...
|
Contém os recursos do módulo no formato protobuf para todas as configurações do dispositivo. Subdiretórios e arquivos precisam ser organizados de forma semelhante a um APK típico. |
root/..., assets/... e lib/...
|
Esses diretórios são idênticos aos descritos na seção sobre o formato Android App Bundle. |
resources.pb
|
A tabela de recursos do app no formato protobuf. |
Depois de preparar os arquivos ZIP para cada módulo do app, você pode transmiti-los
para bundletool a fim de criar seu conjunto de apps, conforme descrito na seção a seguir.
Criar seu pacote de apps usando o bundletool
Para criar o pacote de app, use o comando bundletool build-bundle, como
mostrado no exemplo a seguir:
bundletool build-bundle --modules=base.zip --output=mybundle.aab
A tabela a seguir descreve sinalizações para o comando build-bundle em mais
detalhes.
| Sinalização | Descrição |
|---|---|
--modules=path-to-base.zip, path-to-module2.zip,path-to-module3.zip
|
Especifica a lista de arquivos ZIP do módulo que o bundletool precisa
usar para criar seu pacote de apps.
|
--output=path-to-output.aab
|
Especifica o caminho e o nome do arquivo *.aab de saída.
|
--config=path-to-BundleConfig.json
|
Especifica o caminho para um arquivo de configuração opcional que você pode usar para personalizar o processo de compilação. Para saber mais, consulte a seção sobre como personalizar a geração de APKs descendentes. |
--metadata-file=target-bundle-path:local-file-path
|
Instrui o bundletool a empacotar um arquivo de metadados opcional
dentro do seu pacote de apps. Você pode usar esse arquivo para incluir dados, como os
mapeamentos ProGuard ou a lista completa de arquivos DEX do app, que podem
ser úteis para outras etapas no conjunto de ferramentas ou em uma app store.
A target-bundle-path especifica um caminho relativo à raiz do pacote de apps onde você quer que o arquivo de metadados seja empacotado, e local-file-path especifica o caminho para o próprio arquivo de metadados local. |
Personalizar a geração de APKs descendentes
Os pacotes de apps incluem um arquivo BundleConfig.pb que fornece metadados que as app
stores, como o Google Play, exigem ao gerar APKs do pacote.
Embora o bundletool crie esse arquivo para você, é possível configurar alguns aspectos
dos metadados em um arquivo BundleConfig.json e transmiti-lo ao comando
bundletool build-bundle. Posteriormente, o bundletool converte e combina esse
arquivo com a versão protobuf incluída em cada pacote de apps.
Por exemplo, você pode controlar quais categorias de APKs de configuração serão ativadas ou
desativadas. O exemplo a seguir de um arquivo BundleConfig.json desativa
os APKs de configuração para que cada um seja direcionado a um idioma diferente, isto é,
recursos para todos os idiomas são incluídos nos respectivos APKs de
recurso ou base:
{
"optimizations": {
"splitsConfig": {
"splitDimension": [{
"value": "LANGUAGE",
"negate": true
}]
}
}
}
No arquivo BundleConfig.json, também é possível especificar quais tipos de arquivo não serão
compactados ao empacotar APKs usando
padrões glob, da seguinte forma:
{
"compression": {
"uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
}
}
Por padrão, o bundletool não compacta as bibliotecas nativas
do app (no Android 6.0 ou mais recente) e a tabela de
recursos (resources.arsc). Para uma descrição completa do que pode ser configurado no
BundleConfig.json, inspecione o arquivo bundletool config.proto,
que é escrito usando a sintaxe
Proto3.
Implantar o app em um pacote de apps
Se você criou e assinou um pacote de apps,
use bundletool para gerar APKs e implantá-los em
um dispositivo.
Assinar o app na linha de comando
Não é necessário usar o Android Studio para assinar o app. Você pode fazer isso na
linha de comando, usando apksigner para APKs ou jarsigner para pacotes de app,
ou configurar o Gradle para assinar o app durante o build. De qualquer forma, primeiro você precisa
gerar uma chave privada usando
keytool,
conforme mostrado no exemplo a seguir:
keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias
Este exemplo solicita as senhas do keystore e da chave, além dos
campos "Nome distinto" da chave. Em seguida, ele gera o
keystore como um arquivo chamado my-release-key.jks, salvando-o no
diretório atual (você pode movê-lo para onde quiser). O keystore
contém uma única chave, válida por 10.000 dias.
Agora, você pode assinar o APK ou o pacote de app manualmente ou configurar o Gradle para assinar o app durante o processo de build, conforme descrito nas seções a seguir.
Assinar seu app manualmente na linha de comando
Se quiser assinar um pacote de apps na linha de comando, você poderá usar o
jarsigner.
Se você quiser assinar um APK, use zipalign e apksigner:
Abra uma linha de comando no Android Studio, selecione View > Janelas de ferramentas > Terminal e navegue até o diretório em que o APK não assinado está localizado.
Alinhe o APK não assinado usando
zipalign:zipalign -v -p 4 my-app-unsigned.apk my-app-unsigned-aligned.apk
O
zipaligngarante que todos os dados não compactados comecem com um alinhamento de bytes específico em relação ao início do arquivo, o que pode reduzir a quantidade de RAM consumida por um app.Assine o APK com sua chave privada usando
apksigner:apksigner sign --ks my-release-key.jks --out my-app-release.apk my-app-unsigned-aligned.apk
Este exemplo gera o APK assinado em
my-app-release.apkdepois de assiná-lo com uma chave privada e um certificado armazenados em um único arquivo de keystore:my-release-key.jks.A ferramenta
apksigneré compatível com outras opções de assinatura, incluindo a assinatura de um arquivo APK usando arquivos de chave privada e certificado separados e a assinatura de um APK usando vários signatários. Para mais detalhes, consulte a referência deapksigner.Verifique se o APK está assinado:
apksigner verify my-app-release.apk
Configurar o Gradle para assinar seu app
Abra o arquivo build.gradle.kts no nível do módulo e adicione o
bloco signingConfigs {} com entradas para storeFile,
storePassword, keyAlias e
keyPassword. Depois, transmita esse objeto para a
propriedade signingConfig no seu tipo de build. Exemplo:
Kotlin
android { ... defaultConfig { ... } signingConfigs { create("release") { // You need to specify either an absolute path or include the // keystore file in the same directory as the build.gradle file. storeFile = file("my-release-key.jks") storePassword = "password" keyAlias = "my-alias" keyPassword = "password" } } buildTypes { getByName("release") { signingConfig = signingConfigs.getByName("release") ... } } }
Groovy
android { ... defaultConfig { ... } signingConfigs { release { // You need to specify either an absolute path or include the // keystore file in the same directory as the build.gradle file. storeFile file("my-release-key.jks") storePassword "password" keyAlias "my-alias" keyPassword "password" } } buildTypes { release { signingConfig signingConfigs.release ... } } }
Agora, quando você criar seu app invocando uma tarefa do Gradle, ele assinará o app e executará o zipalign para você.
Além disso, como você configurou o build de lançamento com sua chave de assinatura,
a tarefa "install" (instalar) estará disponível para esse tipo de build. Assim, você pode criar, alinhar,
assinar e instalar o APK da versão final em um emulador ou dispositivo, tudo isso com a
tarefa installRelease.
Um app assinado com sua chave privada está pronto para distribuição, mas primeiro leia mais sobre como publicar seu app e consulte a lista de verificação para publicação no Google Play.