Criar e executar o app

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

É preciso criar e executar o app para verificar a aparência e o comportamento dele em um dispositivo. O Android Studio configura novos projetos para que você possa implantar seu app em um dispositivo virtual ou físico com apenas alguns cliques.

Esta visão geral se concentra em usar o Android Studio para criar e executar o app para fins de teste e depuração. Para mais informações 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 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 suspenso de configurações de execução.
  2. No menu suspenso de dispositivo de destino, selecione o dispositivo em que você quer executar seu app.

    Menu suspenso do dispositivo de destino.

    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 um 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 compilação

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

Figura 1. A janela "Build output" no Android Studio.

  1. Guia Build: mostra as tarefas que o Gradle executa como uma árvore, onde cada nó representa uma fase de compilação ou um grupo de dependências de tarefas. Se você receber erros de tempo de compilação 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.

    Figura 2. Inspecione a janela "Build output" em busca de mensagens de erro.

  2. Guia Sync: exibe as tarefas que o Gradle executa para sincronizar com os arquivos de projeto. Assim como na guia Build, se você encontrar um erro de sincronização, selecione elementos na árvore para ver mais informações sobre ele.
  3. Restart: executa a mesma ação que selecionar Build > Make Project, gerando arquivos intermediários de build para todos os módulos do projeto.
  4. Toggle view: alterna entre a exibição da execução da tarefa como uma árvore gráfica e a exibição de uma saída de texto mais detalhada do Gradle. Essa é a mesma saída que você vê na janela Gradle Console no Android Studio 3.0 e versões anteriores.

Caso suas variantes de compilação 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 compilação disponíveis, clique em View > Tool Windows > Gradle, ou clique em Gradle na barra da janela de ferramentas.

Se ocorrer um erro durante o processo de compilação, o Gradle poderá recomendar algumas opções de linha de comando para ajudar você a 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 Mac OSX, 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 compilação e execução

A maneira padrão de implantar o app pelo Android Studio, abordada na seção anterior, é suficiente para testar um app simples. Para casos de uso mais avançados, você pode mudar vários aspectos de como o app é criado e executado:

  • Também é possível implantar seu app no modo de depuração clicando 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ê tem um app maior e mais complexo, o uso de "Apply Changes" em vez de clicar em "Run" pode economizar tempo, porque pode evitar que o app seja reiniciado sempre que você quiser implantar uma mudança. Para mais informações sobre "Apply Changes", consulte Implantar incrementalmente com "Apply Changes" nesta página.

  • Se você está usando o Compose, a Edição em tempo real permite atualizar elementos de composição de forma imediata, sem ter que clicar novamente em Run. Assim, você pode se concentrar em escrever o código da IU com o mínimo de interrupção. Para mais informações, consulte Edição em tempo real nesta página.

  • 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 Mudar a variante de build nesta página.

  • Para ajustar as opções de instalação, inicialização e teste de apps, mude a configuração de execução/depuração. Essa configuração especifica se o app será implantado a partir de um APK ou de um Android App Bundle, 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. Para mais informações sobre como criar configurações personalizadas de execução/depuração, consulte Criar configurações de execução/depuração.

  • Você pode tentar usar 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 o app na linha de comando.

Implantar de forma incremental com o recurso "Apply Changes"

