Versões Java em builds do Android

Se o código-fonte for escrito em Java, Kotlin ou ambos, há vários lugares em que você precisa escolher uma versão do JDK ou da linguagem Java para o build.

Figura 1. Relações do JDK em um build

Glossário

Kit de desenvolvimento Java (JDK)

O Kit de desenvolvimento para Java (JDK) contém:

• Ferramentas, como compiladores, criadores de arquivos e perfiladores. Eles são usados nos bastidores durante o build para criar seu aplicativo.
• Bibliotecas contendo APIs que você pode chamar do seu código-fonte em Kotlin ou Java. Nem todas as funções estão disponíveis no Android.
• A máquina virtual Java (JVM), um interpretador que executa aplicativos Java. Você usa a JVM para executar o ambiente de desenvolvimento integrado do Android Studio e a ferramenta de build do Gradle. A JVM não é usada em dispositivos ou emuladores Android.

Ambiente de execução da JetBrains (JBR)

O JetBrains Runtime (JBR) é um JDK aprimorado, distribuído com o Android Studio. Ele inclui várias otimizações para uso no Studio e produtos relacionados da JetBrains, mas também pode ser usado para executar outros aplicativos Java.

Como escolher um JDK para executar o Android Studio?

Recomendamos que você use o JBR para executar o Android Studio. Ele é implantado com e usado para testar o Android Studio e inclui melhorias para o uso ótimo do Android Studio. Para garantir isso, não defina a variável de ambiente STUDIO_JDK.

Os scripts de inicialização do Android Studio procuram uma JVM na seguinte ordem:

1. Variável de ambiente STUDIO_JDK
2. diretório studio.jdk (na distribuição do Android Studio);
3. diretório jbr (ambiente de execução do JetBrains), na distribuição do Android Studio. Recomendado.
4. Variável de ambiente JDK_HOME
5. Variável de ambiente JAVA_HOME
6. java executável na variável de ambiente PATH

Como escolho qual JDK executa meus builds do Gradle?

Se você executar o Gradle usando os botões no Android Studio, o JDK definido nas configurações do Android Studio será usado para executar o Gradle. Se você executar o Gradle em um terminal, dentro ou fora do Android Studio, a variável de ambiente JAVA_HOME (se definida) determina qual JDK executa os scripts do Gradle. Se JAVA_HOME não estiver definido, o comando java será usado na variável de ambiente PATH.

Para resultados mais consistentes, defina a variável de ambiente JAVA_HOME e a configuração do Gradle JDK no Android Studio para esse mesmo JDK.

Observação: se você executar um comando do Gradle no terminal do Android Studio clicando com o botão direito do mouse e selecionando Run highlighted command usando o ambiente de desenvolvimento integrado, ele usará o JDK nas configurações do Android Studio, não o JAVA_HOME.

Ao executar o build, o Gradle cria um processo chamado daemon para executar o build real. Esse processo pode ser reutilizado, desde que os builds usem a mesma versão do JDK e do Gradle. A reutilização de um daemon reduz o tempo de inicialização de uma nova JVM e inicializa o sistema de build.

Se você iniciar builds com diferentes JDKs ou versões do Gradle, daemons adicionais serão criados, consumindo mais CPU e memória.

Dica: ao trabalhar com vários projetos simultaneamente, se possível, especifique a mesma versão do Gradle no arquivo gradle-wrapper.properties para reduzir o número de daemons do Gradle criados.

Configuração do JDK do Gradle no Android Studio

Para modificar a configuração do Gradle JDK do projeto, abra as configurações do Gradle em File (ou Android Studio no macOS) > Settings > Build, Execution, Deployment > Build Tools > Gradle. O menu suspenso Gradle JDK contém as seguintes opções:

• Macros como JAVA_HOME e GRADLE_LOCAL_JAVA_HOME
• As entradas de tabela do JDK no formato vendor-version, como jbr-17, que são armazenadas nos arquivos de configuração do Android
• Como fazer o download de um JDK
• Como adicionar um JDK específico
• JDKs detectados localmente no diretório de instalação do JDK padrão do sistema operacional

