Criar e executar o app

O Android Studio configura novos projetos para implantar no Android Emulator ou em um dispositivo conectado. Depois da instalação do app, você pode usar a opção Apply Changes para implantar determinadas mudanças de código e recursos sem implantar um novo APK cada vez que ele for executado.

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.

    Se você não tiver nenhum dispositivo configurado, vai ser necessário conectar um dispositivo ou criar um AVD para usar o Android Emulator.

  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.

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 o seguinte: se é necessário implantar o app usando um APK, o Android App Bundle ou um artefato personalizado, qual módulo vai ser executado, qual pacote vai ser implantado, qual atividade vai ser iniciada, o dispositivo de destino, as configurações do emulador, as opções do logcat e muito mais.

Se as configurações padrão não forem 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 ver mais informações, consulte Criar e editar configurações de execução/depuração.

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, 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 para o módulo determina qual variante de compilação o ambiente de desenvolvimento integrado implantará no dispositivo conectado e que ficará visível no editor.

Figura 1. 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 2. 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 v2 é selecionado, essa classe não é conhecida pelo ambiente de desenvolvimento integrado e falhará 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 versão do app, a variante selecionada nesta caixa de diálogo não terá efeito, porque o Gradle cria seu app com o código-fonte especificado nos roteiros de versão do Gradle, e não com base no que está carregado no momento no ambiente de desenvolvimento integrado.

Criar o projeto

O botão Run cria e implanta o app em um dispositivo. No entanto, para criar seu app para compartilhar ou fazer upload no Google Play, você precisará usar uma das opções no menu Build e criar o projeto total ou parcialmente. Antes de selecionar qualquer uma das opções listadas na tabela 1 primeiro selecione a variante de compilação a ser usada.

Tabela 1. Opções no menu Build.

Item de menu Descrição
Make Module Compila no módulo selecionado todos os arquivos de origem que foram modificados desde o último build, assim como todos os módulos de que o módulo selecionado depende recursivamente. A compilação inclui arquivos de origem dependente e quaisquer tarefas associadas. Você pode selecionar o módulo a ser compilado selecionando o nome do módulo ou um dos arquivos dele na janela Project.
Make Project Faz todos os módulos.
Clean Project Exclui todos os arquivos de compilação intermediários/armazenados em cache.
Rebuild Project Executa o Clean Project para a variante de build selecionada e produz um APK.
Build Bundle(s) / APK(s) > Build APK(s)

Cria um APK de todos os módulos no projeto atual para a variante selecionada. Quando o build for concluído, uma notificação de confirmação será exibida, fornecendo um link para o arquivo APK e um link para analisá-lo no APK Analyzer.

Se a variante de build selecionada for um tipo de build de depuração, o APK será assinado com uma chave de depuração e estará pronto para ser instalado. Se você selecionou uma variante de versão, o APK não estará assinado por padrão e você vai precisar assiná-lo manualmente. Como alternativa, selecione Build > Generate Signed Bundle / APK na barra de menus.

O Android Studio salva os APKs que você cria em project-name/module-name/build/outputs/apk/.

Build Bundle(s) / APK(s) > Build Bundle(s)

Cria um Android APP Bundle de todos os módulos no projeto atual para a variante selecionada. Quando o build for concluído, uma notificação de confirmação será exibida, fornecendo um link para o pacote de apps e um link para análise no APK Analyzer.

Se a variante de build selecionada for um tipo de build de depuração, o pacote de apps vai ser assinado com uma chave de depuração e você vai poder usar o bundletool para implantar seu app do pacote de apps em um dispositivo conectado. Se você selecionou uma variante de versão, o pacote de apps não vai estar assinado por padrão, e você vai precisar assiná-lo manualmente usando jarsigner. Como alternativa, selecione Build > Generate Signed Bundle / APK na barra de menus.

O Android Studio salva os APKs que você cria em project-name/module-name/build/outputs/bundle/.

Generate Signed Bundle / APK Abre uma caixa de diálogo com um assistente para definir uma nova configuração de assinatura e criar um APK ou pacote de app assinado. É necessário assinar o app com uma chave de versão antes de fazer upload dele para o Play Console. Se quiser mais informações sobre a assinatura de apps, consulte Assinar o app.

Observação: o botão Run cria um APK com testOnly="true", o que significa que o APK só pode ser instalado via adb, que o Android Studio usa. Se você quiser um APK depurável que as pessoas possam instalar sem o adb, selecione a variante de build e clique em Build Bundle(s) / APK(s) > Build APK(s).

Para ver mais detalhes sobre as tarefas que o Gradle executa para cada comando, abra a janela Build conforme descrito na próxima seção. Para mais informações sobre o Gradle e o processo de compilação, consulte Configurar sua versão.

Monitorar o processo de compilação

Veja detalhes sobre o processo de compilação, clicando em View > Tool Windows > Build ou clicando em Build na barra da janela de ferramentas. A janela exibe as tarefas que o Gradle executa para criar seu app, conforme mostrado na Figura 3.

Figura 3. A janela de saída "Build" no Android Studio.

  1. Guia Build: exibe 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 4.

    Figura 4. Inspecione a janela de saída "Build" 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 compilação 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.

Edição em tempo real (experimental)

A Edição em tempo real é um recurso experimental nas versões do Android Studio Electric Eel Canary que 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 ao dispositivo ou emulador à medida que você as faz. 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 5. 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 em tempo real.

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 6. 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 7. 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 8. 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

    Figura 9. A marca de seleção verde e a seta do menu suspenso da Edição em tempo real são exibidas depois que você ativa esse recurso.

Fazer e revisar mudanças

No editor, mude o método Greeting já existente em MainActivity para o exemplo abaixo. As mudanças feitas são exibidas instantaneamente, como mostrado na Figura 10.

@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 10. 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 11. 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 vão ter problemas de desempenho. Recomendamos que você execute o app e use um build de lançamento limpo se estiver avaliando o desempenho 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 necessárias quando o projeto é criado 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 mostra os elementos do Compose e é atualizada automaticamente para exibir 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 escala de fonte.

Apply Changes

No Android Studio 3.5 e versões mais recente, o recurso Apply Changes permite que você envie mudanças de código e recursos ao app em execução sem reiniciá-lo 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 alterações 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ções 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.