Criar e executar o app

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

Essa visão geral se concentra em usar o Android Studio para criar e executar o app para testes e depuração. Para saber mais sobre como usar o Android Studio para criar o app de forma que ele possa ser liberado para os usuários, consulte Criar o app para lançamento aos usuários. Para ver mais informações 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 destino, selecione o dispositivo em que você quer executar o app.

   

   Caso você não tenha nenhum dispositivo configurado, vai 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 mais informações sobre ele.
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 performance do build com o Build Analyzer para saber mais.
4. Restart: executa a mesma ação que selecionar Build > Make Project, gerando arquivos intermediários de build 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 precisa ser suficiente para testar um app simples. No entanto, é possível usar esses recursos de build e execução para casos de uso 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 seu 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 reiniciar o app sempre que quiser implantar uma mudança. Para saber mais sobre Aplicar mudanças, consulte a seção Implantar incrementalmente com o recurso Aplicar mudanças.

• Se você estiver usando o Jetpack Compose, a Edição em tempo real é um recurso experimental que permite atualizar elementos combináveis em tempo real sem clicar novamente em Run . Isso permite que você se concentre em programar o código da IU 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, vai 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 a criação de configurações personalizadas de execução/depuração, consulte a seção 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 saber mais, consulte Criar o app na linha de comando.

Implantar de forma incremental com o recurso "Apply Changes"

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 pequenas mudanças incrementais preservando o estado atual do dispositivo.