A opção selecionada é armazenada em gradleJvm no arquivo .idea/gradle.xml do projeto, e a resolução de caminho do JDK é usada para executar o Gradle quando iniciado pelo Android Studio.

Figura 2. Configurações do Gradle JDK no Android Studio.

As macros permitem a seleção de caminho do JDK do projeto dinâmico:

• JAVA_HOME: usa a variável de ambiente com o mesmo nome
• GRADLE_LOCAL_JAVA_HOME: usa a propriedade java.home no arquivo .gradle/config.properties, que é padrão para o ambiente de execução do JetBrains.

O JDK selecionado é usado para executar o build do Gradle e resolver as referências da API do JDK ao editar os scripts de build e o código-fonte. O compileSdk especificado restringe ainda mais quais símbolos Java estarão disponíveis ao editar e criar o código-fonte.

Observação: na maioria dos casos, recomendamos o uso de GRADLE_LOCAL_JAVA_HOME, que é o padrão para projetos recém-criados. Isso permite definir um JDK específico do projeto sem abrir o projeto primeiro.

Escolha uma versão do JDK maior ou igual às versões do JDK usadas pelos plug-ins que você usa no build do Gradle. Para determinar a versão mínima do JDK necessária para o Plug-in do Android para Gradle (AGP), consulte a tabela de compatibilidade nas notas da versão.

Por exemplo, o Plug-in do Android para Gradle versão 8.x requer o JDK 17. Se você tentar executar um build do Gradle que o use com uma versão anterior do JDK, uma mensagem como esta será gerada:

An exception occurred applying plugin request [id: 'com.android.application']
> Failed to apply plugin 'com.android.internal.application'.
   > Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
      Your current JDK is located in /usr/local/buildtools/java/jdk
      You can try some of the following options:
       - changing the IDE settings.
       - changing the JAVA_HOME environment variable.
       - changing `org.gradle.java.home` in `gradle.properties`.

Quais APIs Java posso usar no meu código-fonte Java ou Kotlin?

Um aplicativo Android pode usar algumas das APIs definidas em um JDK, mas não todas elas. O SDK do Android define implementações de muitas funções de biblioteca Java como parte das APIs disponíveis. A propriedade compileSdk especifica qual versão do SDK do Android usar ao compilar o código-fonte Kotlin ou Java.

Kotlin

android {
    ...
    compileSdk = 33
}

Groovy

android {
    ...
    compileSdk 33
}

Cada versão do Android oferece suporte a uma versão específica do JDK e a um subconjunto das APIs Java disponíveis. Se você usar uma API Java disponível em um compileSdk que não está disponível no minSdk especificado, talvez seja possível usar a API na versão anterior do Android por um processo conhecido como dessugaramento. Consulte APIs Java 11 e mais recentes disponíveis pela simplificação para conferir as APIs com suporte.

Use esta tabela para determinar qual versão do Java é compatível com cada API do Android e onde encontrar detalhes sobre quais APIs Java estão disponíveis.

Android	Java	Recursos de API e linguagem com suporte
14 (nível 34 da API)	17	Bibliotecas principais
13 (nível 33 da API)	11	Bibliotecas principais
12 (API 32)	11	API Java
11 e versões anteriores		Versões do Android

Qual JDK compila meu código-fonte Java?

O JDK da cadeia de ferramentas Java contém o compilador Java usado para compilar qualquer código-fonte Java. Esse JDK também executa javadoc e testes de unidade durante o build.

A ferramenta de cadeia de ferramentas padrão é o JDK usado para executar o Gradle. Se você usar o padrão e executar um build em máquinas diferentes (por exemplo, sua máquina local e um servidor de integração contínua separado), os resultados do build poderão ser diferentes se diferentes versões do JDK forem usadas.

