Configurar sua versão

O sistema de build do Android compila os recursos e o código-fonte do app e os coloca em APKs ou Android App Bundles que podem ser testados, implantados, assinados e distribuídos.

O Android Studio usa o Gradle (link em inglês), um kit de ferramentas de build avançado, para automatizar e gerenciar o processo, permitindo que você defina configurações de build personalizadas e flexíveis. Cada configuração de build pode definir o próprio conjunto de códigos e recursos, reutilizando as partes comuns a todas as versões do app. O Plug-in do Android para Gradle trabalha com o kit de ferramentas de build para fornecer processos e configurações ajustáveis que são específicos para criar e testar apps Android.

O Gradle e o Plug-in do Android para Gradle são executados de forma independente do Android Studio. Isso significa que você pode criar seus apps Android no Android Studio, na linha de comando da sua máquina ou usando máquinas em que o Android Studio não está instalado, como servidores de integração contínua.

Se você não estiver usando o Android Studio, veja como criar e executar seu app na linha de comando. A saída do build é a mesma, quer você esteja criando o projeto em uma linha de comando, em uma máquina remota ou pelo Android Studio.

Observação: como o Gradle e o Plug-in do Android para Gradle são executados de forma independente do Android Studio, é necessário atualizar as ferramentas de build separadamente. Leia as notas da versão para aprender a atualizar o Gradle e o Plug-in do Android para Gradle.

A flexibilidade do sistema de build do Android permite criar configurações de build personalizadas sem modificar os arquivos de origem principais do app. Esta página ajuda a entender como o sistema de build do Android funciona e como ele pode ajudar a personalizar e automatizar várias configurações de build. Se quiser saber mais sobre a implantação do app, consulte Criar e executar o app. Para já começar a criar configurações de build personalizadas com o Android Studio, leia Configurar variantes de build.

O processo de build

O processo de build envolve muitas ferramentas e processos que convertem seu projeto em um pacote de aplicativo Android (APK) ou em um Android App Bundle (AAB).

O Plug-in do Android para Gradle realiza grande parte desse processo de build, mas entender alguns aspectos desse processo pode ser útil para conseguir ajustar o build da maneira que você achar necessário.

Projetos diferentes podem ter metas de build distintas. Por exemplo, o build de uma biblioteca de terceiros produz bibliotecas Android Archive (AAR) ou Java Archive (JAR). Contudo, o tipo de projeto mais comum é o app. O build de um projeto de app gera um APK ou AAB de depuração ou de lançamento, que pode ser implantado, testado ou lançado para usuários externos.

Esta página se concentra no desenvolvimento de apps, mas muitas das etapas e dos conceitos apresentados são comuns na maioria dos tipos de build.

Glossário de build do Android

O Gradle e o Plug-in do Android para Gradle ajudam a configurar estes aspectos do build:

Tipos de build

Os tipos de build definem algumas propriedades que o Gradle usa ao criar e empacotar seu app. Geralmente, eles são configurados para diferentes fases do ciclo de desenvolvimento.

Por exemplo, o tipo de build de depuração oferece opções de depuração e assina o app com a chave de depuração. Já o de lançamento pode reduzir, ofuscar e assinar o app com uma chave de lançamento para distribuição.

É necessário definir pelo menos um tipo de build para criar seu app. Por padrão, o Android Studio cria os tipos de build de depuração e lançamento. Para começar a personalizar as configurações de empacotamento do app, aprenda a configurar tipos de build.

Variações de produtos
As variações de produto representam diferentes versões do app que podem ser lançadas para os usuários, como versões pagas e sem custos. Você pode personalizar as variações de produtos para usar códigos e recursos diferentes, ao mesmo tempo que compartilha e reutiliza as partes comuns a todas as versões do app. As variações de produto são opcionais e precisam ser criadas manualmente. Para começar a criar diferentes versões do app, aprenda a configurar variações de produtos.
Variantes de build
Uma variante de build é o produto resultante da combinação de um tipo de build e uma variação de produto. Essa é a configuração que o Gradle usa para criar seu app. Com as variantes de build, você pode criar a versão de depuração das suas variações de produto durante o desenvolvimento, além de criar versões de lançamento assinadas dessas variações para distribuição. Embora as variantes de build não sejam configuradas diretamente, é necessário configurar os tipos de build e as variações de produto que compõem essas variantes. A criação de outros tipos de build ou variações de produtos também faz com que outras variantes sejam criadas. Para aprender a criar e gerenciar variantes de build, leia a visão geral sobre como Configurar variantes de build.
Entradas do manifesto
Você pode especificar valores para algumas propriedades do arquivo de manifesto na configuração da variante de build. Eles substituem os valores existentes no arquivo de manifesto. Isso é útil quando você quer gerar diversas variantes do seu app com um nome diferente, versão mínima do SDK ou versão de destino do SDK. Quando há vários manifestos, a ferramenta de combinação de manifestos combina as configurações de manifesto.
Dependências
O sistema de build gerencia as dependências do projeto no sistema de arquivos local e nos repositórios remotos. Isso significa que não é necessário pesquisar, fazer o download e copiar manualmente pacotes binários das suas dependências para o diretório do projeto. Para saber mais, consulte Adicionar dependências de build.
Assinaturas
O sistema de build permite especificar opções de assinatura nas configurações e pode assinar seu app automaticamente durante o processo de build. O sistema assina a versão de depuração com uma chave e um certificado padrão, usando credenciais conhecidas para evitar solicitações de senha no momento do build. O sistema só assina a versão de lançamento se você define explicitamente uma configuração de assinatura para esse build. Caso você não tenha uma chave de lançamento, é possível gerar uma de acordo com a descrição apresentada em Assinar o app. A maioria das app stores exigem builds de lançamento assinados para que os apps sejam distribuídos.
Redução de código e recursos
O sistema de build permite especificar um arquivo de regras do ProGuard diferente para cada variante de build. Ao criar seu app, o sistema de build aplica o conjunto de regras adequado para reduzir seu código e recursos usando as ferramentas de redução integradas, como o R8. Reduzir o código e os recursos pode ajudar a diminuir o tamanho do APK ou AAB.
Compatibilidade com vários APKs
O sistema de build permite criar diferentes APKs automaticamente, cada um contendo apenas os códigos e recursos necessários para uma densidade de tela ou Interface binária do aplicativo (ABI) específica. Para saber mais, consulte Criar vários APKs. No entanto, o recomendado é lançar apenas um ABB, já que ele oferece a divisão por idioma, a densidade de tela e a ABI sem que seja necessário fazer upload de vários artefatos para o Google Play. Todos os apps enviados depois de agosto de 2021 precisam usar AABs.

