Kotlin - Amper

Amper és una eina de construcció per als llenguatges Kotlin i Java.

• Introducció
• IDEA
• Amper CLI
• Dependències
• Configurar Java i Kotlin
• UI Compose
• Modularitzar
• Kotlin Symbol Processing
• TODO

Introducció

IDEA

Obre l’editor Idea i instal·la el plugin d’Amper.

Crea un projecte “JVM console application”:

Els fitxers main.kt i WorldTest.kt són fitxers Kotlin normals sense res especial.

La part interessant és el module.yaml, que és el fitxer de configuració del mòdul Amper.

product: jvm/app

Com que has creat un projecte JVM simple, el contingut del fitxer és mínim.

Tens més informació a Using Amper in IntelliJ IDEA

Amper CLI

Quan crees el projecte, la IDE baixa les últimes versions dels scripts amper.

De totes maneres obre un terminal Alt + F12.

Actualitza els scripts d’Amper i la distribució a l’última versió publicada.

./amper update

L’script és un petit fitxer que descarrega i executa la distribució real de la CLI d’Amper, i serveix com a punt d’entrada per a totes les comandes d’Amper.

La primera vegada que executes l’script d’Amper, trigarà una estona a descarregar la distribució de la CLI d’Amper.

Les execucions posteriors seran més ràpides, ja que els fitxers descarregats es guardaran localment en cache.

Fetching latest Amper version info...
Latest Amper version is 0.7.0
Downloading Amper scripts...
Download complete.
Amper is already in version 0.7.0, nothing to update

Per executar el fitxer src/main.kt has d’executar amper run:

./amper run

Si no tens insta·lat un entorn d’execució amper en baixa un per tu de manera automàtica:

Logs are in file://C:\Users\david\Workspace\amper\build\logs\amper_2025-09-18_11-57-47_10940_run

00:02.705 INFO  :amper:compileJvm         Compiling module 'amper' for platform 'jvm'...
Hello, World!
00:05.636 INFO  :amper:runJvm             Process exited with exit code 0

L’ordre ./amper i totes les subordres admeten l’opció -h (o --help) per explorar què és possible:

./amper --help

Ordres útils:

Dependències

Un projecte necessita moltes funcionalitats que no estan a les biblioteques estàndards.

Afegim una dependència d’una biblioteca Kotlin des del repositori Maven:

product: jvm/app
dependencies:
  - org.jetbrains.kotlinx:kotlinx-datetime:0.6.2

We can now use this library in the main.kt file:

import kotlinx.datetime.*

fun main() {
    println("Hello, ${World.get()}!")
    println("It's ${Clock.System.now().toLocalDateTime(TimeZone.currentSystemDefault())} here")
}

Per exemple, si vull crear gràfics puc utilitzar la biblioteca Kandy.

Afegeix una dependència amb “Kandy”:

product: jvm/app

dependencies:
  - org.jetbrains.kotlinx:kandy-lets-plot:0.7.1
  - org.jetbrains.kotlinx:kotlinx-datetime:0.6.2

Modifica el fitxer main.kt per crear un diagrama de barres:

import org.jetbrains.kotlinx.dataframe.api.*
import org.jetbrains.kotlinx.kandy.dsl.*
import org.jetbrains.kotlinx.kandy.letsplot.export.save
import org.jetbrains.kotlinx.kandy.letsplot.layers.bars

fun main() {
    val averageTemperature = dataFrameOf(
        "city" to listOf("New York", "London", "Berlin", "Yerevan", "Tokyo"),
        "average temperature" to listOf(12.5, 11.0, 9.6, 11.5, 16.0)
    )

    averageTemperature.plot {
        bars {
            x("city")
            y("average temperature") {
                axis.name = "Average Temperature (°C)"
            }
        }
    }.save("plot.png", path = ".")
}

Executa l’aplicació:

./amper run

Obre el fitxer app\plot.png que s’acaba de crear.

Tutorial

TODO test-dependencies !!

Àmbits i visibilitat

Hi ha tres àmbits de dependència:

En la forma completa, pots declarar l’àmbit de la següent manera:

dependencies:
  - io.ktor:ktor-client-core:2.2.0:
      scope: compile-only
  - ../ui/utils:
      scope: runtime-only

També hi ha una forma abreujada:

dependencies:
  - io.ktor:ktor-client-core:2.2.0: compile-only
  - ../ui/utils: runtime-only

