Bàsic

Amper és una eina de construcció de programari multiplataforma.

Introducció
Entorn de treball
Mòdul
CLI
Dependències
Compilador
Resources
Package
IDEA
Activitat

Introducció

Entorn de treball

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

Crea un projecte “JVM console application”:

Mòdul

Un mòdul Amper és un directori amb un fitxer de configuració module.yaml, fitxers font i recursos que descriu un únic producte.

Un fitxer de configuració de mòdul descriu què produir: per exemple, una biblioteca reutilitzable o una aplicació específica per a escriptori, android o altres plataformes.

Com que has creat un projecte “VM simple, el contingut del fitxer module.yaml és mínim.

El fitxer està en format YAML (mira l’activitat si no saps que és).

Un mòdul està format per defecte per les carpetes src i test.

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

Per executar una aplicació utilitza la icona ‘run’ () al costat de la secció product del fitxer module.yaml:

També pots utilitzar la icona ‘run’ ( ) al costat de la funció main():

Codi font

Els fitxers font es troben a la carpeta src:

|-src/
|  |-main.kt
|-module.yaml

Per defecte, el punt d’entrada de les aplicacions JVM (la funció main) s’espera que estigui en un fitxer main.kt (no distingeix entre majúscules i minúscules) a la carpeta src.

Això es pot sobreescriure especificant una classe principal explícitament a la configuració del mòdul:

product: jvm/app
settings:
  jvm:
    mainClass: dev.xtec.TotoKt

Nota

A Kotlin, la funció main normalment es troba al nivell superior del fitxer.

No obstant això, la JVM espera una classe principal quan executa qualsevol aplicació.

Kotlin sempre compila les declaracions de nivell superior a una classe, i el nom d’aquesta classe es deriva del nom del fitxer capitalitzant el nom i convertint l’extensió .kt en un sufix Kt.

Per exemple, les declaracions de nivell superior de toto.kt estaran en una classe anomenada TotoKt.

En un mòdul JVM, pots barrejar fitxers font de Kotlin i Java:

|-src/
|  |-main.kt
|  |-Util.java
|-module.yaml

`module.yaml`

Un fitxer module.yaml té diverses seccions principals: product:, dependencies: i settings:.

El tipus de producte descriu la plataforma objectiu i el tipus de projecte alhora.

A continuació tens la llista de tipus de productes admesos:


`lib`	Una biblioteca que pot ser utilitzada com a dependència per altres mòduls.
`jvm/app`	Una aplicació de consola o d’escriptori JVM
`jvm/lib`	Una biblioteca que només es pot utilitzar en JVM
`windows/app`	Una aplicació mingw64
`linux/app`	Una aplicació nativa de Linux
`macos/app`	Una aplicació nativa de macOS
`android/app`	Una aplicació Android VM
`ios/app`	Una aplicació iOS/iPadOS

Aquí tens un exemple d’una aplicació de consola JVM amb una única dependència i una versió del llenguatge Kotlin especificada:

product: jvm/app
dependencies:
  - io.ktor:ktor-client-core:2.3.0
settings:
  kotlin:
    languageVersion: 2.1

CLI

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

Obre un terminal Alt + F12.

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

Segur que estan actualitzats, però en un projecte de fa uns mesos segur que no (així vas aprenent)

.\amper update

Nota

No cal que escriguis .\amper.

És més ràpid escriure am i apretar la tecla ⭾ per que autcompleti amb .\amper.

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.

*** Welcome to Amper v.0.8.0! ***

This is the first run of this version, so we need to download the actual Amper distribution.
Please give us a few seconds now, subsequent runs will be faster.

Downloading Amper distribution v0.8.0...
Download complete.

Downloading JetBrains Runtime v21.0.8b1038.68...
Download complete.

Fetching latest Amper version info...
Latest Amper version is 0.8.0
Downloading Amper scripts...
Download complete.
Amper is already in version 0.8.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:

00:05.328 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\JetBrains\Amper\download.cache\5de2c13edf-amazon-corretto-21.0.1.12.1-windows-x64-jdk.zip
00:21.241 INFO  :amper:compileJvm         Compiling module 'amper' for platform 'jvm'...
Hello, World!
00:25.140 INFO  :amper:runJvm             Process exited with exit code 0

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

.\amper --help

Ordres útils:


`amper init`	Crea un projecte Amper nou
`amper build`	Compila i enllaçar tot el codi del projecte
`amper test`	Executa les proves del projecte
`amper run`	Executar l’aplicació
`amper clean`	Eliminar la sortida de compilació i les memòries cau del projecte

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

Com que has modificat la configuració d’Amper, has de sincronitzar els canvis:

Ara pots utilitzar la llibreria kotlinx-datetime en el fitxer main.kt:

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.8.0
  - 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 plot.png que s’acaba de crear.

En qualsevol moment pots veure les dependències del projecte:

.\amper show dependencies

Dependencies of module amper:

Module amper
│ - main
│ - scope = COMPILE
│ - platforms = [jvm]
├─── amper:main:org.jetbrains.kotlinx:kandy-lets-plot:0.8.0
│    ╰─── org.jetbrains.kotlinx:kandy-lets-plot:0.8.0
│         ├─── org.jetbrains.kotlinx:kandy-api:0.8.0
.
├─── amper:main:org.jetbrains.kotlinx:kotlinx-datetime:0.6.2
│    ╰─── org.jetbrains.kotlinx:kotlinx-datetime:0.6.2 (*)
╰─── amper:main:org.jetbrains.kotlin:kotlin-stdlib:2.2.10, implicit
     ╰─── org.jetbrains.kotlin:kotlin-stdlib:2.2.10 (*)

Test

A Kotlin - Test pots aprendre com gestionar les dependències de test.

Compilador

Una altra tasca típica és configurar els paràmetres del compilador, com el nivell del llenguatge, etc.

Per exemple, si vols que el compilador utilitzi compatibilitat amb la versió 2.1 del llenguatge, pots configurar la secció settings:

product: jvm/app
settings:
  kotlin:
    languageVersion: 2.1  # Set Kotlin source compatibility to 2.1

En aquest enllaç tens les diferents versions del compilador disponibles: Kotlin - Releases

Si tens ganes de provar noves versions del compilador de Kotlin abans de la pròxima versió d’Amper, ara pots personalitzar la versió del compilador de Kotlin amb una configuració senzilla:

PENDENT de verificar funcionament 🤔

settings:
  kotlin:
    version: 2.3.0-Beta1

Resources

Els fitxers col·locats a la carpeta resources es copien als productes resultants:

|-src/
|  |-...
|-resources/     # These files are copied into the final products
|  |-...

Package

Amper proporciona una ordre package per construir un projecte per a la distribució.

Per a mòduls jvm/app produeix jars executables que segueixen El format de Jar executable.

El format JAR executable, tot i que està comunament associat amb aplicacions Spring, és una solució d’empaquetament universal adequada per a qualsevol aplicació JVM.

Aquest format proporciona una unitat de desplegament autònoma i executable convenient que inclou totes les dependències necessàries, però a diferència de l’enfocament del shadow jar, està desproveit dels problemes de processament de duplicats.

Crea un executable amb amper package:

.\amper package

El resultat està a la carpeta build/tasks.

Si tens java instal·lat pots executar l’aplicació directament:

IDEA

Quan crees nous directoris en un mòdul Amper:

Pots triar entre diverses opcions predefinides en funció de les teves plataformes:

Activitat

Crea un petit programa que demani alguna cosa al teu usuari, faci alguna cosa i mostri el resultat.

Crea una projecte que sigui distribuïble.

Amper - Bàsic