Versões Java em builds do Android

Não importa se o código-fonte foi escrito em Java, Kotlin ou ambos, há vários lugares onde você precisa escolher uma versão da linguagem JDK ou Java para o build. Consulte Versões Java em builds do Android para mais detalhes.

Arquivos de configuração de build

Para criar configurações de build personalizadas, você precisa mudar um ou mais arquivos de configuração de build. Esses arquivos de texto simples usam a Domain Specific Language (DSL) para descrever e manipular a lógica de build usando o script Kotlin, que é uma variação da linguagem Kotlin. Também é possível usar o Groovy, que é uma linguagem dinâmica para a Java Virtual Machine (JVM), para configurar os builds.

Não é preciso conhecer o script Kotlin ou o Groovy para começar a configurar seu build, porque o Plug-in do Android para Gradle apresenta a maioria dos elementos DSL necessários. Para saber mais sobre a DSL do Plug-in do Android para Gradle, leia a documentação de referência da DSL. O script Kotlin também depende da DSL Kotlin do Gradle (link em inglês).

Ao iniciar um novo projeto, o Android Studio cria automaticamente alguns arquivos para você e os preenche com base em padrões razoáveis. A estrutura de arquivos do projeto tem o seguinte layout: 

└── MyApp/  # Project
    ├── gradle/
    │   └── wrapper/
    │       └── gradle-wrapper.properties
    ├── build.gradle(.kts)
    ├── settings.gradle(.kts)
    └── app/  # Module
        ├── build.gradle(.kts)
        └── build/
            ├── libs/
            └── src/
                └── main/  # Source set
                    ├── java/
                    │   └── com.example.myapp
                    ├── res/
                    │   ├── drawable/
                    │   ├── values/
                    │   └── ...
                    └── AndroidManifest.xml

Há alguns arquivos de configuração de build do Gradle que fazem parte da estrutura de projeto padrão de um app Android. Antes de começar a configurar seu build, é importante entender o escopo e o propósito de cada um desses arquivos e os elementos DSL básicos que eles definem.

Arquivo Wrapper do Gradle

O wrapper do Gradle (gradlew) é um pequeno app incluído no código-fonte que faz o download e inicia o Gradle. Isso cria uma execução de build mais consistente. Os desenvolvedores fazem o download da origem do aplicativo e executam o gradlew. Isso faz o download da distribuição necessária do Gradle e inicia o Gradle para criar o aplicativo.

O arquivo gradle/wrapper/gradle-wrapper.properties contém uma propriedade, distributionUrl, que descreve qual versão do Gradle é usada para executar o build.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Arquivo de configurações do Gradle

O arquivo settings.gradle.kts (para a DSL do Kotlin) ou o arquivo settings.gradle (para a DSL do Groovy) fica localizado no diretório raiz do projeto. Esse arquivo de configurações define as configurações de repositório do projeto e informa ao Gradle os módulos que vão ser incluídos ao criar seu app. Projetos com vários módulos precisam especificar cada um dos que serão incluídos no build final.

Por padrão, o arquivo fica assim na maior parte dos projetos:

Kotlin

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. The code below
      * defines the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

Groovy

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. The code below
      * defines the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

Arquivo de build de nível superior

O arquivo build.gradle.kts (para a DSL do Kotlin) ou o arquivo build.gradle (para a DSL do Groovy) está localizado no diretório raiz do projeto. Normalmente, ele define as versões comuns dos plug-ins usados pelos módulos no seu projeto.

O exemplo de código a seguir descreve as configurações padrão e os elementos de DSL no script de build de nível superior após a criação de um novo projeto:

Kotlin

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id("com.android.application") version "8.1.0" apply false
    id("com.android.library") version "8.1.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.20" apply false
}

Groovy

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id 'com.android.application' version '8.1.0' apply false
    id 'com.android.library' version '8.1.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.20' apply false
}