Gradle Kotlin DSL

Proyek Kotlin berukuran sedang ke atas dikelola oleh Gradle, alat build yang membaca konfigurasi tertulis lalu menjalankan langkah kompilasi, pengujian, dan pengemasan secara otomatis. Konfigurasi tersebut ditulis dengan Gradle Kotlin DSL, yaitu domain specific language berbasis Kotlin yang menjadi pilihan default pada proyek baru. Topik ini membahas bentuk berkas build.gradle.kts dan settings.gradle.kts, peran blok plugins, repositories, dan dependencies, deklarasi dependensi pengujian, serta pembuatan task tambahan di dalam skrip yang sama.

Dua berkas konfigurasi proyek#

Skrip Kotlin DSL disimpan sebagai berkas berekstensi .kts, yaitu berkas skrip yang dievaluasi oleh Gradle menggunakan compiler Kotlin. Karena skripnya berupa Kotlin sungguhan, konfigurasinya memiliki tipe data yang ketat, mendukung pelengkapan otomatis pada IDE, dan menampilkan pesan error kompilasi ketika salah menulis nama fungsi. Skrip Groovy yang lama tetap didukung, tetapi proyek baru yang dibuat dengan gradle init sudah menggunakan berkas .kts secara bawaan.

Sebuah proyek paling sedikit memuat dua berkas konfigurasi. Berkas settings.gradle.kts menyatakan identitas proyek, sedangkan build.gradle.kts memuat plugin, repositori, dependensi, dan task. Keduanya diletakkan pada akar direktori proyek.

// tidak-dijalankan
rootProject.name = "statistik-nilai"

// tidak-dijalankan
plugins {
    kotlin("jvm") version "2.2.21"
    application
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:5.14.4")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

application {
    mainClass.set("MainKt")
}

tasks.test {
    useJUnitPlatform()
}

tasks.register("cetakSalam") {
    doLast {
        println("Halo dari task custom")
    }
}

Berkas-berkas di atas mengasumsikan struktur direktori bawaan Gradle untuk proyek Kotlin, yaitu kode utama pada src/main/kotlin dan kode pengujian pada src/test/kotlin.

statistik-nilai/
├── settings.gradle.kts
├── build.gradle.kts
└── src/
    ├── main/kotlin/Main.kt
    └── test/kotlin/PengujianKalkulator.kt

Blok plugins dan repositories#

Blok plugins mendeklarasikan plugin yang dipakai proyek beserta versinya. Penulisan versi di tempat ini membuat build bersifat dapat direproduksi, karena setiap komputer yang menjalankan proyek memakai versi plugin yang sama. Plugin kotlin("jvm") mengompilasi kode Kotlin menjadi bytecode JVM dan menyiapkan dua source set, yaitu main untuk kode aplikasi dan test untuk kode pengujian. Plugin application menambahkan task run serta penentuan kelas utama lewat mainClass.set("MainKt"), sesuai aturan penamaan kelas hasil kompilasi berkas Main.kt.

Blok repositories menyatakan lokasi unduhan plugin dan dependensi. Pemanggilan mavenCentral() menetapkan Maven Central sebagai repositori, sehingga Gradle dapat mengunduh JUnit 5 dan pustaka lain yang dideklarasikan pada blok dependencies. Bila proyek membutuhkan repositori tambahan, pemanggilan maven() atau mavenLocal() ditambahkan pada blok yang sama.

Blok dependencies dan konfigurasi pemasangannya#

Setiap baris pada blok dependencies memasangkan satu konfigurasi pemasangan (configuration) dengan satu dependensi. Konfigurasi menentukan di mana dependensi boleh dipakai, dan notasi dependensinya berupa string dengan urutan grup, nama, lalu versi yang dipisahkan titik dua. Tiga konfigurasi yang paling sering dipakai adalah sebagai berikut.

• implementation untuk dependensi yang dibutuhkan kode utama pada src/main/kotlin.
• testImplementation untuk dependensi yang hanya dibutuhkan kode pengujian pada src/test/kotlin.
• testRuntimeOnly untuk dependensi yang hanya dibutuhkan saat pengujian dijalankan, bukan saat dikompilasi.

Pada contoh di atas, JUnit Jupiter 5.14.4 dipasang melalui testImplementation sehingga tidak terbawa ke dalam artefak produksi. Baris testRuntimeOnly("org.junit.platform:junit-platform-launcher") menyediakan launcher yang mengeksekusi pengujian saat task test berjalan. Pemisahan ketiga konfigurasi ini menjaga dependensi pengujian tetap terisolasi dari kode utama.

Task bawaan dan task tambahan#

Task adalah satuan kerja terkecil yang dijalankan Gradle, misalnya mengompilasi satu source set atau menjalankan pengujian. Plugin yang diterapkan pada blok plugins ikut mendaftarkan task bawaannya, sehingga tanpa menulis apa pun proyek Kotlin sudah memiliki task build, test, clean, dan run. Task tambahan dideklarasikan dengan tasks.register, dan blok doLast berisi pekerjaan yang dieksekusi setiap kali task tersebut dipanggil. Task cetakSalam pada build.gradle.kts adalah contohnya.

# tidak-dijalankan
# mengompilasi kode utama dan kode pengujian, lalu menjalankan seluruh pengujian
./gradlew build
# menjalankan task tambahan yang dideklarasikan pada build.gradle.kts
./gradlew cetakSalam
# menampilkan daftar task yang tersedia pada proyek
./gradlew tasks

Skrip gradlew pada akar proyek adalah Gradle wrapper, yaitu peluncur yang mengunduh dan memakai versi Gradle yang tercatat pada proyek. Dengan wrapper, perintah build menjadi identik di setiap komputer tanpa memerlukan pemasangan Gradle manual.

Kesalahan umum#

Dua kesalahan yang paling sering muncul pada proyek Kotlin DSL berkaitan dengan blok yang ditulis tidak lengkap. Kesalahan pertama adalah lupa memanggil useJUnitPlatform() pada blok tasks.test. Tanpa pemanggilan itu, task test memakai mesin pengujian lama, tidak menemukan kelas pengujian JUnit 5, dan tetap berakhir sukses tanpa menjalankan satu pun pengujian. Akibatnya kegagalan pada kode tersembunyi di balik build yang tampak sehat.

Kesalahan kedua adalah salah memilih konfigurasi dependensi. Dependensi yang ditulis pada testImplementation tidak terlihat oleh kode utama, dan dependensi yang ditulis pada implementation tidak tersedia pada kode pengujian. Apabila kompilasi gagal dengan pesan kelas tidak ditemukan, cocokkan dulu letak berkasnya dengan konfigurasi pemasangan dependensinya sebelum mengubah kode.

Ringkasan#

• Gradle Kotlin DSL menulis konfigurasi sebagai Kotlin sungguhan pada berkas settings.gradle.kts dan build.gradle.kts.
• Blok plugins menetapkan plugin beserta versinya, blok repositories menyatakan sumber unduhan, dan blok dependencies memasangkan konfigurasi pemasangan dengan dependensi.
• Konfigurasi implementation, testImplementation, dan testRuntimeOnly memisahkan dependensi kode utama dari dependensi pengujian.
• Task bawaan berasal dari plugin, sedangkan task tambahan dideklarasikan dengan tasks.register dan dijalankan melalui wrapper ./gradlew.

Referensi#

• Gradle — JetBrains — Dokumentasi resmi Kotlin tentang penulisan konfigurasi Gradle dengan Kotlin DSL.
• Kotlin DSL — Gradle — Panduan Gradle tentang sintaks Kotlin DSL pada berkas build dan settings.