Amper

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

Introducció

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

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:

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:

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:


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

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:

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.