Independentemente de o código-fonte ser escrito em Java, Kotlin ou ambos, há vários lugares em que é preciso escolher uma versão da linguagem JDK ou Java para seu build.
Glossário
- Kit de desenvolvimento Java (JDK)
-
O Kit de desenvolvimento Java (JDK)
contém:
- Ferramentas, como compilador, criador de perfil e criador de arquivos. Eles são usados em segundo plano durante a compilação para criar o aplicativo.
- Bibliotecas contendo APIs que você pode chamar do seu código-fonte Kotlin ou Java. Nem todas as funções estão disponíveis no Android.
- A máquina virtual Java (JVM), um intérprete que executa aplicativos Java. Use 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 nos produtos JetBrains relacionados, 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
e usado para testar o Android Studio e inclui melhorias para otimizar o
uso. 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:
- Variável de ambiente
STUDIO_JDK
- Diretório
studio.jdk
(na distribuição do Android Studio) - Diretório
jbr
(JetBrains Runtime) na distribuição do Android Studio. Recomendado. - Variável de ambiente
JDK_HOME
- Variável de ambiente
JAVA_HOME
java
executável na variável de ambientePATH
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 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.
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 para iniciar uma nova JVM e inicializar o sistema de build.
Se você iniciar builds com diferentes versões do JDK ou Gradle, outros daemons serão criados, consumindo mais CPU e memória.
Configuração do JDK do Gradle no Android Studio
Para modificar a configuração do Gradle JDK do projeto existente, 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
eGRADLE_LOCAL_JAVA_HOME
. - Entradas da tabela do JDK no formato
vendor-version
, comojbr-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 padrão do JDK 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.
As macros ativam a seleção de caminho dinâmico do JDK do projeto:
JAVA_HOME
: usa a variável de ambiente com o mesmo nome.GRADLE_LOCAL_JAVA_HOME
: usa a propriedadejava.home
no arquivo.gradle/config.properties
, que tem como padrão o ambiente de execução do JetBrains.
O JDK selecionado é usado para executar o build do Gradle e resolver as referências da
API JDK ao editar os scripts de build e o código-fonte. Observe que o
compileSdk
especificado restringe ainda mais quais símbolos Java estarão
disponíveis ao editar e criar seu código-fonte.
Escolha uma versão do JDK maior ou igual às versões do JDK usadas pelos plug-ins usados 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, o Plug-in do Android para Gradle versão 8.x exige o JDK 17. Se você tentar executar um build do Gradle que o usa com uma versão anterior do JDK, ele vai informar uma mensagem como esta:
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/jdk11
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 da biblioteca Java
como parte das APIs disponíveis. A propriedade compileSdk
especifica qual
versão do SDK do Android usar ao compilar seu código-fonte em Kotlin ou Java.
Kotlin
android {
...
compileSdk = 33
}
Groovy
android {
...
compileSdk 33
}
Cada versão do Android é compatível com uma versão específica do JDK e com um subconjunto das
APIs Java disponíveis. Se você usar uma API Java disponível em
uma compileSdk
que não está disponível na
minSdk
especificada, talvez seja possível usar a API
na versão anterior do Android com um processo conhecido como
simplificação.
Confira as APIs Java 11+ disponíveis por simplificação para conhecer 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 compatíveis |
---|---|---|
14 (nível 34 da API) | 17 | Bibliotecas principais |
13 (nível 33 da API) | 11 | Bibliotecas principais |
12 (nível 32 da API) | 11 | API Java |
11 e inferior | Versões do Android |
Qual JDK compila meu código-fonte em Java?
O conjunto de ferramentas Java JDK contém o compilador Java usado para compilar qualquer código-fonte Java. Esse JDK também executa testes de unidade e do javadoc durante a compilação.
O padrão do conjunto de ferramentas é o JDK usado para executar o Gradle. Se você usar o padrão e executar um build em máquinas diferentes (por exemplo, na máquina local e em um servidor de integração contínua separado), os resultados do build poderão ser diferentes caso versões diferentes do JDK sejam usadas.
Para criar um build mais consistente, você pode especificar explicitamente uma versão do conjunto de ferramentas Java. Especificar isso:
- Localiza um JDK compatível no sistema que está executando o build.
- Se não houver um JDK compatível (e um resolvedor de conjunto de ferramentas estiver definido), o download será feito.
- Expõe as APIs Java do conjunto de ferramentas para chamadas do código-fonte.
- Compila o código-fonte Java usando a versão da linguagem Java.
- Padrões de suprimentos para
sourceCompatibility
etargetCompatibility
.
Recomendamos que você sempre especifique o conjunto de ferramentas do Java e verifique se o JDK especificado está instalado ou adicione um resolvedor de conjunto 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 o conjunto 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 dos dois.
A versão do JDK do conjunto de ferramentas pode ser igual ao JDK usado para executar o Gradle, mas tenha em mente que elas servem a finalidades diferentes.
Quais recursos-fonte 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.
Ele não afeta a origem do Kotlin.
Se não for especificado, o padrão será o conjunto de ferramentas Java ou
JDK usado para executar o Gradle. Recomendamos que você sempre especifique explicitamente
um conjunto de ferramentas (preferencial) ou sourceCompatibility
.
Especifique sourceCompatibility
no arquivo build.gradle(.kts)
do módulo.
Kotlin
android {
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
}
}
Groovy
android {
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
}
}
Quais recursos binários Java podem ser usados quando eu compilo minha fonte Kotlin ou Java?
Especificar targetCompatibility
e jvmTarget
determina 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 da adição de recursos Java equivalentes.
Os primeiros compiladores do Kotlin precisavam criar a própria maneira de representar esses recursos
do Kotlin. Alguns desses recursos foram adicionados posteriormente ao Java.
Com níveis jvmTarget
posteriores, o compilador Kotlin pode usar diretamente
o recurso Java, o que pode resultar em um melhor desempenho.
O padrão de targetCompatibility
é o mesmo valor que
sourceCompatibility
,
mas, se especificado, precisa ser maior ou igual a sourceCompatibility
.
jvmTarget
tem como padrão a versão do conjunto de ferramentas.
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 também a
versão mínima do SDK do Android para garantir
que o recurso esteja disponível.
Kotlin
android {
compileOptions {
targetCompatibility = JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = "17"
}
}
Groovy
android {
compileOptions {
targetCompatibility JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget '17'
}
}