Criar e executar o app

Para conferir a aparência e o comportamento do seu app em um dispositivo, crie e faça a execução dele. O Android Studio configura novos projetos para que você possa implantar o app em um dispositivo virtual ou físico com apenas alguns cliques.

Esta visão geral foca no uso do Android Studio para criar e executar seu app para testes e depuração. Se quiser mais informações sobre como usar o Android Studio para criar o app de forma que ele possa ser lançado para os usuários, consulte Criar o app para lançamento aos usuários. Para informações mais detalhadas sobre como gerenciar e personalizar seu build, com ou sem o Android Studio, consulte Configurar seu build.

Criação e execução básicas

Para criar e executar seu app, siga estas etapas:

1. Na barra de ferramentas, selecione seu app no menu de configurações de execução.

2. No menu de dispositivo de destino, selecione onde você quer executar o app.

   

   Se você não tiver nenhum dispositivo configurado, será necessário criar um Dispositivo virtual Android para usar o Android Emulator ou conectar um dispositivo físico.

3. Clique em Run .

O Android Studio vai informar se você tentar iniciar o projeto em um dispositivo que tem um erro ou aviso associado. A iconografia e as mudanças estilísticas diferenciam entre erros, que são seleções de dispositivos que resultam em uma configuração corrompida, e avisos, que são seleções de dispositivos que podem resultar em comportamentos inesperados, mas ainda são executáveis.

Monitorar o processo de build

Para ver detalhes sobre o processo de build, selecione View > Tool Windows > Build ou clique em Build na barra da janela de ferramentas. A janela de ferramentas Build exibe as tarefas que o Gradle executa para criar seu app, conforme mostrado na Figura 1.

1. Guia Sync: exibe as tarefas que o Gradle executa para sincronizar com os arquivos de projeto. Assim como na guia Build Output, se você encontrar um erro de sincronização, selecione elementos na árvore para conferir mais informações sobre ele. Também mostra um resumo do impacto do download para determinar se os downloads de dependência estão afetando negativamente seu build.
2. Guia Build Output: mostra as tarefas que o Gradle executa como uma árvore, onde cada nó representa uma fase de build ou um grupo de dependências de tarefas. Se você receber erros de tempo de build ou de tempo de criação, inspecione a árvore e selecione um elemento para ler a saída do erro, como mostrado na Figura 2.

   

3. Guia Build Analyzer: oferece informações sobre análise de desempenho do build. Consulte Resolver problemas de desempenho do build com o Build Analyzer para saber mais.
4. Restart: executa a última ação da versão novamente. Se o último comando que você executou foi Build > Make Selected Module, o módulo atual será criado. Se o último comando que você executou foi Build > Make Project, ele vai gerar arquivos de build intermediários para todos os módulos do projeto.
5. Filtros: filtra alertas, tarefas ou ambos que foram concluídos com êxito. Isso pode facilitar a localização de problemas na saída.

Caso suas variantes de build usem variações de produto, o Gradle também invoca tarefas para criar essas variações. Para ver a lista de todas as tarefas de build disponíveis, clique em View > Tool Windows > Gradle ou em Gradle na barra da janela de ferramentas.

Se um erro ocorre durante o processo de build, o Gradle pode recomendar opções de linha de comando para resolver o problema, como --stacktrace ou --debug. Para usar opções de linha de comando com seu processo de compilação:

1. Abra a caixa de diálogo Settings ou Preferences:
   • No Windows ou no Linux, selecione File > Settings na barra de menus.
   • No macOS, selecione Android Studio > Preferences na barra de menus.
2. Navegue para Build, Execution, Deployment > Compiler.
3. No campo de texto ao lado de Command-line Options, insira suas opções de linha de comando.
4. Clique em OK para salvar e sair.

O Gradle vai aplicar essas opções de linha de comando na próxima vez que você tentar criar o app.

Recursos avançados de build e execução

A maneira padrão de criar e executar o app no Android Studio deve ser suficiente para testar um app simples. No entanto, é possível usar estes recursos de build e execução para casos mais avançados:

• Para implantar o app no modo de depuração, clique em Debug . Executar o app no modo de depuração permite que você defina pontos de interrupção no código, examine variáveis e avalie expressões no momento da execução, além de executar ferramentas de depuração. Para saber mais, consulte Depurar o app.

• Se você tiver um app maior e mais complexo, use o recurso "Aplicar mudanças" em vez de clicar em Run . Isso economiza tempo, porque você evita ter que reiniciar o app sempre que quiser implantar uma mudança. Para saber mais, consulte a seção Implantar de forma incremental com o recurso "Aplicar mudanças".

• Se você está usando o Jetpack Compose, a Edição em tempo real é um recurso experimental que permite atualizar elementos combináveis sem clicar novamente em Run . Com isso, você pode se concentrar em programar o código da interface com o mínimo de interrupção. Para saber mais, consulte a seção Edição em tempo real (experimental).

• Se você tiver um app com diversas variantes de build ou versões, poderá escolher qual variante de build implantar usando a janela de ferramentas Build Variants. Para saber mais sobre como executar uma variante de build específica, consulte a seção Mudar a variante de build.

• Para ajustar as opções de instalação, inicialização e teste de apps, mude a configuração de execução/depuração. Para saber mais sobre como criar configurações personalizadas de execução/depuração, consulte Criar configurações de execução/depuração.

• Recomendamos que você use o Android Studio para suas necessidades de desenvolvimento, mas também é possível implantar o app em um dispositivo virtual ou físico usando a linha de comando. Para mais informações, consulte Criar seu app na linha de comando.

Implantar de forma incremental com o recurso "Aplicar mudanças"

No Android Studio 3.5 e mais recentes, o recurso Aplicar mudanças permite enviar mudanças de código e recursos ao app em execução sem que ele precise ser reiniciado e, em alguns casos, sem reiniciar a atividade atual. Essa flexibilidade ajuda a controlar quanto do seu app é reiniciado quando você quer implantar e testar mudanças pequenas e incrementais preservando o estado atual do dispositivo.

A opção "Aplicar mudanças" usa recursos na implementação da JVMTI para Android que têm suporte em dispositivos com o Android 8.0 (nível 26 da API) ou versões mais recentes. Para saber mais sobre como "Aplicar mudanças" funciona, consulte a página Project Marble do Android Studio: Aplicar mudanças (links em inglês).

Requisitos

As ações em "Apply Changes" só estarão disponíveis quando você atender às seguintes condições:

• Criar o APK do seu app usando uma variante de build de depuração.
• Implementar seu app em um dispositivo ou emulador de destino que execute o Android 8.0 (API de nível 26) ou versões mais recentes.

Usar o recurso "Apply Changes"

Use as opções a seguir quando quiser implantar as mudanças em um dispositivo compatível:

Apply Changes and Restart Activity : tenta aplicar suas mudanças no código e em recursos reiniciando a atividade, mas sem reiniciar o app. Geralmente, é possível usar essa opção quando você modificou o código no corpo de um método ou modificou um recurso.

Você também pode realizar essa ação pressionando Ctrl + Alt + F10 (Ctrl + Command + Shift + R no macOS).

Apply Code Changes : tenta aplicar apenas as mudanças no código sem reiniciar nada. Geralmente, é possível usar essa opção quando você modificou o código no corpo de um método, mas não modificou nenhum recurso. Se você tiver modificado o código e os recursos, use Apply Changes and Restart Activity.

Você também pode realizar essa ação pressionando Ctrl + F10 (Ctrl + Command + R no macOS).

Run : implanta todas as mudanças e reinicia o app. Use essa opção quando as modificações não puderem ser aplicadas usando alguma das opções de "Aplicar mudanças". Para saber mais sobre os tipos de mudança que exigem a reinicialização do app, consulte Limitações do recurso "Aplicar mudanças".

Ativar substituto de execução para o recurso "Aplicar mudanças"

