Gradle KTS — چیست، Kotlin DSL برای Gradle و syntax

Gradle KTS چیست؟

Gradle KTS — این Kotlin DSL (Domain Specific Language) است که جایگزینی برای Groovy برای نوشتن فایل‌های پیکربندی Gradle فراهم می‌کند. به جای syntax Groovy، توسعه‌دهندگان از Kotlin استفاده می‌کنند — زبانی با تایپ قوی که صحت پیکربندی را در مرحله کامپایل بررسی می‌کند. KTS اولین بار در Gradle 5.0 در سال 2018 به عنوان یک ویژگی آزمایشی معرفی شد و در Gradle 6.0 به پایداری رسید.

هدف اصلی KTS رفع کاستی‌های Groovy در اسکریپت‌های build است. Groovy زبانی با تایپ dynamic است که در آن خطاهای پیکربندی فقط در runtime هنگام اجرای task ظاهر می‌شوند. KTS به لطف تایپ static Kotlin امکان تشخیص همان خطاها را در مرحله ویرایش کد فراهم می‌کند. علاوه بر این، KTS دسترسی به API Gradle را با مستندات کامل انواع فراهم می‌کند که یادگیری و استفاده از بلوک‌های پیکربندی پیچیده را بسیار ساده‌تر می‌کند.

اکوسیستم KTS توسط تمام ابزارهای اصلی پشتیبانی می‌شود: Android Studio، IntelliJ IDEA، VS Code با پلاگین Kotlin و Gradle Build Tool. تمام پلاگین‌های مدرن (Android Gradle Plugin، Kotlin Multiplatform، Protobuf، Compose) API دوستانه Kotlin با انواع مشخص ارائه می‌دهند که KTS را به انتخاب ارجح برای پروژه‌های جدید تبدیل می‌کند.

Gradle KTS چگونه کار می‌کند

Gradle KTS از کامپایلر Kotlin برای پردازش فایل‌های .gradle.kts استفاده می‌کند. Gradle پسوند را تشخیص داده و اسکریپت‌ها را به موتور اسکریپت‌نویسی Kotlin می‌فرستد که آنها را به کلاس‌ها کامپایل می‌کند. سپس این کلاس‌ها توسط Gradle برای ساخت مدل پروژه اجرا می‌شوند. تفاوت کلیدی با Groovy: اسکریپت‌های KTS از قبل کامپایل می‌شوند نه اینکه به صورت dynamic تفسیر شوند، که این امکان را می‌دهد خطاها قبل از شروع اجرای task‌ها شناسایی شوند.

معماری KTS بر پایه kotlin-scripting استوار است. هر فایل .gradle.kts یک اسکریپت Kotlin با importهای ضمنی API Gradle است. توسعه‌دهنده می‌تواند از هر ساختار Kotlin استفاده کند: توابع extension، lambdaها، کلاس‌های data و甚至 اعلام توابع کمکی در داخل اسکریپت build. Gradle مجموعه‌ای از توابع extension را برای پیکربندی تایپ‌شده بلوک‌ها فراهم می‌کند: dependencies، android، kotlin و غیره.

plugins {
    id("com.android.application") version "8.4.0"
    kotlin("android") version "2.0.21"
}

android {
    namespace = "com.itsectr.app"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.itsectr.app"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0.0"
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.06.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.core:core-ktx:1.13.1")
}

تبدیل انواع در KTS

یکی از تفاوت‌های کلیدی KTS با Groovy کار با انواع است. در Groovy تمام پیکربندی‌ها Object دریافت می‌کنند، در KTS — انواع مشخص Kotlin. به عنوان مثال، compileSdk مقدار Int را می‌پذیرد نه string را. این کار خطاهای مربوط به نوع نادرست را حذف می‌کند: در Groovy compileSdk 34 و compileSdk «34» هر دو یکسان کار می‌کنند، در KTS فقط گزینه اول. چنین دقتی پیکربندی را قابل پیش‌بینی‌تر و مستندتر می‌کند.

Gradle KTS در مقابل Groovy: مقایسه

Groovy DSL اصلی برای Gradle بود و همچنان به طور کامل پشتیبانی می‌شود. با این حال، KTS مجموعه‌ای از مزایا را ارائه می‌دهد که آن را برای پروژه‌های جدید توصیه‌شده می‌کند. تایپ static، عملکرد بهتر ویرایش در IDE و syntax دقیق‌تر — دلایل اصلی انتقال به KTS هستند. در عین حال، Groovy مزیت مختصر بودن را برای پیکربندی‌های ساده حفظ می‌کند.

عملکرد build در KTS و Groovy پس از کامپایل اسکریپت‌ها تقریباً یکسان است. اسکریپت‌های KTS در اولین اجرا یا پس از پاک کردن cache طولانی‌تر کامپایل می‌شوند، اما buildهای بعدی با همان سرعت اسکریپت‌های Groovy کار می‌کنند. Gradle اسکریپت‌های KTS کامپایل‌شده را در دایرکتوری build کش می‌کند، بنابراین کامپایل مجدد فقط هنگام تغییر اسکریپت انجام می‌شود.

انتخاب بین KTS و Groovy در سال 2026 واضح است: برای پروژه‌های جدید — KTS. Google، JetBrains و Gradle KTS را برای تمام پروژه‌های جدید توصیه می‌کنند. Groovy برای پشتیبانی از پروژه‌های legacy که مهاجرت به دلیل حجم پیکربندی‌ها یا پلاگین‌های خاص ناسازگار با KTS به صرفه نیست، مرتبط باقی می‌ماند.

مثال‌های کد: اسکریپت‌های build در KTS

