Criar seu app na linha de comando

Você pode executar todas as tarefas de compilação disponíveis para seu projeto Android usando a ferramenta de linha de comando do wrapper Gradle (link em inglês). Ela está disponível como um arquivo de lote para Windows (gradlew.bat) e como um script de shell para Linux e Mac (gradlew.sh), e pode ser acessada 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-name

• No 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 o app com o wrapper Gradle. Para saber mais sobre como configurar seu build para Android, leia Configurar seu build.

Se preferir usar as ferramentas do Android Studio em vez das ferramentas da linha de comando, leia Criar e executar seu app.

Sobre tipos de compilação

Por padrão, há dois tipos de build disponíveis para todo app Android: um para depurar o app, o build de depuração, e outro para disponibilizar o app aos usuários, o build de lançamento. A saída resultante de cada build precisa ser assinada com um certificado para que você possa implantar seu app em um dispositivo. O build de depuração é assinado automaticamente com uma chave de depuração fornecida pelas ferramentas do SDK (esse método não é seguro e, por isso, não pode ser usado para publicar na Google Play Store), e o build de lançamento precisa ser assinado com sua própria chave privada.

Se você quiser criar o app para lançamento, é importante que também assine o app com a chave de assinatura apropriada. Se ainda não tiver muita experiência nisso, você poderá executar seus apps rapidamente em um emulador ou em um 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 compilação.

Criar e implantar um APK

Ainda que a criação de um pacote de apps seja a melhor forma de empacotar seu app e fazer upload dele para o Play Console, é mais indicado criar um APK para testar rapidamente um build de depuração ou para compartilhar seu app como um artefato implantável.

Compilar um APK de depuração

Para testar e depurar o app de forma imediata, você pode criar um APK de depuração. O APK de depuração é assinado com uma chave de depuração fornecida pelas ferramentas do SDK e permite depuração com 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 então, se quiser 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 de tarefas acima é apenas uma versão, conhecida como CamelCase, do nome da variante de build. Por isso, ela poderá ser substituída pelo tipo ou variante de build que você quiser 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:

1. Em uma linha de comando, navegue até android_sdk/tools/ e inicie o emulador especificando o AVD:

   emulator -avd avd_name

   Se não tiver certeza de qual é o nome do AVD, execute emulator -list-avds.

2. Agora você poderá instalar seu 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 usando um SDK de visualização do desenvolvedor (caso o targetSdkVersion seja uma letra em vez de um número), você precisará incluir a opção -t com o comando install para instalar um APK de teste.

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

Observação: no Android 4.2 e em versões mais recentes, as Opções do desenvolvedor ficam ocultas por padrão. Para torná-las disponíveis, acesse Configurações > Sobre o dispositivo e toque em Número da versão sete vezes. Retorne à tela anterior para encontrar as Opções do desenvolvedor.

Depois que o dispositivo estiver configurado e conectado via USB, você poderá instalar seu 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 apps

Os Android App Bundles incluem todos os recursos e o código compilados do seu app, mas permitem 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 a partir da linha de comando, use o Gradle ou bundletool, conforme descrito nas seções abaixo.

Criar um pacote de apps com o Gradle

Se você preferir gerar um pacote de apps a partir da linha de comando, execute a tarefa do Gradle bundleVariant no módulo base do seu 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 para o Play Console, será necessário configurar primeiro 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 keyAlias

Observação: não é possível usar o apksigner para assinar o pacote de apps.

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

Cuidado: não use a versão do AAPT2 incluída no pacote de ferramentas de desenvolvimento do Android. Essa versão do AAPT2 não é compatível com bundletool.

Para fazer o download do AAPT2 do repositório Maven do Google, faça o seguinte:

1. Navegue até com.android.tools.build > aapt2 no índice do repositório.
2. Copie o nome da versão mais recente do AAPT2.

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

4. Navegue até o URL em um navegador. O download do AAPT2 é iniciado em seguida.

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