Quando você clica em Apply Changes and Restart Activity ou Apply Code Changes, o Android Studio cria um APK e determina se as mudanças podem ser aplicadas. Se elas não puderem e causarem uma falha do recurso "Aplicar mudanças", o Android Studio pedirá que você use a opção Run no app novamente.

Se você não quiser receber um aviso sempre que isso ocorrer, configure o Android Studio para executar o app de novo automaticamente quando as mudanças não puderem ser aplicadas. Para ativar esse comportamento, siga estas etapas:

1. Abra a caixa de diálogo Settings ou Preferences:

   • No Windows ou no Linux, selecione File > Settings na barra de menus.
   • No macOS, selecione Android Studio > Preferences na barra de menus.

2. Navegue até Build, Execution, Deployment > Deployment.

3. Marque as caixas de seleção para ativar o substituto de execução automática para uma ou ambas as ações de "Aplicar mudanças".

4. Clique em OK.

Mudanças dependentes da plataforma

Alguns recursos de "Apply Changes" dependem de versões específicas da plataforma Android. Para aplicar esses tipos de mudanças, seu app precisa ser implantado em um dispositivo com essa versão do Android ou mais recente. Por exemplo, a adição de um método exige o Android 11 ou uma versão mais recente.

Limitações do recurso Aplicar mudanças

O recurso "Aplicar mudanças" foi criado para acelerar o processo de implantação do app. No entanto, existem algumas limitações de uso.

Mudanças no código que exigem a reinicialização do app

Algumas mudanças de código e recursos não podem ser aplicadas até que o app seja reiniciado, incluindo estas:

• Como adicionar ou remover um campo
• Como remover um método
• Mudar assinaturas de método
• Mudar modificadores de métodos ou classes
• Mudar herança da classe
• Modificar valores em enumerações.
• Adicionar ou remover um recurso
• Modificar o manifesto do app.
• Modificar bibliotecas nativas (arquivos do SO).

Bibliotecas e plug-ins

Alguns plug-ins e bibliotecas fazem modificações automaticamente nos arquivos de manifesto do app ou em recursos referenciados no manifesto. Essas atualizações automáticas podem interferir em Aplicar mudanças das seguintes maneiras:

• Se uma biblioteca ou um plug-in fizer mudanças no manifesto do app, não vai ser possível usar o recurso Aplicar mudanças. É necessário reiniciar o app para conferir as mudanças.
• Se uma biblioteca ou um plug-in fizer mudanças nos arquivos de recursos do app, não será possível usar Apply Code Changes . Use Apply Changes and Restart Activity ou reinicie o app para conferir as mudanças.

Para evitar essas limitações, desative todas as atualizações automáticas das variantes de build de depuração.

Por exemplo, o Firebase Crashlytics atualiza recursos de apps com um ID de build exclusivo durante cada criação, o que impede o uso de Apply Code Changes e exige que você reinicie a atividade do app para conferir as mudanças. Desative esse comportamento para usar Apply Code Changes com o Crashlytics nos seus builds de depuração.

Código que faz referência direta ao conteúdo em um APK instalado

Caso seu código faça referência direta ao conteúdo do APK do app instalado no dispositivo, esse código poderá causar falhas ou comportamento indevido após clicar em Apply Code Changes . Isso ocorre porque, quando você clica em Apply Code Changes, o APK no dispositivo é substituído durante a instalação. Nesses casos, você pode clicar em Apply Changes and Restart Activity ou em Run .

Se você encontrar problemas durante o uso do recurso "Aplicar mudanças", informe um bug.

Edição em tempo real

A "Edição em tempo real" é um recurso experimental do Android Studio que permite atualizar elementos combináveis em emuladores e dispositivos físicos em tempo real. Essa funcionalidade minimiza as mudanças de contexto entre a programação de código e o processo de build do app, permitindo que você se concentre na primeira por mais tempo e sem interrupções.

Saiba mais sobre a "Edição em tempo real"

Mudar a variante de build

Quando você clica em Run , o Android Studio cria a versão de depuração do app por padrão, destinada ao uso apenas durante o desenvolvimento.

