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), sendo acessível pela 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 Windows:
    gradlew task-name
  • No Mac ou Linux:
    ./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 a compilação para Android, leia Configurar sua compilação.

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 compilação disponíveis para todo app Android: uma para depurar o app, a compilação debug (depuração), e outra para disponibilizar o app aos usuários, a compilação release (lançamento). A saída resultante de cada compilação precisa ser assinada com um certificado para que você possa implantar seu app em um dispositivo. A compilação de depuração é assinada 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 a compilação final precisa ser assinada 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 compilação personalizado no arquivo build.gradle e configurá-lo para ser assinado como compilação de depuração incluindo debuggable true. Para saber mais, consulte Configurar variantes de compilação.

Criar e implantar um APK

Ainda que criar 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 uma compilação 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 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 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 uma compilação de depuração, chame 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 compilar o APK e instalá-lo imediatamente em um emulador em execução ou dispositivo conectado, chame installDebug:

gradlew installDebug

A parte "Debug" nos nomes de tarefas acima é apenas uma versão, conhecida como CamelCase, do nome da variante de compilação. Por isso, ela pode ser substituída pelo tipo ou variante de compilação que você quiser montar ou instalar. Por exemplo, se você tiver uma variação de produto "demo", poderá criar a compilação de depuração com a tarefa assembleDemoDebug.

Para ver todas as tarefas de compilação 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.

Compilar um APK de versão final

Quando estiver tudo pronto para lançar e distribuir o app, crie um APK de versão final assinado com sua chave privada. Para 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ê pode 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 para desenvolvedores (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 Settings > Developer options.

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 Settings > About phone e toque em Build number 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 no Play Console, será necessário configurar primeiro o arquivo build.gradle 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 do seu app, e o Gradle gerará automaticamente um pacote de apps e vai assiná-lo com as informações de assinatura fornecidas no arquivo build.gradle.

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.

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 será iniciado em breve.

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

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

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

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 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. O bundletool posteriormente 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 segmente um idioma diferente (isto é, recursos para todos os idiomas são incluídos nos respectivos APKs de recurso base ou dinâmico):

{
      "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 do seu app (no Android 6.0 ou versão mais recente) e a tabela de recursos (resources.arsc). Para 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. É possível assinar o app pela linha de comando, usando apksigner para APKs ou jarsigner para pacotes de apps ou configurando o Gradle para assiná-lo durante a compilaçã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 (é possível movimentá-lo como 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ê pode 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
        

    Este 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 oferece 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 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 compilação. Exemplo:

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 a compilação de lançamento com sua chave de assinatura, a tarefa "install" (instalar) estará disponível para esse tipo de compilação. Assim, você pode compilar, 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.