Amper

Introducció

Amper …

https://gitlab.com/xtec/kotlin/data/-/packages

Amper Documentation

Entorn de treball

Crea un directori amper:

mkdir amper
cd amper

Utilitzant Amper des de la línia de comandes

Per utilitzar la CLI d’Amper, necessites descarregar l’script executable d’Amper a la carpeta arrel del teu projecte. 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.

Utilitza les següents comandes per descarregar l’script:

Invoke-WebRequest -OutFile amper.bat -Uri https://packages.jetbrains.team/maven/p/amper/amper/org/jetbrains/amper/amper-cli/0.7.0/amper-cli-0.7.0-wrapper.bat?download=true

Completa i verifica la teva instal·lació executant:

./amper -v

Nota

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.

Executa ./amper update per actualitzar els scripts d’Amper i la distribució a l’última versió publicada.

Per començar un nou projecte, simplement utilitza init:

./amper init

Selecciona “JVM console application”

Per construir i executar l’aplicació JVM “Hello, World”:

./amper run

Amper s’encarrega de baixar el JDK:

Logs are in file://C:\Users\david\Workspace\amper\build\logs\amper_2025-07-12_15-47-46_11780_run

00:17.641 INFO  :amper:compileJvm         Downloading https://corretto.aws/downloads/resources/21.0.1.12.1/amazon-corretto-21.0.1.12.1-windows-x64-jdk.zip to C:\Users\david\AppData\Local\Amper\download.cache\5de2c13edf-amazon-corretto-21.0.1.12.1-windows-x64-jdk.zip
00:23.708 INFO  :amper:compileJvm         Extracting C:\Users\david\AppData\Local\Amper\download.cache\5de2c13edf-amazon-corretto-21.0.1.12.1-windows-x64-jdk.zip to C:\Users\david\AppData\Local\Amper\extract.cache\5de2c13edf-amazon-corretto-21.0.1.12.1-windows-x64-jdk.zip.f78dbe.d
00:34.275 INFO  :amper:compileJvm         Compiling module 'amper' for platform 'jvm'...
Hello, World!
00:36.931 INFO  :amper:runJvm             Process exited with exit code 0

Mòdul

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.

Per a l’estructura de projecte anterior, seria simplement:

module.yaml

product: jvm/app

Això és tot. Les eines de Kotlin i Java, el framework de test i altres funcionalitats necessàries estan configurades i disponibles directament. Pots construir-lo, executar-lo, escriure i executar tests, i més.

./amper test

Utilitzant Amper a IntelliJ IDEA

Instal·la el plugin d’Amper.

Per executar una aplicació:

TODO

També pots crear un projecte directament amb la IDE:

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:

module.yaml

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”:

module.yaml

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:

src/main.kts

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:

all	(per defecte) la dependència està disponible durant la compilació i l’execució.
compile-only	la dependència només està disponible durant la compilació.
runtime-only	La dependència no està disponible durant la compilació, però està disponible durant les proves i l’execució

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

module.yaml

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

També hi ha una forma abreujada:

module.yaml

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.

module.yaml

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

També hi ha una forma abreujada:

module.yaml

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:

module.yaml

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:

module.yaml

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:

module.yaml

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

Nota

Les dependències $compose.* es declaren aquí amb una sintaxi especial de referència. Aquestes són referències al catàleg de biblioteques de l’eina Compose, i estan disponibles perquè hem habilitat l’eina. Llegiu més sobre els catàlegs de biblioteques a la documentació.

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

src/main.kts

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í:

project.yaml

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

Kotlin Symbol Processing

Amper provides built-in support for KSP.

TODO

Play Play

• 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