No Android Studio 3.5 e versões mais recentes, o recurso "Apply Changes" permite que você envie 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. Apply Changes usa recursos na implementação da JVMTI para Android compatíveis com dispositivos que executam o Android 8.0 (API de nível 26) ou versões mais recentes. Para saber mais sobre como a opção "Apply Changes" funciona, consulte Project Marble do Android Studio: Apply Changes (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 Ícone de "Apply Changes and Restart Activity"

Tenta aplicar as modificações de recurso e 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 executar essa ação pressionando Ctrl+Alt+F10 (ou Control+Shift+Command+R no macOS).

Apply Code Changes Ícone de "Apply Code Changes"

Tenta aplicar somente suas modificações de código sem reiniciar nada. Geralmente, você pode usar essa opção quando tiver modificado o código no corpo de um método, mas não tiver modificado nenhum recurso. Se você tiver modificado o código e os recursos, use Apply Changes and Restart Activity.

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

Run Ícone de Run

Implanta todas as modificações e reinicia o app. Use essa opção quando as modificações não puderem ser aplicadas usando uma das opções de Apply Changes. Para saber mais sobre os tipos de modificação que exigem a reinicialização do app, consulte Limitações de "Apply Changes".

Ativar substituto de execução para "Apply Changes"

Depois que você clicar em Apply Changes and Restart Activity ou Apply Code Changes, o Android Studio criará um novo APK e determinará se as modificações podem ser aplicadas. Se elas não puderem e fizerem com que o recurso "Apply Changes" falhe, o Android Studio pedirá que você execute Ícone de Run o app novamente. No entanto, se você não quiser receber um aviso sempre que isso ocorrer, poderá configurar 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ático para qualquer uma das ações de "Apply Changes".

  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.

Tipo de mudança Versão mínima da plataforma
Como adicionar um método Android 11

Limitações de Apply Changes

O recurso Apply Changes foi criado para acelerar o processo de implantação do app. No entanto, existem algumas limitações de uso. Se você encontrar problemas durante o uso de "Apply Changes", informe um bug (link em inglês).

Modificações no código que exigem reinicialização do app

Algumas modificações de códigos 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 "Apply Changes" das seguintes maneiras:

  • Se uma biblioteca ou um plug-in fizer modificações no manifesto do app, não será possível usar Apply Code Changes Ícone de "Apply Code Changes" ou Apply Changes and Restart Activity Ícone de "Apply Changes and Restart Activity" e você terá que reiniciar o app para poder ver as modificações.
  • Se uma biblioteca ou um plug-in fizer modificações nos arquivos de recurso do app, não será possível usar Apply Code Changes Ícone de "Apply Code Changes" e você precisará usar Apply Changes and Restart Activity Ícone de "Apply Changes and Restart Activity" para ver as modificações.

Você pode evitar essas limitações desativando todas as atualizações automáticas para suas variantes de compilação de depuração.

Por exemplo, o Crashlytics atualiza recursos de apps com um ID de build exclusivo durante cada build, o que impede o uso de Apply Code Changes Ícone de Apply Code Changes e exige que você reinicie a atividade do app para ver as mudanças. Você pode desativar esse comportamento para que possa usar Apply Code Changes junto ao Crashlytics com 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 Ícone de "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 Ícone de "Apply Changes and Restart Activity" ou Run Ícone de Run.

Edição em tempo real (experimental)

A Edição em tempo real é um recurso experimental nas versões canário do Android Studio Flamingo. Ela permite atualizar elementos de composição em emuladores e dispositivos físicos em tempo real. Quando você atualiza uma função de composição, suas mudanças são aplicadas no dispositivo ou emulador à medida que são feitas. Essa funcionalidade minimiza as mudanças de contexto entre a gravação e criação do app, permitindo que você se concentre em programar código por mais tempo, sem interrupções.

O recurso de Edição em tempo real se concentra em mudanças no código relacionadas a IU e UX. A Edição em tempo real 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 mais informações, consulte Limitações.

Esse recurso não substitui a criação e execução do aplicativo ou o recurso Apply Changes. 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 que não tenha suporte dela. Por exemplo: adicionar novos métodos enquanto o app estiver em execução.
  3. Após fazer uma mudança sem suporte, execute o app para retomar a Edição em tempo real.

GIF mostrando o uso da Edição em tempo real com um dispositivo

Figura 3. 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 fazer a Edição em tempo real

Para começar rapidamente, siga estas etapas para criar uma atividade vazia do Compose, ativar o recurso de 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 mais recente do Android Studio Electric Eel instalada e se o nível da API do dispositivo físico ou emulador é 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.

    Seleção de modelos no Android Studio Figura 4. Modelos disponíveis. Para usar a Edição em tempo real, escolha Empty Compose Activity.

  4. Preencha as informações como mostrado abaixo e clique em Finish.

    • Name: HelloWorld
    • Package name: com.example.helloworld
    • Save location: Default.
    • Language: Kotlin
    • Minimum SDK: Default

    Exemplo de configurações do projeto da etapa 4 no AS Figura 5. Exemplo de configurações do projeto.

Ativar a Edição em tempo real
  1. No ambiente de desenvolvimento integrado, navegue até 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.

    IU da caixa de seleção da Edição em tempo real nas configurações do Android Studio Figura 6. Selecione a opção Live Edit nas configurações.

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

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

  4. Depois de ativar a Edição em tempo real, você vai ver a marca de seleção verde em Live Edit no canto direito de cima do editor.

    IU da marca de seleção verde da Edição em tempo real

Fazer e revisar mudanças

No editor, mude o método Greeting em MainActivity para o exemplo abaixo. As mudanças feitas aparecem instantaneamente, como mostrado na Figura 7.

@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)
    )
}

