Criar seu app na linha de comando

projeto Android usando a ferramenta de linha de comando do wrapper Gradle.

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 um script de shell para Linux e Mac (gradlew.sh) e pode ser acessada pela raiz de cada projeto que você criar 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 mais informações 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ê pode executar seus apps rapidamente em um emulador ou em um dispositivo conectado criando um APK de depuração.

Você também pode definir um tipo de compilação personalizada no seu arquivo build.gradle e configurá-lo para ser assinado como uma compilação de depuração, incluindo o debuggable true. Para saber mais, leia 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 o teste e a depuração imediatos do app, 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 a depuração por meio do 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, invoque a tarefa assembleDebug:

    gradlew assembleDebug
    

Isso cria 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 imediatamente em um dispositivo.

Ou, 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 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 e 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 para android_sdk/tools/ e inicie o emulador especificando seu AVD:

    emulator -avd avd_name

    Se você não tiver certeza do 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ê criar serão salvos em project_name/module_name/build/outputs/apk/.

Para saber mais, leia Executar aplicativos 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 Config. > 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 Config. > 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ê criar serão salvos em project_name/module_name/build/outputs/apk/.

Para saber mais, consulte Executar aplicativos 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, poderá fazer isso usando o Gradle ou o 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 a seguir 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, primeiro configure o arquivo build.gradle do módulo base com as informações de assinatura do app. Para saber mais, acesse a seção sobre como Configurar o Gradle para assinar seu app. Então, você poderá, por exemplo, criar a versão final 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.

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

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

Depois, é possível extrair o conteúdo do APK de saída, como o AndroidManifest.xml, resources.pb e outros arquivos de recursos do seu app, agora 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, primeiro 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, crie um arquivo base.zip para o módulo base do seu app e organize o conteúdo da seguinte maneira:

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 o arquivo ZIP para cada módulo do app, você pode passá-lo para o bundletool para criar o pacote 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 as 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 de arquivo para o 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 mescla 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 quais 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 app (no Android 6.0 ou posteriores) e a tabela de recursos (resources.arsc). Para conseguir uma descrição completa do que você pode configurar no seu BundleConfig.json, inspecione o arquivo bundletool config.proto (link em inglês), que é escrito usando a sintaxe Proto3.

Implantar o app em um pacote de apps

Se você criou e assinou um pacote de apps, use o bundletool para gerar APKs e implantá-los em um dispositivo.

Assinar o app na linha de comando

O Android Studio não é necessário para assinar o app. Você pode assinar seu app na linha de comando usando o apksigner para APKs ou o jarsigner para pacotes de apps, ou configurar o Gradle para assiná-lo para você 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 (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ê pode usar jarsigner. Se, em vez disso, você quiser assinar um APK, precisará 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 exibe o APK assinado em my-app-release.apk após assiná-lo com uma chave privada e um certificado armazenados em um único arquivo keystore: my-release-key.jks.

    A ferramenta apksigner oferece outras opções de assinatura, inclusive a de um arquivo APK usando arquivos separados de chave privada e arquivos de certificado e a assinatura de um APK usando vários assinantes. Para mais detalhes, consulte a referência do apksigner.

    Observação: para usar a ferramenta apksigner você precisa ter a revisão 24.0.3 ou posterior da 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 e, em seguida, passe 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.