انتقال پیکربندی ساخت از Groovy به Kotlin

افزایه Android Gradle نسخه ۴.۰ پشتیبانی از استفاده از Kotlin را در پیکربندی ساخت Gradle شما به‌عنوان جایگزینی برای Groovy، زبان برنامه‌نویسی که به‌طور سنتی در فایل‌های پیکربندی Gradle استفاده می‌شود، اضافه کرد.

Kotlin برای نوشتن اسکریپت‌های Gradle بر Groovy ترجیح داده می‌شود زیرا Kotlin خواناتر است و بررسی زمان ترجمه و پشتیبانی IDE بهتری ارائه می‌دهد.

اگرچه Kotlin درحال‌حاضر درمقایسه با Groovy ادغام بهتری در ویرایشگر کد Android Studio ارائه می‌دهد، اما ساخت‌های بااستفاده از Kotlin معمولاً کندتر از ساخت‌های بااستفاده از Groovy هستند، بنابراین هنگام تصمیم‌گیری برای انتقال، عملکرد ساخت را درنظر بگیرید.

این صفحه اطلاعات پایه‌ای درباره تبدیل فایل‌های ساخت Gradle برنامه Android شما از Groovy به Kotlin ارائه می‌دهد. برای راهنمای جامع‌تر انتقال، به اسناد رسمی Gradle مراجعه کنید.

خط زمان

از Android Studio Giraffe به بعد، پروژه‌های جدید به‌طور پیش‌فرض از Kotlin DSL (build.gradle.kts) برای پیکربندی ساخت استفاده می‌کنند. این گزینه تجربه ویرایش بهتری نسبت‌به Groovy DSL (build.gradle) با برجسته‌سازی نحو، تکمیل کد، و پیمایش به اظهارات ارائه می‌دهد. برای کسب اطلاعات بیشتر، کتاب راهنمای Gradle Kotlin DSL را ببینید.

اصطلاحات رایج

Kotlin DSL: عمدتاً به افزایه Android Gradle‏ Kotlin DSL یا گاهی به Gradle Kotlin DSL زیربنایی اشاره دارد.

در این راهنمای انتقال، «Kotlin» و «Kotlin DSL» به‌جای یکدیگر استفاده می‌شوند. به‌همین ترتیب، «Groovy» و «Groovy DSL» به‌جای یکدیگر استفاده می‌شوند.

نام‌گذاری فایل متن

نام پسوند فایل اسکریپت براساس زبانی است که فایل ساخت به آن نوشته شده است:

  • فایل‌های ساخت Gradle که در Groovy نوشته شده‌اند از پسوند نام فایل .gradle استفاده می‌کنند.
  • فایل‌های ساخت Gradle که در Kotlin نوشته شده‌اند از پسوند نام فایل .gradle.kts استفاده می‌کنند.

تبدیل نحو

تفاوت‌های کلی در نحو بین Groovy و Kotlin وجود دارد، بنابراین باید این تغییرات را در سراسر اسکریپت‌های ساخت خود اعمال کنید.

افزودن پرانتز به فراخوانی‌های روش

Groovy به شما امکان می‌دهد پرانتزها را در فراخوانی‌های روش حذف کنید، درحالی‌که Kotlin به آن‌ها نیاز دارد. برای انتقال پیکربندی، به این نوع فراخوانی‌های روش پرانتز اضافه کنید. این کد نحوه پیکربندی کردن تنظیمات را در Groovy نشان می‌دهد:

compileSdkVersion 30

این همان کد است که در Kotlin نوشته شده است:

compileSdkVersion(30)

افزودن = به تماس‌های تکلیف

Groovy DSL به شما امکان می‌دهد هنگام اختصاص دادن ویژگی‌ها، از عملگر تخصیص = صرف‌نظر کنید، درحالی‌که Kotlin به آن نیاز دارد. این کد نحوه اختصاص دادن ویژگی‌ها در Groovy را نشان می‌دهد:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

این کد نحوه اختصاص دادن ویژگی‌ها را در Kotlin نشان می‌دهد:

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

تبدیل رشته‌ها

تفاوت‌های رشته‌ای بین Groovy و Kotlin در اینجا آمده است:

  • علامت نقل‌قول دوتایی برای رشته‌ها: درحالی‌که Groovy اجازه می‌دهد رشته‌ها بااستفاده از علامت نقل‌قول تکی تعریف شوند، Kotlin به علامت نقل‌قول دوتایی نیاز دارد.

  • درج رشته در عبارت‌های نقطه‌دار: در Groovy، می‌توانید فقط از پیشوند $ برای درج رشته در عبارت‌های نقطه‌دار استفاده کنید، اما Kotlin از شما می‌خواهد عبارت‌های نقطه‌دار را در آکولاد قرار دهید. برای مثال، در Groovy می‌توانید از $project.rootDir استفاده کنید، همان‌طور که در قطعه کد زیر نشان داده شده است:

    myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
    

    اما در Kotlin، کد قبلی toString() را در project فراخوانی می‌کند، نه در project.rootDir. برای دریافت مقدار دایرکتوری ریشه، عبارت ${project.rootDir} را در آکولاد قرار دهید:

    myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
    

    برای کسب اطلاعات بیشتر، به الگوهای رشته در اسناد Kotlin مراجعه کنید.