Para criar um build mais consistente, especifique explicitamente uma versão do conjunto de ferramentas do Java. Especifique o seguinte:

• Localiza um JDK compatível no sistema que executa o build.
  • Se não houver um JDK compatível (e um resolvedor de cadeia de ferramentas estiver definido), faça o download de um.
• Expõe as APIs Java da cadeia de ferramentas para chamadas do código-fonte.
• Compila a origem Java usando a versão da linguagem Java.
• Fornece padrões para sourceCompatibility e targetCompatibility.

Recomendamos que você sempre especifique a cadeia de ferramentas Java e verifique se o JDK especificado está instalado ou adicione um resolvedor de cadeia de ferramentas ao build.

Você pode especificar o conjunto de ferramentas independentemente de o código-fonte ser escrito em Java, Kotlin ou ambos. Especifique a cadeia de ferramentas no nível superior do arquivo build.gradle(.kts) do módulo.

Especifique a versão do conjunto de ferramentas do Java desta forma:

Kotlin

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

Groovy

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

Isso funciona se a origem for Kotlin, Java ou uma combinação de ambos.

A versão do JDK do conjunto de ferramentas pode ser a mesma usada para executar o Gradle, mas elas têm finalidades diferentes.

Quais recursos de origem da linguagem Java posso usar no meu código-fonte Java?

A propriedade sourceCompatibility determina quais recursos da linguagem Java estão disponíveis durante a compilação da origem do Java. Ele não afeta a origem do Kotlin.

Especifique sourceCompatibility no arquivo build.gradle(.kts) do módulo da seguinte forma:

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

Groovy

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

Se não for especificado, essa propriedade vai usar o padrão da versão da toolchain do Java. Se você não estiver usando um conjunto de ferramentas Java, o padrão será uma versão escolhida pelo Plug-in do Android para Gradle (por exemplo, Java 8 ou mais recente).

Observação: a partir do Android Studio Giraffe, quando os projetos são importados, a opção sourceCompatibility também é usada como padrão para a assistência de código do ambiente de desenvolvimento integrado e a linting ao escrever o código-fonte Java. Alguns recursos da linguagem Java exigem suporte de biblioteca e não estão disponíveis no Android. A opção compileSdk determina quais bibliotecas estão disponíveis. Outros recursos, como expressões de alternância, só exigem o compilador Java e funcionam no Android.

Quais recursos binários Java podem ser usados ao compilar minha fonte Kotlin ou Java?

As propriedades targetCompatibility e jvmTarget determinam a versão do formato de classe Java usada ao gerar bytecode para fontes compiladas em Java e Kotlin, respectivamente.

Alguns recursos do Kotlin já existiam antes de recursos equivalentes do Java serem adicionados. Os primeiros compiladores do Kotlin precisavam criar uma maneira própria de representar esses recursos. Alguns desses recursos foram adicionados mais tarde ao Java. Com níveis jvmTarget mais recentes, o compilador do Kotlin pode usar diretamente o recurso Java, o que pode resultar em melhor desempenho.

Diferentes versões do Android oferecem suporte a diferentes versões do Java. É possível aproveitar outros recursos do Java aumentando targetCompatibility e jvmTarget, mas isso pode forçar você a aumentar a versão mínima do SDK do Android para garantir que o recurso esteja disponível.

targetCompatibility precisa ser maior ou igual a sourceCompatibility. Na prática, sourceCompatibility, targetCompatibility e jvmTarget geralmente usam o mesmo valor. Você pode defini-los da seguinte forma:

Kotlin

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

Groovy

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget '17'
    }
}

Se não for especificado, essas propriedades vão assumir o padrão da versão da toolchain do Java. Se você não estiver usando uma cadeia de ferramentas Java, os valores padrão poderão ser diferentes e causar problemas de build. Portanto, recomendamos que você sempre especifique esses valores explicitamente ou use uma ferramenta de linha de comando Java.