2. Configuração do ambiente de desenvolvimento
O ambiente de trabalho do desenvolvedor Kotlin é composto de três componentes independentes:
- o JDK (“Java Development Kit”): Kotlin, como o usamos neste documento, é compilada em bytecode e executada pela Máquina Virtual Java (JVM), exatamente como um programa Java. O JDK fornece essa máquina virtual, o comando [java] que executa os programas, as bibliotecas padrão do Java SE (que Kotlin usa diretamente: arquivos, rede, datas, threads etc.) e ferramentas como [javap] ou [jar];
- uma ferramenta de build de projetos, neste caso o Gradle: ela baixa o compilador Kotlin e as bibliotecas de que um projeto precisa, compila o projeto, executa seus testes e o empacota;
- um editor ou um IDE (Ambiente de Desenvolvimento Integrado): [IntelliJ IDEA], concebido pela empresa que criou Kotlin, é a escolha natural; o [VS Code] com a extensão Kotlin é outra opção. O IDE se baseia no JDK e sabe ler projetos Gradle.
O próprio compilador Kotlin não faz parte dessa lista: o Gradle o baixa para cada projeto e o IntelliJ IDEA o inclui. No entanto, você pode instalá-lo separadamente para usar o comando [kotlinc] e compilar um único arquivo: faremos isso no nosso primeiro programa, mas é opcional.
Este documento usa os comandos [java], [kotlinc] e [gradlew] para todas as operações: eles funcionam da mesma forma no Windows, no Linux e no macOS, qualquer que seja o editor escolhido.
2.1. JDK 25
2.1.1. Instalação
Há várias distribuições do JDK, todas construídas a partir do código-fonte do OpenJDK e equivalentes para os nossos fins. Recomendamos o Eclipse Temurin, uma distribuição gratuita e de código aberto da Eclipse Foundation, que pode ser baixada em https://adoptium.net: ali, selecione a versão 25—LTS, o sistema operacional e o tipo de pacote (no Windows, um instalador [.msi]). No Windows, você também pode instalá-lo a partir de um terminal (PowerShell ou prompt de comando) com o gerenciador de pacotes [winget]:
É preciso selecionar o JDK (que contém tudo) e não apenas o JRE (que só permite executar programas já compilados). Na instalação no Windows, marque as opções que adicionam o JDK ao [PATH] e definem a variável de ambiente [JAVA_HOME]: o Gradle, o compilador [kotlinc] e os IDEs usam essa variável para localizar o JDK. No Linux, o JDK está disponível nos repositórios das principais distribuições (por exemplo, [sudo apt install openjdk-25-jdk] no Ubuntu).
Após a instalação, abra um novo terminal para verificar se o comando [java] está disponível e exibe a versão do JDK:
Esses resultados foram obtidos com o JDK Temurin 25.0.4, que foi usado para escrever este documento. A versão exata depende da data de instalação: atualizações de correção são lançadas a cada trimestre. Todas as versões 25.0.x do JDK servem para este documento. Várias instâncias do JDK podem coexistir no mesmo computador: a primeira encontrada no diretório do [PATH] responde ao comando [java].
O JDK também contém o compilador Java [javac] ([javac --version] exibe [javac 25.0.4]). Não precisaremos dele: o compilador Kotlin gera o bytecode por conta própria. Mas ele está ali, e um projeto Gradle pode misturar sem problemas arquivos Kotlin e Java, que trabalham juntos.
2.1.2. Os comandos do JDK
Aqui estão os comandos do JDK que usaremos:
Comando | Função |
[java -jar program.jar] | Executa o programa contido em um arquivo [.jar] cujo manifesto especifica a classe principal |
[java -cp classes MyClass] | executa a função [main] de uma classe compilada, procurada no caminho de classes ([-cp], “class path”) |
[javap -cp classes MyClass] | exibe os membros de uma classe compilada: usaremos isso para ver o que o compilador Kotlin produziu |
[jar] | cria ou lê um arquivo [.jar] (um arquivo ZIP de classes compiladas) |
O JDK também fornece o interpretador interativo [jshell], mas ele só aceita instruções Java. Para testar uma expressão Kotlin sem escrever um programa, use, em vez disso, as ferramentas do IntelliJ IDEA descritas adiante.
2.2. O compilador Kotlin de linha de comando
2.2.1. Instalação
Esta instalação é opcional: os projetos Gradle não a exigem, e o IntelliJ IDEA inclui seu próprio compilador. Ela permite compilar e executar um arquivo Kotlin isolado a partir de um terminal, sem criar um projeto.
O compilador pode ser baixado da página de versões do projeto Kotlin, mais precisamente no GitHub (https://github.com/JetBrains/kotlin/releases): na seção “Assets” da versão 2.4.20, baixe o arquivo [kotlin-compiler-2.4.20.zip]. Descompacte-o em uma pasta, por exemplo [C:\Program Files\kotlinc], e adicione a subpasta [bin] ao [PATH] (Windows: “Editar as variáveis de ambiente do sistema”). Você também pode usar um gerenciador de pacotes: [scoop install kotlin] no Windows (com o Scoop), ou o SDKMAN! no Linux e no macOS ([sdk install kotlin 2.4.20]). O compilador exige um JDK, que ele localiza pela variável [JAVA_HOME] ou pela variável [PATH] .
Verifique a instalação em um novo terminal:
A versão do compilador (2.4.20) é seguida da versão da JVM que o executa (JDK 25).
2.2.2. Comandos do compilador
O diretório [bin] contém dois comandos principais, [kotlinc] (o compilador) e [kotlinr] (o launcher, “runner”):
Comando | Função |
[kotlinc File.kt -d classes] | compila um ou mais arquivos-fonte e coloca os arquivos [.class] resultantes na pasta [classes]. |
[kotlinc File.kt -include-runtime -d prog.jar] | compila e produz um arquivo executável chamado [.jar], que contém também a biblioteca padrão de Kotlin |
[kotlinr -cp classes MyClass] | como [java -cp classes MyClass], acrescentando a biblioteca padrão de Kotlin ao classpath |
[kotlinr script.main.kts] | executa um script Kotlin (arquivo [.main.kts]), sem etapa de compilação visível |
Um script Kotlin é uma sequência de instruções executadas de cima para baixo, sem uma função [main]. Por exemplo, o seguinte script [essai.main.kts]:
é executado assim:
Antes do Kotlin 2.4.20, o launcher se chamava [kotlin]; ele foi renomeado para [kotlinr] no Kotlin 2.4.20 para evitar um conflito de nome com outro comando, [kotlin], que pertence à ferramenta “Kotlin Toolchain”. O nome antigo ainda funciona na versão 2.4.20 do compilador (não está oficialmente obsoleto), mas a documentação de Kotlin agora recomenda [kotlinr].
Sem nenhum argumento, o comando [kotlinc] costumava iniciar um interpretador interativo (um “REPL”, equivalente ao [jshell]). Esse recurso agora está obsoleto:
Para experimentar algumas linhas de Kotlin, use então um arquivo de rascunho (scratch file) criado com o IntelliJ IDEA (“File / New / Scratch File”, linguagem Kotlin), que exibe os resultados ao lado de cada linha.
2.3. Gradle
2.3.1. O papel do Gradle
Uma aplicação real usa bibliotecas que não fazem parte do JDK nem da biblioteca padrão de Kotlin: um driver de banco de dados, um framework de testes, Hibernate, Spring, corrotinas… Elas são distribuídas como arquivos [.jar] por meio de um repositório público, o Maven Central (https://central.sonatype.com). Uma ferramenta de build lê a descrição do projeto para determinar de quais bibliotecas ele precisa, baixa-as (junto com as bibliotecas das quais elas dependem) e então compila, testa e empacota o projeto.
As duas grandes ferramentas de build do mundo Java são o Maven (usado pelo curso de Java no qual este documento se baseia) e o Gradle. Kotlin pode ser usada com ambas, mas o Gradle é o padrão de fato no ecossistema Kotlin: ele é usado pelo Android e pelos projetos Kotlin criados pelo IntelliJ IDEA, e seus arquivos de build são escritos... em Kotlin. Este documento usa o Gradle 9.8.
2.3.2. O Gradle wrapper: nenhuma instalação necessária
Não é necessário instalar o Gradle. Cada projeto deste documento acompanha o wrapper do Gradle, um pequeno launcher composto de três arquivos situados na raiz do projeto:
- [gradlew]: o script de execução para Linux e macOS ([./gradlew]);
- [gradlew.bat]: o mesmo script para Windows ([gradlew]);
- a pasta [gradle/wrapper], que contém o programa launcher ([gradle-wrapper.jar]) e sua configuração ([gradle-wrapper.properties]).
O arquivo [gradle-wrapper.properties] especifica a versão do Gradle a usar:
Na primeira execução, o [gradlew] baixa essa versão do Gradle e a armazena no computador; nas execuções seguintes, ele a usa diretamente. Cada projeto usa, assim, a versão do Gradle com a qual foi escrito, independentemente da versão que possa estar instalada no computador. O Gradle precisa apenas de um JDK para funcionar, que ele encontra pela variável [JAVA_HOME] ou pela variável [PATH] .
Neste documento, os comandos são escritos no formato do Windows ([gradlew build]); no Linux ou no macOS, escreve-se [./gradlew build]. No PowerShell, é preciso escrever também [.\gradlew build].
Se mesmo assim você quiser usar o comando [gradle] (para criar um projeto com [gradle init], por exemplo), baixe o arquivo [gradle-9.8.0-bin.zip] em https://gradle.org/releases, descompacte-o e adicione a subpasta [bin] ao [PATH]; ou use [scoop install gradle] ou [sdk install gradle]. Depois verifique a instalação:
Esses resultados foram obtidos no Linux. A linha [Kotlin:] indica a versão de Kotlin integrada ao Gradle, que é usada para ler os arquivos de build [.gradle.kts]: ela é independente da versão do compilador Kotlin usada para compilar nossos programas (2.4.20), que é definida por cada projeto. A linha [Launcher JVM] indica o JDK que executa o Gradle.
2.3.3. Comandos do Gradle
O comando [gradlew] é seguido de uma ou mais tarefas; ele é digitado no diretório raiz do projeto, aquele que contém o arquivo [settings.gradle.kts]:
Comando | Função |
[gradlew build] | compila o código-fonte de [src/main/kotlin], executa os testes e cria o arquivo [.jar] do projeto em [build/libs] |
[gradlew run] | compila e depois executa a classe principal do projeto (plugin [application]) |
[gradlew test] | compila e depois executa os testes unitários de [src/test/kotlin] (Capítulo 6) |
[gradlew clean] | exclui a pasta [build]. |
[gradlew tasks] | exibe a lista de tarefas disponíveis no projeto |
[gradlew installDist] | cria uma versão instalável do programa em [build/install]: seus arquivos e scripts de execução |
[gradlew bootRun] | executa uma aplicação Spring Boot (Capítulo 13) |
As tarefas são interdependentes: executar [run] também aciona a compilação, e o Gradle só reexecuta as partes que mudaram desde o build anterior. A opção [-q] (“quiet”) suprime as mensagens do Gradle e exibe apenas as do programa executado; a opção [-Pname=value] define uma propriedade que o arquivo de build pode ler: vamos usá-la para escolher qual programa executar. Os argumentos do programa iniciado por [run] são passados pela opção [--args="a b"].
O primeiro comando executado em um projeto é lento: o Gradle inicia um processo em segundo plano (o “daemon” do Gradle), que permanece ativo por algumas horas para acelerar os comandos seguintes, e baixa o que o projeto precisa.
2.3.4. Maven Central e o cache do Gradle
As bibliotecas baixadas pelo Gradle são armazenadas localmente no cache do Gradle, na pasta [%USERPROFILE%\.gradle\caches] (Linux e macOS: [~/.gradle/caches]). Elas são baixadas uma única vez e depois reutilizadas por todos os projetos. Portanto, é necessária uma conexão com a Internet no primeiro build de um projeto. A mesma pasta [.gradle] contém, em [wrapper/dists], as versões do Gradle baixadas pelo wrapper.
Uma biblioteca é identificada por suas coordenadas: três nomes separados por dois-pontos: o grupo (muitas vezes um nome de domínio invertido, como [org.hibernate.orm]), o nome da biblioteca e sua versão, por exemplo [tools.jackson.core:jackson-databind:3.1.5]. Essas coordenadas são o que você informa no arquivo de build de um projeto, e podem ser encontradas pesquisando a biblioteca no site do Maven Central.
2.3.5. A sintaxe Kotlin: a DSL
O arquivo de build do projeto chama-se [build.gradle.kts]. A extensão [.kts] indica que se trata de um script Kotlin: o arquivo é escrito em uma linguagem dedicada (“DSL”, “Domain Specific Language”) construída com a sintaxe de Kotlin. O Gradle também aceita arquivos [build.gradle] escritos em Groovy, que se encontram em projetos mais antigos; desde o Gradle 8.2, a DSL Kotlin é o formato padrão. Eis um trecho típico:
Mesmo sem conhecer Kotlin ainda, você pode ler este texto como uma configuração:
- um nome seguido de um bloco entre chaves ([plugins { ... }], [dependencies { ... }]) é uma seção da configuração. Em Kotlin, trata-se de uma chamada de função que recebe um bloco de código como parâmetro (uma lambda, Capítulo 7);
- [kotlin("jvm")] e [implementation("...")] são chamadas de função; as strings são delimitadas por aspas duplas;
- [version = "1.0"] atribui um valor a uma propriedade do projeto.
Uma vantagem desse formato é que o IntelliJ IDEA o reconhece como código Kotlin: ele oferece autocompletar e sinaliza erros enquanto você digita.
2.4. O editor
2.4.1. IntelliJ IDEA
IntelliJ IDEA, da empresa JetBrains, é o editor recomendado para este documento. A JetBrains é também a empresa que desenvolveu Kotlin (a primeira versão estável da linguagem saiu em 2016) e continua a desenvolvê-la: o suporte a Kotlin está integrado ao IntelliJ IDEA, sem necessidade de extensões, e é a versão que acompanha mais de perto a evolução da linguagem. Seus recursos básicos, mais que suficientes para este documento, são gratuitos.
O IntelliJ IDEA reconhece projetos Gradle: selecione “File / Open” e escolha a pasta que contém o arquivo [settings.gradle.kts]; o IntelliJ inicia o Gradle para ler o projeto (você pode acompanhar o processo na janela “Build”), baixa as bibliotecas e depois exibe uma visão “Gradle” que dá acesso a todas as tarefas do projeto. Você pode então executar um programa clicando no triângulo verde na margem ao lado de sua função [main] ([Ctrl-Shift-F10]), ou executar um teste clicando no mesmo triângulo ao lado da função de teste. Você especifica o JDK a usar em “File / Project Structure / SDK”; em um projeto Gradle, em geral é a declaração [jvmToolchain(25)] do projeto (veja adiante) que define o JDK para a compilação.
O IntelliJ IDEA também oferece recursos específicos de Kotlin: conversão automática de um arquivo Java para Kotlin (“Code / Convert Java File to Kotlin File”, ou simplesmente colando código Java em um arquivo Kotlin), exibição do bytecode gerado pelo compilador (“Tools / Kotlin / Show Kotlin Bytecode”) e os arquivos de rascunho mencionados anteriormente.
2.4.2. VS Code
VS Code é um editor gratuito e multiplataforma. Para programar em Kotlin, instale a extensão Kotlin publicada pela JetBrains (vá ao menu “Extensions”, procure “Kotlin” e selecione aquela cujo publicador é a JetBrains). Essa extensão oficial é recente: ela usa o mesmo mecanismo de análise de código do IntelliJ IDEA e pode importar projetos Gradle, mas ainda não oferece todos os recursos do IDE da JetBrains, e sua funcionalidade muda de uma versão para outra. Consulte a página da extensão para ver o que ela suporta no momento da instalação. Para os fins deste documento, ela serve para ler e editar programas; você sempre pode executá-los no terminal integrado (“Terminal / New Terminal”) com os comandos [gradlew] fornecidos no texto.
No VS Code, abra a pasta de um capítulo ("File / Open Folder"), por exemplo a pasta [kotlin-oct-2026/03-basics].
2.4.3. Android Studio
Kotlin é também a linguagem recomendada pelo Google para aplicativos Android. O Android Studio, construído sobre o IntelliJ IDEA, é dedicado a esse tipo de aplicativo, que não é abordado neste documento.
No restante deste documento, as operações são descritas com os comandos [java], [kotlinc] e [gradlew], que produzem os mesmos resultados qualquer que seja o editor.
2.5. Um programa de exemplo: o arquivo Hello.kt
2.5.1. O programa
Um programa Kotlin pode ser simplesmente um arquivo contendo uma função chamada [main], sem declaração de classe. Vamos criar o seguinte arquivo, [Hello.kt] (na pasta de exemplos [02-installation] ):
Comentários:
- linha 1: um comentário. Tudo o que segue [//] até o fim da linha é ignorado pelo compilador;
- linha 2: a função [main], o ponto de entrada do programa. A palavra-chave [fun] introduz uma função. Ela é declarada no nível do arquivo (“top-level function”), fora de qualquer classe; não precisa ser declarada como [public] (essa é a visibilidade padrão em Kotlin) nem precisa receber argumentos do programa;
- linha 3: a única instrução do programa: ela imprime uma linha de texto na tela. A função [println] (e [print], que não passa para a linha seguinte) faz parte da biblioteca padrão de Kotlin; é o equivalente de [System.out.println] em Java. Observe a ausência de ponto e vírgula ao final da instrução: ele é opcional em Kotlin e não se escreve.
O programa é um pouco mais simples que seu equivalente no curso de Java ([void main() { IO.println(...); }]), mas a diferença real está em outro ponto: a função de nível superior [main] existe em Kotlin desde a sua primeira versão, ao passo que Java só a aceita desde o Java 25.
2.5.2. Compilação e execução
Compilamos o programa com o [kotlinc], especificando um arquivo executável chamado [.jar], e depois o executamos com o comando [java] do JDK:
- [-d hello.jar]: o destino da compilação. Se terminar em [.jar], o compilador produz um arquivo; caso contrário, é uma pasta na qual ele armazena os arquivos [.class];
- [-include-runtime]: o arquivo contém também a biblioteca padrão de Kotlin ([kotlin-stdlib]), de que os programas Kotlin precisam em tempo de execução, e um manifesto que especifica a classe principal. O programa pode assim ser executado por [java -jar] em qualquer máquina equipada com o JDK (ou JRE), mesmo que Kotlin não esteja instalada nela. Em contrapartida, o arquivo tem mais de 5 MB, compostos principalmente pela biblioteca padrão;
- a compilação leva alguns segundos: o compilador Kotlin, que é ele próprio um programa Java, precisa primeiro iniciar. O Gradle e o IntelliJ IDEA evitam essa sobrecarga mantendo um compilador ativo entre as compilações.
Não há em Kotlin um equivalente ao comando Java [java Hello.java], que compila e executa um arquivo-fonte em uma única etapa; o equivalente mais próximo é o script [.main.kts] apresentado acima.
2.5.3. O que o compilador produz
A Máquina Virtual Java (JVM) só reconhece classes: uma função não pode existir fora de uma classe. O compilador Kotlin, portanto, envolve as funções de nível superior de um arquivo em uma classe que ele gera, dando-lhe o nome do arquivo seguido de [Kt]. Para [Hello.kt], a classe gerada é [HelloKt]. O comando [javap] do JDK exibe seus membros:
- A classe [HelloKt] é [public final];
- ela contém nossa função [main], que se tornou um método estático sem parâmetros;
- e um segundo método, [main(String[])], acrescentado pelo compilador: é o método [public static void main(String[] args)] que a máquina virtual sabe invocar. Ele simplesmente chama o primeiro. Voltaremos a esse mecanismo no Capítulo 3.
É esse nome de classe que identifica o programa a executar: o manifesto de [hello.jar] contém a linha [Main-Class: HelloKt], e também se pode escrever [java -cp hello.jar HelloKt].
Diferentemente de Java, não há restrições quanto ao nome do arquivo: ele não precisa ser um identificador válido nem coincidir com o nome de uma classe que contenha. Um arquivo chamado [first-try.kt] é aceito, e sua classe gerada se chama [First_tryKt] (o compilador coloca a primeira letra em maiúscula e substitui os caracteres proibidos em um identificador por [_]). Por convenção, porém, os arquivos recebem nomes que começam com letra maiúscula e não contêm hifens, como [Hello.kt] ou [Basics01.kt].
No Windows, os caracteres acentuados escritos com [println] aparecem corretamente no terminal: a máquina virtual converte o texto para a codificação do terminal. Os arquivos-fonte devem ser salvos em UTF-8, a codificação padrão do VS Code e do IntelliJ IDEA, e a que o compilador Kotlin sempre assume. A situação é diferente quando o programa é iniciado pelo Gradle ([gradlew run], ou o triângulo verde em um projeto Gradle): sua saída deixa de ser um console e passa a ser um pipe para o Gradle, e a máquina virtual a codifica então na codificação histórica do Windows (windows-1252), de modo que o IntelliJ IDEA, que espera UTF-8, exibe um caractere substituto (um losango com um ponto de interrogação) no lugar de cada caractere acentuado. Os projetos do curso resolvem esse problema em seu arquivo [build.gradle.kts] (veja a próxima seção). Para o terminal integrado do IntelliJ IDEA (PowerShell), você também pode mudar o console para UTF-8 digitando [chcp 65001] no início da sessão, ou de uma vez por todas especificando [powershell.exe -NoExit -Command "[Console]::OutputEncoding = [Text.Encoding]::UTF8"] como interpretador em “File / Settings / Tools / Terminal / Shell path”.
O comando [kotlinc] serve para programas de um único arquivo que usam apenas a biblioteca padrão. Assim que um programa exige uma biblioteca externa, é preciso baixá-la, junto com as bibliotecas das quais ela depende, e passá-la ao compilador e depois à máquina virtual: isso implica criar um projeto Gradle. É o que faremos em todos os exemplos deste documento.
2.6. Um projeto Gradle
2.6.1. Estrutura do projeto
Um projeto Gradle é uma pasta que contém um arquivo de build chamado [build.gradle.kts] e arquivos-fonte organizados segundo uma estrutura de diretórios padrão. A raiz de um build Gradle contém também um arquivo chamado [settings.gradle.kts], que informa o nome do build e a lista dos projetos que ele agrupa, além do wrapper. A pasta [02-installation] dos exemplos é um build que agrupa dois projetos, [FirstProgram] e [TwoHands]:
- [src/main/kotlin] contém os arquivos-fonte do programa; [src/main/resources] conteria os arquivos de dados ou de configuração a serem colocados junto às classes compiladas; [src/test/kotlin] conteria os testes (Capítulo 6);
- Em [src/main/kotlin], a estrutura de pastas espelha a dos pacotes (Capítulo 4): o arquivo [Main.kt] do pacote [first] fica na pasta [first]. Kotlin não impõe essa correspondência, ao contrário de Java, mas a recomenda, e nós a seguiremos sempre;
- O arquivo [Hello.kt] não pertence a nenhum projeto: ele foi colocado ali para ser compilado pelo [kotlinc], e o Gradle o ignora.
Um projeto isolado (não agrupado com outros) tem a mesma estrutura, com seus próprios arquivos [settings.gradle.kts] e do wrapper: é o caso do projeto do Capítulo 3. Você pode criar essa estrutura de diretórios manualmente ou deixar que o IDE a crie (IntelliJ: “File / New / Project”, selecionando “Kotlin” como linguagem e “Gradle” como sistema de build, com a DSL Kotlin).
Veremos os arquivos da raiz na próxima seção. O arquivo [build.gradle.kts] do projeto [FirstProgram] é o seguinte:
Comentários:
- linha 1: um comentário. O arquivo de build é escrito em Kotlin: os comentários se escrevem como em um programa;
- linhas 2–7: os plugins aplicados ao projeto. Eles fornecem ao Gradle as tarefas de que precisamos:
- linha 4: o plugin Kotlin para a JVM. Ele adiciona tarefas que compilam os arquivos de [src/main/kotlin] e acrescenta automaticamente a biblioteca padrão de Kotlin às dependências do projeto. A notação [kotlin("jvm")] é uma forma abreviada do identificador completo do plugin, [org.jetbrains.kotlin.jvm]. Sua versão não é especificada aqui porque o projeto faz parte de um build com vários projetos, em que o projeto raiz define essa versão para todos eles (veja a próxima seção). Em um projeto isolado, você escreveria [kotlin("jvm") version "2.4.20"]: essa versão determina a versão do compilador Kotlin usada;
- linha 6: o plugin [application], que adiciona as tarefas [run] (executar o programa) e [installDist] (preparar uma versão instalável);
- linhas 10–11: os identificadores do projeto, grupo e versão, que o identificam por seu nome ([FirstProgram], o nome de sua pasta). São também os identificadores que outro projeto poderia usar para referenciar este, de modo semelhante ao de uma biblioteca do Maven Central (Capítulo 6);
- linhas 14–15: o repositório onde o Gradle procura as bibliotecas do projeto, neste caso o Maven Central;
- linhas 18–20: as bibliotecas usadas pelo projeto. Este projeto não usa nenhuma, além da biblioteca padrão de Kotlin que o plugin Kotlin adiciona automaticamente;
- linha 24: o toolchain do projeto: o código é compilado para Java 25 e executado por [gradlew run] com um JDK 25, ainda que o próprio Gradle seja executado por outro JDK. O Gradle procura esse JDK entre os instalados na máquina. Se não encontrar nenhum, falha com a mensagem de erro [Cannot find a Java installation on your machine ... matching: {languageVersion=25 ...}], a menos que o build declare o plugin [foojay-resolver-convention], o que todos os projetos do curso fazem (veja a próxima seção): o Gradle então baixa por conta própria um JDK 25. No IntelliJ IDEA, você também pode instalar esse JDK por “File / Project Structure / SDK / Add SDK / Download JDK”;
- linha 27: um aviso do compilador é tratado como erro e interrompe a compilação. O compilador Kotlin sinaliza muitos problemas (variáveis não usadas, conversões de tipo desnecessárias, operadores [!!] supérfluos etc.): queremos programas que não produzam nenhum deles;
- linha 29: o compilador preserva os nomes dos parâmetros das funções no bytecode. Algumas bibliotecas se valem disso, por exemplo o Jackson para criar um objeto a partir de um documento JSON (Capítulo 5) ou o Spring (Capítulo 13);
- linhas 33–35: a classe cuja função [main] é executada por [gradlew run]. O nome é o da classe gerada pelo compilador para o arquivo [Main.kt] do pacote [first]: [first.MainKt];
- linhas 38–41: todas as tarefas que executam um programa Java ([JavaExec]), como [run], recebem duas opções da máquina virtual: a saída em tela do programa ([System.out], [System.err]) é codificada em UTF-8. Sem elas, os caracteres acentuados escritos pelo programa seriam corrompidos no console do IntelliJ IDEA no Windows (veja a observação sobre acentos acima). [tasks.withType<JavaExec>()] refere-se a todas as tarefas desse tipo, e [configureEach { … }] configura cada uma delas. Todos os projetos do curso que executam um programa contêm essa configuração.
Este projeto não usa nenhuma biblioteca. Um projeto que usa uma biblioteca a declara na seção [dependencies] por meio de suas coordenadas, como faremos a partir do Capítulo 5:
O termo [implementation] indica que a biblioteca é necessária para compilar e executar o programa. Você também encontrará [runtimeOnly] (necessária apenas na execução, como um driver de banco de dados) e [testImplementation] (necessária apenas nos testes). O Gradle então baixará [jackson-databind] e as bibliotecas das quais ele depende.
O arquivo [Main.kt] contém o programa:
- linha 1: o arquivo pertence ao pacote [first]. O nome completo da classe gerada para este arquivo é, portanto, [first.MainKt];
- linhas 4–6: a função [main], na mesma forma que em [Hello.kt]. Um arquivo Kotlin pode conter qualquer número de funções e classes, públicas ou não: o nome do arquivo não depende de seu conteúdo.
2.6.2. Compilação e execução
O comando [gradlew build], digitado na pasta [02-installation], compila os projetos do build (e executaria seus testes, se tivessem): o Gradle baixa o plugin Kotlin, o compilador e a biblioteca padrão conforme a necessidade, depois compila os arquivos de [src/main/kotlin] e coloca as classes resultantes na pasta [build/classes/kotlin/main] de cada projeto, preservando a estrutura de pacotes ([FirstProgram/build/classes/kotlin/main/first/MainKt.class]).
O comando [gradlew run] compila um projeto e depois o executa. Em um build com vários projetos, o projeto é indicado por seu caminho, precedido de dois-pontos: [:FirstProgram:run] é a tarefa [run] do projeto [FirstProgram]. Com a opção [-q], apenas a saída do programa é exibida:
Você também pode ir até a pasta do projeto e digitar [..\gradlew -q run]: o Gradle sobe até o arquivo [settings.gradle.kts] do diretório raiz e executa a tarefa [run] do projeto da pasta atual. Por outro lado, digitar [gradlew run] no diretório raiz executaria a tarefa [run] de todos os projetos que a possuem.
Depois que o projeto foi compilado, você também pode executar a classe diretamente com o comando [java], especificando o local das classes (na pasta [FirstProgram]):
Isso funciona aqui porque este programa, na verdade, não usa nada da biblioteca padrão de Kotlin em tempo de execução: o compilador substitui a chamada a [println] por uma chamada direta a [System.out.println]. No entanto, um programa que use, por exemplo, uma lista ([listOf(1, 2, 3)]) falha dessa maneira com o erro [java.lang.NoClassDefFoundError: kotlin/collections/CollectionsKt]: a classe [CollectionsKt] da biblioteca padrão não é encontrada. É preciso então adicionar o arquivo [kotlin-stdlib-2.4.20.jar] ao classpath (ele está no cache do Gradle; a pasta [lib] do compilador [kotlinc] também o contém, com o nome [kotlin-stdlib.jar]): [java -cp "build/classes/kotlin/main;path/kotlin-stdlib-2.4.20.jar" first.MainKt] no Windows (o separador é [:] no Linux e no macOS). O comando [kotlinr -cp build/classes/kotlin/main first.MainKt] do compilador de linha de comando faz isso por nós.
O modo mais fácil é pedir ao Gradle que construa o programa e tudo de que ele precisa com a tarefa [installDist] do plugin [application]:
Ela cria a pasta [FirstProgram/build/install/FirstProgram], que contém uma pasta [lib] (o arquivo do projeto, a biblioteca padrão de Kotlin e, se for o caso, as demais bibliotecas do projeto) e uma pasta [bin] com dois scripts de execução, [FirstProgram] (Linux, macOS) e [FirstProgram.bat] (Windows), que chamam o [java] com o classpath correto. Dessa forma, um programa é entregue de modo que possa ser copiado para outro computador que tenha o JDK:
A pasta [build] pode ser excluída sem risco ([gradlew clean]): ela é recriada na próxima compilação. O comando [gradlew build] também produz o arquivo do projeto [build/libs/FirstProgram-1.0.jar], que contém apenas suas próprias classes.
2.7. Um projeto com vários módulos
2.7.1. O build com vários projetos
Um build Gradle pode agrupar vários projetos, chamados de seus subprojetos (ou módulos). O arquivo [settings.gradle.kts] do diretório raiz os lista. O da pasta [02-installation] é o seguinte:
- linhas 3–6: um plugin para o próprio build (não para um projeto), [foojay-resolver-convention]: quando um projeto pede um JDK por meio de [jvmToolchain(25)] que o Gradle não encontra na máquina, o Gradle o baixa do serviço foojay.io e o armazena em seu cache. A primeira execução demora um pouco mais, mas o aluno não precisa mais ter o JDK correto instalado. O bloco [plugins] deve ser o primeiro do arquivo. Todos os builds do curso declaram esse plugin;
- linha 8: o nome do build (o projeto raiz). Sem essa linha, seria o nome da pasta;
- linha 11: os subprojetos, identificados pelos nomes de suas pastas. Um subprojeto pode estar aninhado mais profundamente: [include("TaxV5:tax-dao")] refere-se ao projeto da pasta [TaxV5/tax-dao] (Capítulo 6).
O projeto raiz também tem um arquivo chamado [build.gradle.kts]:
- linhas 3–4: o plugin Kotlin é declarado, junto com sua versão, mas não é aplicado ao projeto raiz ([apply false]), que não contém código a compilar. Essa declaração torna o plugin disponível para os subprojetos, que o aplicam por meio de [kotlin("jvm")] sem repetir a versão: todos os subprojetos usam assim a mesma versão de Kotlin, que pode ser alterada em um único lugar. Se cada subprojeto declarasse por conta própria a versão do plugin, o Gradle o carregaria várias vezes, o que o plugin Kotlin desaconselha.
Na pasta [02-installation], o comando [gradlew build] compila os dois projetos; um IDE que abre essa pasta enxerga os dois projetos de uma vez. No Capítulo 6, veremos que um subprojeto pode depender de outro ([implementation(project(":TaxV5:tax-dao"))]), e, nos Capítulos 10 a 13, veremos que um build pode até reutilizar projetos de outro build ([includeBuild]).
2.7.2. Um projeto com várias funções main
Um projeto pode conter vários arquivos, cada um com uma função [main]: cada uma é um possível ponto de entrada, e a classe a executar é escolhida em tempo de execução. O projeto [TwoHands] contém dois arquivos do pacote [twohands]. O arquivo [P1.kt]:
e o arquivo [P2.kt], idêntico, exceto pelo nome. As duas funções se chamam [main] e pertencem ao mesmo pacote: não há conflito porque ficam em duas classes diferentes, [twohands.P1Kt] e [twohands.P2Kt]. O comando [java] executa a classe que lhe for indicada (na pasta [TwoHands], depois que o projeto foi compilado):
Para o comando [gradlew run], o arquivo [build.gradle.kts] do projeto especifica a classe a executar:
- linha 5: a classe executada é indicada pela propriedade [main] do Gradle, fornecida na linha de comando pela opção [-Pmain=...]. A função [providers.gradleProperty("main")] lê essa propriedade; [orElse(...)] especifica o valor a usar se ela não tiver sido fornecida: neste caso, a classe [twohands.P2Kt].
O restante do arquivo é igual ao de [FirstProgram], com o acréscimo de uma configuração para a tarefa [run] ([standardInput = System.in]), que transmite a entrada do teclado ao programa: sem ela, um programa iniciado por [gradlew run] não consegue ler o teclado.
Resultados:
Isso permite escolher o programa a executar sem modificar o arquivo [build.gradle.kts]. Com o IntelliJ IDEA, o problema não existe: cada função [main] tem seu próprio triângulo verde na margem.
2.7.3. Um pacote por programa
Os projetos dos capítulos seguintes usam todos esse mecanismo, já que cada um contém muitos programas pequenos. Para evitar que esses programas interfiram uns nos outros, este documento segue uma convenção simples: cada programa tem seu próprio pacote, que leva seu nome em minúsculas e fica em uma pasta de mesmo nome. Assim, o programa [Basics04.kt] do Capítulo 3 é o arquivo [03-basics/src/main/kotlin/basics04/Basics04.kt], que começa com a linha [package basics04]; sua classe é [basics04.Basics04Kt], e ele é executado da seguinte forma:
Há duas razões para essa convenção:
- todos os programas de um projeto são compilados juntos. Se estivessem no mesmo pacote, dois programas não poderiam declarar uma função ou uma classe com o mesmo nome (uma função [display], uma classe [Person]…): o compilador relataria uma declaração duplicada. Com um pacote por programa, cada um tem seu próprio espaço de nomes;
- um programa composto de vários arquivos é simplesmente um pacote que contém vários arquivos: no Capítulo 4, o pacote [persons] contém a classe [Person] em [Person.kt] e o programa principal em [Main.kt], que é executado por [-Pmain=persons.MainKt].
O texto de cada capítulo indica, antes dos resultados de um programa, o comando exato que o executa. Voltaremos a essa estrutura no Capítulo 3.
2.8. Exemplos deste documento
Para executar os exemplos deste documento:
- baixe a pasta [kotlin-oct-2026] (link no início do documento). Ela contém uma pasta por capítulo ([02-installation], [03-basics], [04-classes]…), e cada uma dessas pastas é um build Gradle, completo, com seu wrapper: um único projeto ou vários subprojetos agrupados pelo arquivo [settings.gradle.kts];
- abra a pasta de um capítulo no IntelliJ IDEA (“File / Open”); depois execute um programa clicando no triângulo verde ao lado de sua função [main];
- ou, em um terminal situado na pasta do capítulo, execute um programa com [gradlew -q run -Pmain=package.ClassKt] (com o caminho do subprojeto antes de [run] se houver vários subprojetos); o texto de cada capítulo indica o comando exato.
O primeiro comando [gradlew] de um capítulo exige acesso à Internet: o Gradle então baixa sua própria distribuição, o plugin Kotlin e as bibliotecas do projeto, que em seguida armazena em seu cache.
Os Capítulos 10 e 11 usam um banco de dados chamado MySQL; a instalação do MySQL com o [Laragon] é descrita no apêndice.