تغییر دادن نام پسوند فایل

هنگام انتقال محتوای هر فایل ساخت، .kts را به آن اضافه کنید. برای مثال، فایل ساخت، مثل فایل settings.gradle را انتخاب کنید. نام فایل را به settings.gradle.kts تغییر دهید و محتوای فایل را به Kotlin تبدیل کنید. مطمئن شوید که پروژه‌تان پس‌از انتقال هر فایل ساخت همچنان کامپایل می‌شود.

ابتدا کوچک‌ترین فایل‌هایتان را انتقال دهید، تجربه کسب کنید، و سپس ادامه دهید. می‌توانید ترکیبی از فایل‌های ساخت Kotlin و Groovy را در یک پروژه داشته باشید، بنابراین وقت بگذارید تا با دقت این انتقال را انجام دهید.

def را با val یا var جایگزین کنید

def را با val یا var جایگزین کنید، که نحوه تعریف متغیرها در Kotlin است. این یک اعلان متغیر در Groovy است:

def building64Bit = false

این همان کد است که در Kotlin نوشته شده است:

val building64Bit = false

پیشوند ویژگی‌های بولی با is

Groovy از منطق کسر دارایی براساس نام‌های دارایی استفاده می‌کند. برای ویژگی بولی foo، روش‌های استنتاج‌شده آن می‌تواند getFoo،‏ setFoo، یا isFoo باشد. بنابراین، پس‌از تبدیل به Kotlin، باید نام‌های ویژگی را به روش‌های استنتاج‌شده‌ای تغییر دهید که Kotlin از آن‌ها پشتیبانی نمی‌کند. برای مثال، برای buildTypes عناصر بولی DSL، باید پیشوند is را به آن‌ها اضافه کنید. این کد نحوه تنظیم ویژگی‌های بولی را در Groovy نشان می‌دهد:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

کد زیر همان کد در Kotlin است. توجه داشته باشید که ویژگی‌ها با is پیشوندگذاری شده‌اند.

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

تبدیل کردن فهرست‌ها و نقشه‌ها

فهرست‌ها و نقشه‌ها در Groovy و Kotlin بااستفاده از نحو متفاوتی تعریف می‌شوند. Groovy از [] استفاده می‌کند، درحالی‌که Kotlin روش‌های ایجاد مجموعه را به‌طور صریح بااستفاده از listOf یا mapOf فراخوانی می‌کند. هنگام انتقال، حتماً [] را با listOf یا mapOf جایگزین کنید.

در اینجا نحوه تعریف فهرست در Groovy درمقابل Kotlin آمده است:

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

این همان کد است که در Kotlin نوشته شده است:

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

در اینجا نحوه تعریف نقشه در Groovy درمقابل Kotlin آمده است:

def myMap = [key1: 'value1', key2: 'value2']

این همان کد است که در Kotlin نوشته شده است:

val myMap = mapOf("key1" to "value1", "key2" to "value2")

پیکربندی انواع ساخت

در Kotlin DSL، فقط انواع ساخت اشکال‌زدایی و انتشار به‌طور ضمنی دردسترس هستند. همه انواع ساخت سفارشی دیگر باید به‌صورت دستی ایجاد شوند.

در Groovy می‌توانید از انواع ساخت اشکال‌زدایی، انتشار، و برخی انواع ساخت دیگر بدون ایجاد کردن آن‌ها استفاده کنید. تکه‌کد زیر پیکربندی‌ای را با انواع ساخت debug، release، و benchmark در Groovy نشان می‌دهد.

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

برای ایجاد پیکربندی معادل در Kotlin، باید صریحاً نوع ساخت benchmark را ایجاد کنید.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

انتقال از buildscript به بلوک افزایه‌ها

اگر ساخت شما از بلوک buildscript {} برای افزودن افزونه‌ها به پروژه استفاده می‌کند، باید آن را بازسازی کنید تا به‌جای آن از بلوک plugins {} استفاده کند. بلوک plugins {} اعمال افزونه‌ها را آسان‌تر می‌کند و با کاتالوگ‌های نسخه به‌خوبی کار می‌کند.

علاوه‌براین، وقتی از بلوک plugins {} در فایل‌های ساخت خود استفاده می‌کنید، «استودیو Android» از زمینه آگاه است، حتی زمانی که ساخت ناموفق باشد. این بافت به رفع اشکال فایل‌های Kotlin DSL کمک می‌کند زیرا به Studio IDE اجازه می‌دهد تکمیل کد را انجام دهد و پیشنهادهای مفید دیگری ارائه دهد.

یافتن شناسه‌های افزونه

