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 seu build.

Glossário

Java Development Kit (JDK)

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

• Ferramentas, como um compilador, um criador de perfil e um criador de arquivos. Eles são usados nos bastidores durante o build para criar o aplicativo.
• Bibliotecas que contêm APIs que podem ser chamadas do seu código-fonte Kotlin ou Java. Nem todas as funções estão disponíveis no Android.
• A Java Virtual Machine (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.

JetBrains Runtime (JBR) (link em inglês)

O JetBrains Runtime (JBR) é um JDK aprimorado distribuído com o Android Studio. Ele inclui várias otimizações para uso no Studio e em 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 usar o JBR para executar o Android Studio. Ele é implantado com e usado para testar o Android Studio, além de incluir melhorias para o uso ideal 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 (JetBrains Runtime) na distribuição do Android Studio. Recomendado.
4. Variável de ambiente JDK_HOME
5. Variável de ambiente JAVA_HOME
6. Executável java 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) vai determinar qual JDK executa os scripts do Gradle. Se JAVA_HOME não estiver definido, ele usará o comando java na variável de ambiente PATH.

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

Ao executar o build, o Gradle cria um processo chamado daemon para realizar o build. 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 para iniciar uma nova JVM e inicializar o sistema de build.

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

Configuração do Gradle JDK no Android Studio

Para modificar a configuração do Gradle JDK do projeto atual, 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
• Entradas da tabela do JDK no formato vendor-version, como jbr-17, que são armazenadas nos arquivos de configuração do Android
• Como baixar um JDK
• Adicionar um JDK específico
• JDKs detectados localmente no diretório de instalação padrão do JDK do sistema operacional

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

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

• 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 usa o JetBrains Runtime por padrão.

O JDK selecionado é usado para executar seu build do Gradle e resolver referências da API do JDK ao editar scripts de build e 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.

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

Por exemplo, a versão 8.x do Plug-in do Android para Gradle 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á exibida:

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. O SDK do Android define implementações de muitas funções da 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.

android {
    ...
    compileSdk = 33
}

android {
    ...
    compileSdk 33
}

Cada versão do Android é compatível com uma versão específica do JDK e 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 desaçucaramento. Consulte APIs Java 11+ disponíveis pela simplificação para conferir as APIs compatíveis.

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.

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 cadeia de ferramentas usa por 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 versões diferentes do JDK forem usadas.

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

• 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), um será baixado.
• 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 garanta que o JDK especificado esteja instalado ou adicione um resolver de cadeia de ferramentas ao build.

É possível especificar a cadeia de ferramentas se o código-fonte for 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 assim:

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

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

Isso funciona se a fonte for Kotlin, Java ou uma combinação dos dois.

A versão do JDK do conjunto de ferramentas pode ser a mesma usada para executar o Gradle, mas lembre-se de que 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 Java. Isso não afeta a origem do Kotlin.

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

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
    }
}

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
    }
}

Se não for especificado, o padrão dessa propriedade será a versão da ferramenta Java. Se você não estiver usando um conjunto de ferramentas Java, a versão padrão será escolhida pelo plug-in do Android Gradle (por exemplo, Java 8 ou mais recente).

Quais recursos binários do 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 existiam antes da adição dos recursos equivalentes em Java. Os primeiros compiladores Kotlin precisavam criar a própria maneira de representar esses recursos do Kotlin. Alguns desses recursos foram adicionados ao Java mais tarde. Com níveis mais recentes de jvmTarget, o compilador Kotlin pode usar diretamente o recurso Java, o que pode resultar em melhor desempenho.

Diferentes versões do Android são compatíveis com diferentes versões do Java. Você pode aproveitar outros recursos do Java aumentando targetCompatibility e jvmTarget, mas isso pode exigir que você também aumente 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. É possível definir da seguinte forma:

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

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

Se não forem especificadas, essas propriedades vão usar a versão padrão da ferramenta 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 de forma explícita ou use uma cadeia de ferramentas Java.