بلوک‌های پیکربندی معمول در KTS را برای Android، Kotlin Multiplatform و Compose Multiplatform بررسی می‌کنیم. پروژه Android با KTS نیاز به مشخص کردن صریح انواع در پیکربندی buildTypes و productFlavors دارد. مثال زیر پیکربندی اپلیکیشن با دو flavour را نشان می‌دهد.

android {
    buildTypes {
        val release = getByName("release") {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        getByName("debug") {
            applicationIdSuffix = ".debug"
        }
    }

    flavorDimensions += "version"
    productFlavors {
        register("demo") {
            dimension = "version"
            versionNameSuffix = "-demo"
        }
        register("full") {
            dimension = "version"
        }
    }
}

برای Kotlin Multiplatform KTS اجباری است — Groovy پیکربندی ماژول‌های چندپلتفرمی را به درستی پشتیبانی نمی‌کند. پیکربندی ماژول KMM شامل تنظیم پلتفرم‌های target و source set‌ها است. مثال زیر پیکربندی ماژول shared با iOS و Android را نشان می‌دهد.

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = "17"
            }
        }
    }

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "Shared"
            isStatic = true
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
        }
        androidMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
        }
    }
}

توابع کمکی و task‌های سفارشی

KTS امکان اعلام توابع کمکی Kotlin در داخل اسکریپت build را فراهم می‌کند. این به ویژه برای پیکربندی‌های تکراری مانند signing configs یا مدیریت نسخه مناسب است. به لطف تایپ static، چنین توابعی را می‌توان با بررسی پارامترها در مرحله کامپایل فراخوانی کرد که خطاها را در پیکربندی‌های signing قبل از انتشار در Google Play حذف می‌کند.

fun Project.configureSigning() {
    android {
        signingConfigs {
            register("release") {
                storeFile = file("release.keystore")
                storePassword = System.getenv("KEYSTORE_PASSWORD")
                keyAlias = System.getenv("KEY_ALIAS")
                keyPassword = System.getenv("KEY_PASSWORD")
            }
        }
    }
}

// استفاده در build.gradle.kts
configureSigning()

مهاجرت از Groovy به KTS

مهاجرت از Groovy به KTS فرآیندی است که می‌تواند به تدریج انجام شود. Gradle از پروژه‌های ترکیبی پشتیبانی می‌کند که در آن بخشی از ماژول‌ها از Groovy (build.gradle) و بخشی از KTS (build.gradle.kts) استفاده می‌کنند. settings.gradle و root build.gradle می‌توانند اول ترجمه شوند زیرا به پلاگین‌های ماژول وابسته نیستند. Google توصیه می‌کند مهاجرت را با settings.gradle.kts، سپس root build.gradle.kts و فقط بعد از آن ماژول‌ها شروع کنید.

مراحل اصلی مهاجرت شامل: جایگزینی syntax closures با lambdaها، اضافه کردن علامت = برای تخصیص، جایگزینی کلیدهای string با ثابت‌های تایپ‌شده و تایپ صریح متغیرها است. Android Studio تبدیل خودکار Groovy → KTS را برای بلوک‌های ساده فراهم می‌کند، اما پیکربندی‌های پیچیده با closures تو در تو نیاز به بازنویسی دستی دارند.

مشکلات معمول در مهاجرت شامل فراخوانی‌های ضمنی متدهای Groovy است که معادل Kotlin ندارند و پلاگین‌هایی که API دوستانه Kotlin ارائه نمی‌دهند. برای حل مشکل اول، Gradle سازگاری را از طریق withGroovyBuilder فراهم می‌کند — مکانیزمی که امکان فراخوانی متدهای Groovy را از KTS می‌دهد. برای دوم — باید منتظر به‌روزرسانی پلاگین ماند یا از آن در ماژول Groovy تا زمان مهاجرت کامل استفاده کرد.

Gradle KTS برای Kotlin Multiplatform

Kotlin Multiplatform پروژه اصلی است که در آن KTS یک الزام اجباری است. پلاگین kotlin multiplatform extensionهایی برای پیکربندی پلتفرم‌های target، source set‌ها و باینری‌های framework فراهم می‌کند که فقط از طریق Kotlin DSL در دسترس هستند. Groovy پیکربندی چندپلتفرمی را به درستی پشتیبانی نمی‌کند، بنابراین پروژه‌های KMM منحصراً از KTS استفاده می‌کنند.

پیکربندی KMM در KTS شامل بلوک‌های غیراستاندارد است: kotlin.target برای مشخص کردن پلتفرم‌ها، kotlin.sourceSets برای سازماندهی کد مشترک و پلتفرمی، kotlin.cocoapods برای یکپارچه‌سازی با CocoaPods و kotlin.jvmToolchain برای انتخاب JDK. هر بلوک API به شدت تایپ‌شده با تکمیل خودکار در Android Studio دارد که برای پیکربندی پیچیده پروژه KMM با چندین پلتفرم بسیار ارزشمند است.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    cocoapods {
        summary = "Shared Kotlin module"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = false
        }
        pod("Alamofire") {
            version = "5.9"
        }
    }
}

به لطف تایپ static KTS، توسعه‌دهندگان KMM تکمیل خودکار را برای source set‌ها و وابستگی‌ها، بررسی types پیکربندی framework و امکان refactoring نام‌های پلتفرمی دریافت می‌کنند. KTS همچنین debug را ساده‌تر می‌کند: خطاهای پیکربندی KMM به عنوان خطاهای کامپایل Kotlin با پیام‌های قابل فهم نمایش داده می‌شوند، برخلاف Groovy که خطاها می‌توانند تا زمان اجرای task Gradle پنهان بمانند.