درحالی‌که بلوک buildscript {} افزایه‌ها را بااستفاده از مختصات Maven افزایه، برای مثال com.android.tools.build:gradle:7.4.0، به مسیر کلاس ساخت اضافه می‌کند، بلوک plugins {} درعوض از شناسه‌های افزایه استفاده می‌کند.

برای اکثر افزایه‌ها، شناسه افزایه رشته‌ای است که هنگام اعمال آن‌ها بااستفاده از apply plugin استفاده می‌شود. برای مثال، شناسه‌های افزایه زیر بخشی از افزایه Android Gradle هستند:

  • com.android.application
  • com.android.library
  • com.android.lint
  • com.android.test

می‌توانید فهرست کامل افزونه‌ها را در مخزن Google Maven پیدا کنید.

افزونه‌های Kotlin را می‌توان با چندین شناسه افزونه ارجاع داد. توصیه می‌کنیم از شناسه افزونه فضای نام استفاده کنید و طبق جدول زیر، شناسه افزونه را از حالت خلاصه به حالت فضای نام بازسازی کنید:

شناسه‌های افزونه Shorthand شناسه‌های افزونه فضای نامی
kotlin org.jetbrains.kotlin.jvm
kotlin-android org.jetbrains.kotlin.android
kotlin-kapt org.jetbrains.kotlin.kapt
kotlin-parcelize org.jetbrains.kotlin.plugin.parcelize

همچنین می‌توانید افزایه‌ها را در درگاه افزایه Gradle، مخزن مرکزی Maven، و مخزن Google Maven جستجو کنید. برای کسب اطلاعات بیشتر درباره نحوه عملکرد شناسه‌های افزایه، توسعه افزایه‌های Gradle سفارشی را بخوانید.

بازسازی کد را انجام دهید

وقتی شناسه‌های افزونه‌هایی را که استفاده می‌کنید پیدا کردید، مراحل زیر را انجام دهید:

  1. اگر هنوز مخزن‌هایی برای افزایه‌ها دارید که در بلوک buildscript {} اعلام شده‌اند، آن‌ها را به فایل settings.gradle منتقل کنید.

  2. افزونه‌ها را به بلوک plugins {} در فایل سطح بالای build.gradle اضافه کنید. باید شناسه و نسخه افزونه را در اینجا مشخص کنید. اگر لازم نیست افزایه روی پروژه ریشه اعمال شود، از apply false استفاده کنید.

  3. ورودی‌های classpath را از فایل build.gradle.kts سطح بالا بردارید.

  4. افزونه‌ها را با افزودن آن‌ها به بلوک plugins {} در فایل build.gradle سطح ماژول اعمال کنید. در اینجا فقط باید شناسه افزونه را مشخص کنید زیرا نسخه از پروژه ریشه به ارث می‌رسد.

  5. فراخوانی apply plugin برای افزایه را از فایل build.gradle در سطح ماژول بردارید.

برای مثال، این راه‌اندازی از بلوک buildscript {} استفاده می‌کند:

// Top-level build.gradle file
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
        ...
    }
}

// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")

این راه‌اندازی معادل بااستفاده از بلوک plugins {} است:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.4.0' apply false
   id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   id 'org.jetbrains.kotlin.android'
   ...
}

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

تبدیل بلوک افزایه‌ها

اعمال کردن افزایه‌ها از بلوک plugins {} در Groovy و Kotlin مشابه است. کد زیر نحوه اعمال افزایه‌ها در Groovy را هنگام استفاده از کاتالوگ‌های نسخه نشان می‌دهد:

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

کد زیر نحوه انجام همین کار را در Kotlin نشان می‌دهد:

// Top-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application) apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

کد زیر نحوه اعمال افزایه‌ها را در Groovy وقتی از کاتالوگ‌های نسخه استفاده نمی‌کنید نشان می‌دهد:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

کد زیر نحوه انجام همین کار را در Kotlin نشان می‌دهد:

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version "7.3.0" apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

برای جزئیات بیشتر درباره بلوک plugins {}، به اعمال کردن افزایه‌ها در اسناد Gradle مراجعه کنید.

متفرقه

برای نمونه‌های کد Kotlin برای سایر عملکردها، به صفحه‌های اسناد زیر مراجعه کنید:

مشکلات شناخته‌شده

یک مشکل شناخته‌شده این است که سرعت ساخت ممکن است با Kotlin کندتر از Groovy باشد.

نحوه گزارش کردن مشکلات

برای دریافت دستورالعمل‌های مربوط به نحوه ارائه اطلاعاتی که برای اولویت‌بندی مشکلتان نیاز داریم، به جزئیات مربوط به ابزارهای ساخت و اشکالات Gradle مراجعه کنید. سپس، بااستفاده از ردیاب مشکل عمومی Google، اشکال را ثبت کنید.

منابع بیشتر

برای مشاهده نمونه‌ای از فایل‌های ساخت Gradle که با Kotlin نوشته شده‌اند، برنامه نمونه Now In Android را در GitHub ببینید.