Per defecte, totes les dependències no són accessibles des del codi dependent. Per fer que una dependència sigui visible per a un mòdul dependent, cal marcar-la explícitament com a exportada.

dependencies:
  - io.ktor:ktor-client-core:2.2.0:
      exported: true
  - ../ui/utils:
      exported: true

També hi ha una forma abreujada:

dependencies:
  - io.ktor:ktor-client-core:2.2.0: exported
  - ../ui/utils: exported

Aquí tens un exemple d’una dependència només de compilació i exportada:

dependencies:
  - io.ktor:ktor-client-core:2.2.0:
scope: compile-only
exported: true

Vegeu la documentació completa sobre Dependencies.

Configurar Java i Kotlin

Una altra tasca típica és configurar els paràmetres del compilador, com el nivell del llenguatge, etc. Així és com ho fem a Amper:

product: jvm/app

dependencies:
  - org.jetbrains.kotlinx:kotlinx-datetime:0.6.2

settings:
  kotlin:
    languageVersion: 2.2  # Set Kotlin source compatibility to 2.2

Vegeu la documentació completa sobre Settings.

UI Compose

Ara, convertim l’exemple en una aplicació GUI. Per fer-ho, afegirem el framework Compose Multiplatform.

Permet construir aplicacions d’escriptori JVM simples, que són simples per ara, i prepara el camí per convertir-les en multiplataforma més endavant.

Canviem el nostre module.yaml a:

product: jvm/app

dependencies:
  - org.jetbrains.kotlinx:kotlinx-datetime:0.6.2

  # add Compose dependencies
  - $compose.foundation
  - $compose.material3
  - $compose.desktop.currentOs

settings:
  kotlin:
    languageVersion: 2.2  # Set Kotlin source compatibility to 2.2
  # enable the Compose framework toolchain
  compose:
    enabled: true

Podem llavors reemplaçar el contingut de main.kt amb el següent codi:

import androidx.compose.foundation.text.BasicText
import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application

fun main() = application {
    Window(onCloseRequest = ::exitApplication) {
        BasicText("Hello, World!")
    }
}

Exwmples:

• Compose Desktop
• Compose Android
• Compose iOS
• Compose Multiplatform

See the full documentation about [Compose](https://github.com/JetBrains/amper/blob/release/0.7/docs/Documentation.md#configuring-compose-multiplatform.

Vegeu la documentació completa sobre Compose.

Modularitzar

Un projecte Amper es defineix per un fitxer project.yaml. Aquest fitxer conté la llista de mòduls i la configuració global del projecte. La carpeta amb el fitxer project.yaml és l’arrel del projecte. Els mòduls només poden estar ubicats sota l’arrel del projecte. Si només hi ha un mòdul al projecte, no cal el fitxer project.yaml.

Un mòdul Amper és un directori amb un fitxer de configuració module.yaml, el codi font del mòdul i els recursos. Un fitxer de configuració del mòdul descriu què produir: per exemple, una biblioteca reutilitzable o una aplicació específica per a una plataforma. Cada mòdul descriu un sol producte. Diversos mòduls no poden compartir les mateixes fonts o recursos, però poden dependre els uns dels altres.

|-app/
|  |-src/
|  |  |-main.kt
|  |-...
|  |-module.yaml
|-lib/
|  |-src/
|  |  |-util.kt
|  |-module.yaml
|-project.yaml

En el cas anterior, el project.yaml es veu així:

modules:
  - app
  - lib

Consulta la referència per a més opcions per definir la llista de mòduls al fitxer project.yaml.

Dividim el nostre projecte en una aplicació JVM i un mòdul de biblioteca, amb codi compartit que reutilitzarem més tard quan fem el projecte multiplataforma.

El nostre objectiu aquí és separar la nostra aplicació en un mòdul de biblioteca shared i un mòdul d’aplicació jvm-app i aconseguir la següent estructura:

Kotlin Symbol Processing

Amper provides built-in support for KSP.

Amper is compatible with KSP2, so all processors must be updated to this version.

To add a processor to your module, use the settings.kotlin.ksp section, where you can also specify options for KSP.

Veure un exemple a Room - Bàsic

TODO

• Amper …

• Amper Documentation

• Blog

• Hello. Congrats on Amper. I’m loving it so far! Wh…

• Amper Update, May 2025 – A Standalone Build Tool for Kotlin, Server-Side and Multiplatform

• Amper: Simplifying Cross-Platform Kotlin Development

• Amper – Improving the Build Tooling User Experience