Criar seu app na linha de comando

É 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-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 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:

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

  2. 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 targetSdkVersion for 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 <var>path/to/your_app</var>.apk
    

    Todos 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 keyAlias

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.

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.

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:

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

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

  3. 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.apk depois 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 de apksigner.

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

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.