O recurso Aplicar mudanças usa recursos na implementação da JVMTI para Android com suporte em dispositivos que executam o Android 8.0 (API de nível 26) ou mais recentes. Para saber mais sobre como a opção Aplicar mudanças funciona, consulte Project Marble do Android Studio: Aplicar mudanças (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 seus recursos e mudanças no código 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 um recurso existente.

Você também pode realizar essa ação pressionando Ctrl + Alt + F10 (Control + 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 (Control + 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 qualquer uma das opções de Aplicar mudanças. Para saber mais sobre os tipos de modificação 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 novo APK e determina se as mudanças podem ser aplicadas. Se elas não puderem por possibilidade de falha do recurso Aplicar mudanças, o Android Studio vai pedir que você execute 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 modificações 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.

Modificações no código que exigem 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 recurso do app, não vai 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 build, 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 . Esse comportamento ocorre porque, quando você clica em Apply Code Changes, o APK subjacente no dispositivo é substituído durante a instalação. Nesses casos, você pode clicar em Apply Changes and Restart Activity ou Run .

Se você encontrar problemas durante o uso de Aplicar mudanças, informe um bug (em inglês).

Edição em tempo real (experimental)

A Edição em tempo real é um recurso experimental nas versões canário do Android Studio Giraffe. Ela 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 programação por mais tempo, sem interrupções.

A Edição em tempo real tem dois modos:

• Manual: as mudanças de código são aplicadas quando são salvas manualmente usando Ctrl + S (Command + S para macOS).
• Automático. As mudanças são aplicadas no dispositivo ou emulador quando você atualiza uma função combinável.

O recurso Edição em tempo real se concentra em mudanças no código relacionadas a IU e UX. Ele não oferece suporte a mudanças como atualizações de assinatura de método, adição de novos métodos ou mudanças na hierarquia de classes. Para saber mais, consulte a lista de Limitações do recurso Edição em tempo real.

Esse recurso não substitui a criação e execução do app ou o recurso Aplicar mudanças. Em vez disso, ele foi projetado para otimizar o fluxo de trabalho durante a criação, implantação e iteração para desenvolver a IU do Compose.

Confira as práticas recomendadas de fluxo de trabalho:

1. Configure o aplicativo para que ele possa ser executado.
2. Use a Edição em tempo real o máximo possível, até que seja necessário fazer uma mudança sem suporte desse recurso. Por exemplo: adicionar novos métodos enquanto o app estiver em execução.
3. Depois de fazer uma mudança sem suporte, clique em Run para reiniciar o app e retomar a Edição em tempo real.

Figura 3. No modo automático, cada vez que você faz uma edição com suporte da Edição em tempo real, o app em execução no dispositivo ou emulador é atualizado imediatamente.

Como usar o recurso Edição em tempo real

Siga estas etapas para criar uma atividade vazia do Compose, ativar o recurso Edição em tempo real no projeto e fazer mudanças.

Configurar o novo projeto

1. Antes de começar, confira se você tem a versão canário mais recente do Android Studio Giraffe e se o nível da API do dispositivo ou emulador físico é de pelo menos 30.

2. Abra o Android Studio e selecione New Project no pop-up Welcome to Android Studio. Se você já tem um projeto aberto, pode criar um novo em File > New > New Project.

3. Escolha o modelo Empty Compose Activity para Phone and Tablet e clique em Next.

   Figura 4. Modelos disponíveis. Para usar a Edição em tempo real, escolha Empty Compose Activity.

4. Preencha a caixa de diálogo New Project com as informações necessárias: nome, nome do pacote, local para salvar, idioma (definido como Kotlin) e o SDK mínimo.

   Figura 5. Exemplo de configurações do projeto.

5. Clique em Finish.

Ativar o recurso Edição em tempo real

1. Acesse as configurações para ativar a Edição em tempo real.

   • No Windows ou no Linux, acesse File > Settings > Editor > Live Edit.
   • No macOS, acesse Android Studio > Preferences > Editor > Live Edit.

2. Selecione a opção Live Edit e o modo que você quer executar nas configurações.

   No modo manual, as mudanças de código são aplicadas sempre que você salva manualmente usando Ctrl + S (Command + S no macOS). No modo automático, as mudanças de código são aplicadas no dispositivo ou emulador conforme você faz as mudanças.

   Figura 6. Configurações da Edição em tempo real.

3. No editor, abra o arquivo MainActivity, que é o ponto de entrada do app.

4. Clique em Run para implantar o app e depois em Split, no canto direito de cima do editor, para abrir a visualização.

5. Depois de ativar a Edição em tempo real, a marca de seleção verde em Live Edit vai aparecer no canto superior direito do editor:

   

Fazer e revisar mudanças

Quando você faz mudanças com suporte no editor, a atualização de teste é feita automaticamente.

Por exemplo, edite o método Greeting existente em MainActivity para o seguinte:

@Composable
fun Greeting(name: String) {
    Text(text = "Hello $name!",
        Modifier.padding(80.dp) // Outer padding; outside background
            .background(color = Color.Cyan) // Solid element background color
            .padding(16.dp) // Inner padding; inside background, around text)
    )
}

As mudanças feitas aparecem instantaneamente na visualização, como mostrado na Figura 7.

Figura 7. Visualização mostrando a Edição em tempo real do método Greeting.

Resolver problemas do recurso Edição em tempo real

Se as mudanças não aparecerem no painel de visualização, é possível que o Android Studio não tenha atualizado as edições. Verifique se o indicador da IU Edição em tempo real mostra um ícone pausado, como mostrado na Figura 8, que indica um erro de compilação. Para saber mais sobre o erro e ver sugestões para resolvê-lo, clique no indicador.

Figura 8. Indicador de status do recurso Edição em tempo real.

Limitações do recurso Edição em tempo real

Veja abaixo uma lista das limitações atuais.

• É necessário usar a Edição em tempo real com o Compose 1.3.0 ou mais recente. Se o projeto usar uma versão mais antiga do Compose, a Edição em tempo real será desativada.
• O recurso de Edição em tempo real requer um dispositivo físico ou emulador com o nível 30 da API ou mais recente.
• A Edição em tempo real só oferece suporte à edição de um corpo de função, ou seja, não é possível mudar o nome ou a assinatura da função, adicionar ou remover uma função ou mudar campos que não sejam de função.
• As classes modificadas na Edição em tempo real podem ter problemas de performance. Execute o app e use um build de lançamento limpo se estiver avaliando a performance dele.
• Faça uma execução completa para que o depurador funcione nas classes que você modificou com a Edição em tempo real.
• Um app em execução pode falhar quando você usa a Edição em tempo real. Se isso acontecer, você pode reimplantar o app com o botão Run .
• A Edição em tempo real não faz nenhuma manipulação de bytecode definida no arquivo de build do projeto. Por exemplo, as manipulações de bytecode que seriam aplicadas na criação do projeto usando as opções no menu Build ou clicando nos botões Build ou Run.
• As funções não combináveis são atualizadas em tempo real no dispositivo ou emulador, e uma recomposição completa é acionada. A recomposição completa pode não invocar a função atualizada. Para funções não combináveis, é necessário acionar as funções recém-atualizadas ou executar o app novamente.
• A Edição em tempo real não é retomada após a reinicialização do app. Execute o app novamente.
• A Edição em tempo real só oferece suporte a processos depuráveis.
• A Edição em tempo real não oferece suporte a projetos que usam valores personalizados para moduleName em kotlinOptions na configuração do build.
• A Edição em tempo real não funciona com implantações múltiplas. Isso significa que não é possível implantar em um dispositivo e depois em outro. A Edição em tempo real só fica ativa no último conjunto de dispositivos em que o app foi implantado.
• A Edição em tempo real funciona com implantações em vários dispositivos que foram criados com a opção Select multiple devices no menu suspenso do dispositivo de destino. No entanto, ela não tem suporte oficial e pode apresentar problemas. Se você tiver algum problema, informe aqui.

Perguntas frequentes sobre o recurso de Edição em tempo real

• Qual é o status atual da Edição em tempo real?
  • A Edição em tempo real está disponível no canal canário do Android Studio Giraffe como um recurso experimental. Para ativar ou desativar esse recurso, acesse File > Settings > Editor > Live Edit (Android Studio > Preferences > Editor > Live Edit no macOS).
• Quando posso usar a Edição em tempo real?
  • Use a Edição em tempo real quando quiser ver rapidamente o efeito de atualizações de elementos de UX, como atualizações de modificadores e animações, na experiência geral do app.
• Quando devo evitar a Edição em tempo real?
  • No momento, o recurso Edição em tempo real se concentra em mudanças no código relacionadas a IU e UX. Ele não oferece suporte a mudanças como atualizações de assinatura de método, adição de novos métodos ou mudanças na hierarquia de classes. Para saber mais, consulte Limitações do recurso Edição em tempo real.
• Quando devo usar a Visualização do Compose?
  • Use a Visualização do Compose ao desenvolver elementos combináveis. Ela apresenta os elementos do Compose e é atualizada automaticamente para mostrar o efeito das mudanças de código. A visualização também oferece suporte à exibição de elementos da IU em diferentes configurações e estados, como modo escuro, localidades e tamanho da fonte.

Mudar a variante de build

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

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 vai implantar no seu dispositivo e que ficará 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. Mudar 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. Para 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. Isso indica 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 M2 tem a variante v2 selecionada no ambiente de desenvolvimento integrado, você tem símbolos não resolvidos. Suponha que M1 dependa de uma classe disponível apenas em v1. Quando v2 for selecionado, essa classe não vai 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.

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. A configuração de execução especifica se o app vai ser implantado usando um APK ou um Android App Bundle, bem 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 suas próprias por projeto, padrão e módulo.

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