Mudanças feitas no método de saudação mostradas em um dispositivo

Figura 7. As mudanças em tempo real feitas no método Greeting acima aparecem instantaneamente.

Solução de problemas

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. Confira se o indicador da IU Live Edit mostra um ícone pausado, que indica um erro de compilação.

IU de status da Edição em tempo real

Figura 8. Para ver mais informações sobre o erro e sugestões de solução, passe o cursor sobre Live Edit: ON na IU.

Limitações

Veja abaixo uma lista das limitações atuais.

  • 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. Recomendamos que você 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 Botão da IU.
  • 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 que não são de composição 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 que não são de composição, é 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.

Perguntas frequentes

  • Qual é o status atual da Edição em tempo real?
    • A Edição em tempo real está disponível no canal Android Studio Electric Eel Canary como um recurso experimental. Para ativar ou desativar esse recurso, clique em File > Settings > Editor > Live Edit (Android Studio > Preferences > Editor > Live Edit no macOS).
  • Quando posso usar a Edição em tempo real?
    • Use esse recurso para 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, a Edição em tempo real se concentra em mudanças no código relacionadas a IU e UX. Evite usá-la para fazer mudanças como atualizações de assinatura de métodos, adição de novos métodos ou mudanças na hierarquia de classes, que não tem suporte desse recurso. Para mais informações, consulte Limitações.
  • Quando devo usar a Visualização do Compose?
    • Use a visualização do Compose ao desenvolver elementos de composição individuais. 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 compilação que o Android Studio usa, selecione Build > Select Build Variant na barra de menus.

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 Buid Variants tem três colunas: Module, Active Build Variant e Active ABI. O valor da Active Build Variant para o módulo determina a variante de compilação que o ambiente de desenvolvimento integrado 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 compilação ou ABI, clique na célula da coluna Active Build Variant ou Active ABI e escolha a variante ou a ABI desejada na lista. Depois que você mudar a seleção, o ambiente de desenvolvimento integrado sincronizará seu projeto automaticamente. Mudar a coluna para um módulo de app ou de biblioteca aplicará a modificação em 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 criar outras variações do app, cada uma com recursos ou requisitos de dispositivo diferentes, você pode configurar 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:

Janela "Variant Build" com erros de conflito de variante

Esse erro não indica um problema de versão com o Gradle. Ele indica apenas que o próprio 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. Digamos que M1 depende de uma classe Foo que só está disponível em v1. Quando a v2 é selecionada, essa classe não é conhecida pelo ambiente de desenvolvimento integrado e falha em resolver e mostrar erros no código de 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 momento 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 de um APK ou de um Android App Bundle, 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, você pode personalizar as configurações de execução/depuração ou mesmo criar novas configurações nos níveis de projeto, padrão e módulo. Para editar uma configuração de execução/depuração, selecione Run > Edit Configurations. Para mais informações, consulte Criar e editar configurações de execução/depuração.