Observação: embora seja possível transmitir diretórios de recursos para o AAPT2 usando a flag --dir, isso recompila todos os arquivos no diretório, independentemente de quantos arquivos realmente foram alterados.

Durante a fase de vinculação, em que AAPT2 vincula seus diversos recursos compilados em um único APK, instrua o AAPT2 a converter o manifesto e os recursos compilados do seu app no formato protobuf incluindo a sinalização --proto-format, conforme mostrado abaixo:

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

Observação: como alternativa, ao especificar recursos compilados com a flag -R, você pode especificar um arquivo de texto que inclua o caminho absoluto para cada um dos seus recursos compilados, com cada caminho separado por um único espaço. Em seguida, você pode transmitir esse arquivo de texto para AAPT2 da seguinte maneira: aapt2 link ... -R @compiled_resources.txt.

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 seu pacote de apps, use o comando bundletool build-bundle, conforme mostrado abaixo.

bundletool build-bundle --modules=base.zip --output=mybundle.aab

Observação: se você pretende publicar o pacote de apps, é necessário assiná-lo usando jarsigner. Não é possível usar o apksigner para assinar o pacote de apps.

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 de saída *.aab.
--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.

Observação: para saber mais sobre como o JSON mapeia para o formato protobuf, leia Mapeamento do JSON. No entanto, essa informação é mais avançada do que o necessário para esta página.

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 seu arquivo BundleConfig.json, também é possível especificar que tipos de arquivos ficarão descompactados ao empacotar APKs usando padrões glob, da seguinte maneira:

{
  "compression": {
    "uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
  }
}

Lembre-se de que, por padrão, bundletool não compacta as bibliotecas nativas (no Android 6.0 ou versão mais recente) e a tabela de recursos (resources.arsc) do seu app. Para ver uma descrição completa do que pode ser configurado em BundleConfig.json, inspecione o arquivo bundletoolconfig.proto , que é gravado 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

Você não precisa do Android Studio para assinar seu app. Você pode assiná-lo pela linha de comando, usando apksigner para APKs ou jarsigner para pacotes de apps ou configurando o Gradle para assiná-lo durante a criação. De qualquer maneira, primeiro é necessário gerar uma chave privada usando keytool, conforme mostrado abaixo.

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias

O exemplo acima solicita senhas para o keystore e a chave e para os campos "Nome distinto" da sua 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 pacote de apps manualmente ou configurar o Gradle para assinar seu app durante o processo de compilação, conforme descrito nas seções abaixo.

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 em vez disso, será necessário usar zipalign e apksigner, conforme descrito abaixo.

1. Abra uma linha de comando no Android Studio, selecionando View > Tool Windows > Terminal e indo até o diretório onde o APK não assinado está localizado.

2. Alinhe o APK não assinado usando zipalign:

   zipalign -v -p 4 my-app-unsigned.apk my-app-unsigned-aligned.apk
   

   O zipalign garante que todos os dados descompactados comecem com um alinhamento de byte específico em relação ao início do arquivo, o que pode reduzir a quantidade de RAM consumida pelo app.

3. Assine o APK com a chave privada usando apksigner:

   apksigner sign --ks my-release-key.jks --out my-app-release.apk my-app-unsigned-aligned.apk
   

   Esse exemplo tem como saída o APK assinado em my-app-release.apk após 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, inclusive a de um arquivo APK usando arquivos diferentes de chave privada e de certificado e a assinatura de um APK usando vários assinantes. Para ver mais detalhes, consulte a referência apksigner.

   Observação: para usar a ferramenta apksigner, é necessário ter a revisão 24.0.3 ou versão mais recente do Android SDK Build Tools instalada. Atualize esse pacote usando o SDK Manager.

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

Observação: nesse caso, o keystore e a senha da chave ficam visíveis diretamente no arquivo build.gradle. Para melhorar a segurança, remova as informações de assinatura do arquivo de compilação.

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 antes é importante que você leia mais sobre como publicar o app e analise a Lista de verificação de lançamento do Google Play.