Kotlin Toolchain 0.11: O Próximo Passo para o Amper

A versão Amper 0.11.0 está disponível, e você notará uma mudança na marca do produto imediatamente. Se perdeu a keynote da KotlinConf (assista ao registro), aqui está o resumo: o Amper evoluiu para se tornar o Kotlin Toolchain e agora está em Alpha! Esta versão traz essa transição à vida, junto com a capacidade de publicar bibliotecas JVM, novos APIs para desenvolvimento de plugins e várias melhorias na experiência do desenvolvedor.

Siga adiante para os detalhes e verifique as notas de lançamento para a lista completa de alterações e correções de bugs.

Para obter suporte às últimas funcionalidades do Kotlin Toolchain, use IntelliJ IDEA 2026.1.2 (ou versão mais recente). Certifique-se de que a versão mais recente do plugin Kotlin Toolchain está instalado. 

Amper é agora o Kotlin Toolchain

Quando lançamos o Amper, a ideia era experimentar com uma experiência de build coesa e declarativa. À medida que o projeto evoluiu, ficou claro que o ecossistema não precisa apenas de outra ferramenta de build – ele precisa de um ponto de entrada unificado para toda a Kotlin.

O Kotlin Toolchain é esse ponto de entrada unificado. Ele fornece um único comando, kotlin, que permite criar um projeto, compilá-lo, executá-lo e testá-lo, além de configurar o pacote e publicação. No futuro, ele permitirá formatar seu código, gerar documentações e muito mais. Sem decisões sobre ferramentas de build no início; sem complexa configuração de plugins antes que você possa escrever sua primeira linha de código.

Claro, não começamos do zero. Tudo o que construímos dentro do Amper foi movido para o Kotlin Toolchain, permitindo ao projeto passar diretamente para Alpha! Esta etiqueta significa que a JetBrains está comprometida em apoiá-lo, e assim adoraríamos que você experimentasse e compartilhasse seu feedback.

Se você já estava usando Amper, esta grande mudança tem várias implicações que você deve estar ciente:

• Os scripts de wrapper amper e amper.bat devem ser substituídos pelos novos wrappers kotlin e kotlin.bat.
• No IntelliJ IDEA, o plugin do IDE para Kotlin Toolchain deve ser instalado em vez do plugin Amper IDE, que pode ser desinstalado com segurança.

Instalação global

Os scripts de wrapper que são comprometidos ao seu projeto são ótimos para fornecer uma experiência clone-and-build sem requisitos de instalação, mas eles não são adequados para todos os casos de uso.

Com esta nova versão, você pode agora instalar o kotlin CLI globalmente (fora do projeto) e usá-lo em qualquer lugar ao invés de ./kotlin. Você pode instalá-lo agora via SDKMAN! desta maneira:

sdk install kotlintoolchain

• Lançar comandos kotlin de dentro de diretórios aninhados no seu projeto é mais conveniente.
• Você pode usar comandos projetos-agnosticos de qualquer diretório (como kotlin tool jaeger ou kotlin clean-shared-caches).
• Criar novos projetos com o comando init é mais natural (sem a necessidade de baixar um wrapper manualmente ou copiá-lo de outro projeto).

O uso do comando global kotlin não significa que você terá que alinhar a versão da Kotlin Toolchain em todos os seus projetos. O comando kotlin automaticamente encontra o script wrapper do seu projeto e executa a versão correspondente da Kotlin Toolchain.

Publicação

A funcionalidade de publicação de bibliotecas está finalmente em preview! Você pode agora publicar suas bibliotecas JVM para repositórios Maven, incluindo o Maven Central.

Repositórios Maven regulares

Para publicar em um repositório Maven diferente do Maven Central, use a seguinte configuração no seu module.yaml:

product: jvm/lib

repositories:
  - id: myMavenRepoId
    url: https://maven.pkg.github.com/my-org/my-maven-repo 
    publish: true
    credentials:
      file: creds.properties # um arquivo de propriedades contendo suas credenciais 
      usernameKey: maven.username # o nome da propriedade contendo o nome do usuário
      passwordKey: maven.password # o nome da propriedade contendo a senha

settings:
 publishing:
   enabled: true
   group: com.example
   artifactId: greeter # opcional, padrão ao nome do módulo
   version: 1.0.0

Fornecer o arquivo de credenciais que foi referenciado na configuração do repositório, por exemplo, este creds.properties:

maven.username=john.doe
maven.password=MyVerySecurePassword123

Você pode então referenciar o repositório por ID quando executar o comando publish:

kotlin publish myMavenRepoId

Este comando publica todos os módulos que têm a publicação habilitada e declararam um repositório com o ID myMavenRepoId.

Maven Central

A publicação para o Maven Central é conhecida por ser um processo tedioso envolvendo muitas partes: JARs de fontes e javadoc, assinaturas PGP, metadados POM, checksums, etc. A última Kotlin Toolchain faz tudo isso por você – você declara o que publicar, e nós cuidamos do resto.

Você precisará primeiro de uma conta, um namespace e um token de usuário no Maven Central Publisher Portal, bem como uma chave PGP de assinatura. Para tudo mais, a Kotlin Toolchain tem você coberto.