Para mudar a variante de build que o Android Studio usa, siga um destes procedimentos:

• Selecione Build > Select Build Variant no menu.
• Selecione View > Tool Windows > Build Variants no menu.
• Clique na guia Build Variants na barra da janela de ferramentas.

Para projetos sem código nativo/C++, o painel Build Variants tem duas colunas: Module e Active Build Variant. O valor Active Build Variant do módulo determina qual variante de build o ambiente de desenvolvimento integrado vai implantar no dispositivo conectado e que vai ficar visível no editor.

Figura 9. O painel Build Variants tem duas colunas para projetos que não têm código nativo/C++.

Para alternar entre variantes, clique na célula Active Build Variant de um módulo e escolha a variante desejada no campo de lista.

Para projetos com código nativo/C++, o painel Build Variants tem três colunas:

• Module
• Variante de build ativo
• ABI ativa

O valor da Active Build Variant para o módulo determina a variante de build que o ambiente de desenvolvimento integrado implanta no seu dispositivo e que fica visível no editor. Para módulos nativos, o valor de Active ABI determina a ABI que o editor usa, mas não afeta o que é implantado.

Figura 10. O painel Build Variants adiciona a coluna Active ABI para projetos com código nativo/C++.

Para mudar a variante de build ou ABI, clique na célula da coluna Active Build Variant ou Active ABI e escolha a variante ou ABI desejada na lista. Depois que você mudar a seleção, o ambiente de desenvolvimento integrado vai sincronizar seu projeto automaticamente. Modificar uma coluna para um módulo de app ou de biblioteca aplica a mudança a todas as linhas dependentes.

Por padrão, os novos projetos são configurados com duas variantes de build: depuração e lançamento. Você precisa criar a variante de lançamento para preparar seu app para o lançamento público. Se quiser definir outras variações do app com diferentes recursos ou requisitos de dispositivo, você pode definir mais variantes de build.

Conflitos na caixa de diálogo "Build Variants" do Android Studio

Na caixa de diálogo Build Variants do Android Studio, você pode ver mensagens de erro indicando os conflitos entre variantes de build, como no exemplo a seguir:

Esse erro não indica um problema de build com o Gradle, mas sim que o ambiente de desenvolvimento integrado do Android Studio não pode resolver símbolos entre as variantes dos módulos selecionados.

Por exemplo, se você tem um módulo M1 que depende da variante v1 do módulo M2, mas a M2 tem a variante v2 selecionada no ambiente de desenvolvimento integrado, então você tem símbolos não resolvidos nesse ambiente. Imagine que o M1 depende de uma classe disponível apenas na v1. Quando a v2 for selecionada, essa classe não será conhecida pelo ambiente de desenvolvimento integrado. Portanto, ele não vai resolver o nome da classe, mostrando erros no código do módulo M1.

Essas mensagens de erro aparecem porque o ambiente de desenvolvimento integrado não consegue carregar código para diversas variantes simultaneamente. No entanto, em termos de build do app, a variante selecionada nessa caixa de diálogo não tem efeito, porque o Gradle cria seu app com o código-fonte especificado nos roteiros de build do Gradle, e não com base no que está carregado no ambiente de desenvolvimento integrado no momento.

Mudar a configuração de execução/depuração

Quando você executa o app pela primeira vez, o Android Studio usa uma configuração de execução padrão. Ela especifica se o app será implantado usando um APK ou um Android App Bundle, assim como o módulo executado, o pacote implantado, a atividade iniciada, o dispositivo de destino, as configurações do emulador, as opções do Logcat e muito mais.

A configuração padrão de execução/depuração cria um APK, inicia a atividade de projeto padrão e usa a caixa de diálogo Select Deployment Target para seleção do dispositivo de destino. Caso as configurações padrão não sejam adequadas ao seu projeto ou módulo, personalize as configurações de execução/depuração ou crie as suas nos níveis do projeto, padrão e módulo.

Para editar uma configuração de execução/depuração, selecione Run > Edit Configurations. Se quiser mais informações, consulte Criar e editar configurações de execução/depuração.