Para publicar no Maven Central, não é necessário declarar o repositório manualmente. Basta adicionar mavenCentral: enabled à sua configuração de publicação e configurar tudo que o Maven Central requer. Aqui está um exemplo mínimo:

product: jvm/lib

description: Uma descrição significativa para este módulo específico

settings:
  publishing:
    enabled: true
    group: com.example # o grupo deve corresponder ao seu namespace Maven Central
    version: 1.0.0
    # artifactId é opcional e assume como padrão o nome do seu módulo
    mavenCentral: habilitado
    signArtifacts: true # assina automaticamente seus artefatos, sem necessidade de binário GPG externo
    publishSources: true
    pom:
      url: https://example.com
      scm: https://github.com/my-org/example.git # a conexão SCM e desenvolvimento são derivadas automaticamente deste URL
      developers:
        - name: John Doe
      licenses:
        - name: MIT
          url: https://opensource.org/license/mit

Confira a documentação para aprender como passar as credenciais necessárias para assinar artefatos e fazer upload ao Maven Central Publisher Portal. Depois disso, a publicação é apenas um comando de distância:

kotlin publish mavenCentral

Este comando constrói e assina cada artefato, os empacota em um pacote de implantação Maven Central, faz o upload do pacote e aguarda sua validação. Você pode então verificar a implantação e concluir a versão via o portal central UI. Também é possível pular a verificação manual e automatizar completamente o lançamento com publishingMode: auto, caso confie na pipeline. Confira a documentação para ler mais sobre os modos de publicação.

Suporte Cinterop

Agora o Kotlin Toolchain gera vinculações personalizadas para bibliotecas C a partir dos arquivos de definição (.def) colocados dentro da pasta cinterop do módulo.

O IDE também fornece assistência gerando vinculações durante o processo de sincronização do projeto.

Melhorias na interface de terminal

Fizemos várias melhorias na saída do comando kotlin.

Incorporamos indicadores de progresso melhores para tarefas concluídas e a barra principal de progresso está integrada com o indicador nativo do seu terminal:

Também melhoramos a maneira como os diagnósticos relatados pelo compilador Kotlin JVM são renderizados (requer Kotlin 2.4.0 ou superior):

Melhorias no IDE

Download de fontes da biblioteca

As fontes para as bibliotecas agora são baixadas automaticamente como uma atividade pós-sincronização.

Como a sincronização é concluída primeiro, você pode começar a trabalhar no projeto imediatamente enquanto as fontes são baixadas em segundo plano.

Resolução de dependências em escopo do módulo

Anteriormente, a resolução de dependências no plugin do IDE era realizada no nível do projeto, ao contrário da CLI. Isso poderia levar a uma versão incorreta de dependência em um módulo ou avisos incorretos no editor. Alinhamos o comportamento com a CLI, então agora cada módulo tem seu próprio escopo de resolução e todos os diagnósticos são iguais.

Melhorias na desenvolvimento de plugins

Várias novas funcionalidades estão disponíveis para autores de plugins locais, incluindo as novas declarações checks e commands, novos APIs para entradas de tarefas e melhorias em diagnósticos.

Novas referências

No momento da criação do plugin.yaml para conectar as entradas de tarefa, algumas referências internas podem ser usadas para acessar informações sobre o projeto. Introduzimos duas novas para cobrir alguns casos comuns:

• ${project.rootDir} pode ser usado para acessar o diretório raiz do projeto.
• ${module.classes} pode ser usado para acessar o diretório que contém os arquivos de classe compilados brutos.

Verificações personalizadas

A nova kotlin check é projetada para garantir que o projeto passe por todas as verificações de qualidade. Por padrão, ela executa os testes unitários habituais e plugins podem registrar verificações adicionais que a comando deve executar.

Para introduzir uma verificação personalizada em um plugin, use a lista top-level checks:

# my-lint-plugin/plugin.yaml
tasks:
  runLinter:
    action: !kotlinJavaLint
      sources: ${module.kotlinJavaSources}

checks:
  - name: lint
    performedBy: runLinter

A verificação lint acima também pode ser executada individualmente usando kotlin check lint.

Para listar as verificações que estão no projeto, use o comando kotlin show checks. Você pode ler mais sobre verificações personalizadas nos documentos de plugins.

Comandos personalizados

Às vezes, você precisa expor um ponto de entrada público para os usuários do seu plugin. Por exemplo, pode querer fornecer a capacidade de gerar uma lista de alterações, imprimir alguma informação sob demanda ou publicar um formato de distribuição personalizado. Como as tarefas do seu plugin devem ser consideradas privadas por padrão, introduzimos um novo conceito chamado comandos personalizados para representar esses pontos de entrada públicos.

Um comando personalizado é implementado usando uma tarefa regular e, como tal, pode obter dados do build (como arquivos fonte, JARs compilados ou informações da classpath em tempo de execução) e depender de outras tarefas. Para registrar um comando associado à sua tarefa, use a nova seção top-level commands no plugin.yaml:

# my-lint-plugin/plugin.yaml
tasks:
  updateBaseline:
    action: !runDetektForBaseline
      sources: ${module.kotlinJavaSources}
      outputFile: ${module.rootDir}/detekt/baseline.xml

commands:
  # abreviação quando o nome do comando corresponde ao da tarefa
  - updateBaseline

Você pode então executar este comando personalizado usando o novo kotlin do command:

kotlin do updateBaseline

Isso irá executar a tarefa associada ao comando, bem como suas dependências.

Para listar todos os comandos personalizados disponíveis no projeto, use kotlin show commands. Saiba mais sobre comandos personalizados nos documentos de plugins.

Uma nova maneira de registrar arquivos gerados

Introduzimos uma nova seção do nível superior no plugin.yaml chamada generated, que permite registrar fontes, recursos e classes geradas. A partir da versão 0.11.0, você pode até mesmo registrar definições de cinterop quando sua tarefa provisiona dinamicamente bibliotecas nativas:

tasks:
  generateStuff:
    action: !myGenerateStuffAction
      outputSources: ${taskOutputDir}/src
      outputResources: ${taskOutputDir}/res
      outputDefFiles: ${taskOutputDir}/cinterop

generated:
  sources:
    - directory: ${tasks.generateStuff.action.outputSources}
      language: kotlin
  resources:
    - directory: ${tasks.generateStuff.action.outputResources}
  cinteropDefinitions:
    - directory: ${tasks.generateStuff.action.outputDefFiles}

Isso substitui a propriedade markOutputAs dentro das tarefas, que está obsoleta e será removida em breve. Dessa forma, todos os outputs que contribuem de volta para o build são registrados da mesma maneira e podem ser identificados à primeira vista em suas próprias seções por humanos, agentes IA e outras ferramentas.

Outras melhorias

lib renomeado para kmp/lib

O tipo de produto lib foi renomeado para kmp/lib para melhor refletir o que representa após a introdução do tipo de produto jvm/lib. O valor lib está obsoleto e planejamos removê-lo em uma versão futura da Kotlin Toolchain.

Templates aninhados

Agora os templates podem aplicar outros templates, permitindo que você construa uma hierarquia lógica de configurações. A sintaxe é a mesma; simplesmente use a seção apply nos seus arquivos de template:

# spring.module-template.yaml
apply:
  - ./jvm.module-template.yaml

settings:
  springBoot: enabled

Suporte a classificador Maven

Agora você pode adicionar classificadores para notações de dependência Maven para depender de um artefato específico da biblioteca, por exemplo:

dependencies:
  - io.netty:netty-transport-native-epoll:4.2.13.Final:linux-x86_64

Melhorias no comando run

Aprimoramos a experiência do comando run em casos onde apenas uma opção é adequada para a máquina host.

Caso o projeto tenha múltiplos módulos, mas apenas um possa ser executado na máquina host, não é mais necessário especificar explicitamente o módulo. Por exemplo, dado o seguinte projeto:

.
├── linux-cli/
├── macos-cli/
├── windows-cli/
├── shared/
├── kotlin
├── kotlin.bat
└── project.yaml

kotlin run iniciará o módulo windows-cli em uma máquina Windows.

Caso o módulo especificado tenha múltiplas plataformas de destino e apenas uma delas possa ser executada na máquina host, não é mais necessário especificar explicitamente a plataforma. Por exemplo, dado o seguinte módulo:

# linux-app/module.yaml
product: linux/app

# As plataformas linuxArm64 e linuxX64 estão presentes por padrão

kotlin run -m linux-app iniciará a versão ARM64 do aplicativo em uma máquina ARM e a versão x86-64 do aplicativo em uma máquina x86.

Versões padrão atualizadas

Atualizamos algumas das versões padrão para ferramentas e frameworks:

• Kotlin 2.3.21
• Compose Hot Reload 1.1.1
• KSP 2.3.7
• Ktor 3.4.3
• SpringBoot 4.0.6
• Lombok 1.18.46
• JUnit Platform 6.0.3

Experimente o Kotlin Toolchain 0.11.0

Para começar com o Kotlin Toolchain, confira nosso manual de início rápido. Dê uma olhada em alguns exemplos, siga um tutorial ou leia a guia do usuário completa, dependendo do seu estilo de aprendizado.

Se você tem usado o Amper, não será possível migrar sua instalação para o Kotlin Toolchain via o caminho usual de atualização automática. Em vez disso, você deve substituir amper e amper.bat em seu projeto por wrappers do Kotlin. Você pode fazer isso instalando a ferramenta globalmente e então usando a CLI do Kotlin para gerar os novos wrappers do Kotlin no seu projeto:

kotlin update --create

Após substituir os wrappers, você poderá usar kotlin update para atualizações futuras.

Compartilhe seu feedback

O Kotlin Toolchain ainda está em desenvolvimento ativo. Você pode fornecer feedback sobre sua experiência participando da discussão no canal #kotlin-toolchain do Slack ou compartilhando suas sugestões e ideias em um problema no YouTrack. Seu input e casos de uso ajudam a moldar o futuro do Kotlin Toolchain!