העברת תצורת ה-build מ-Groovy ל-Kotlin

בפלאגין Android Gradle 4.0 נוספה תמיכה בשימוש ב-Kotlin בהגדרות ה-build של Gradle, כתחליף ל-Groovy, שפת התכנות שבה נהוג להשתמש בקובצי התצורה של Gradle.

מומלץ להשתמש ב-Kotlin במקום ב-Groovy לכתיבה של סקריפטים של Gradle, כי קל יותר לקרוא ב-Kotlin ויש בה בדיקה טובה יותר בזמן הידור ותמיכה טובה יותר ב-IDE.

אמנם בשלב הזה Kotlin מציע שילוב טוב יותר בעורך הקוד של Android Studio בהשוואה ל-Groovy, אבל גרסאות build שמבוססות על Kotlin נוטים להיות איטיות יותר מגרסאות build שמבוססות על Groovy. לכן, כדאי להביא בחשבון את ביצועי ה-build כשמחליטים אם לעבור ל-Kotlin.

בדף הזה מפורט מידע בסיסי על המרת קובצי ה-build של אפליקציית Android מ-Groovy ל-Kotlin. למדריך מקיף יותר להעברה, עיינו במסמכי התיעוד הרשמיים של Gradle.

ציר הזמן

החל מגרסה Android Studio Giraffe, פרויקטים חדשים משתמשים ב-Kotlin DSL (build.gradle.kts) כברירת מחדל להגדרת build. הכלים האלה מספקים חוויית עריכה טובה יותר בהשוואה ל-Groovy DSL (build.gradle) עם הדגשת תחביר, השלמת קוד וניווט להצהרות. למידע נוסף, קראו את המאמר Gradle Kotlin DSL Primer.

מונחים נפוצים

Kotlin DSL: המונח מתייחס בעיקר לפלאגין של Android Gradle Kotlin DSL, או, לפעמים ל-ה-Gradle Kotlin DSL הבסיסי.

במדריך הזה להעברת נתונים, אנחנו משתמשים במונחים 'Kotlin' ו-'Kotlin DSL' לסירוגין. באופן דומה, אפשר להשתמש ב-Groovy וב-Groovy DSL לאותה מטרה.

מתן שמות לקובץ הסקריפטים

שמות הסיומת של קובצי הסקריפט מבוססים על השפה שבה נכתב קובץ ה-build:

  • קובצי build של Gradle שנכתבו ב-Groovy משתמשים בסיומת .gradle של שם הקובץ.
  • קובצי build של Gradle שנכתבו ב-Kotlin משתמשים בסיומת .gradle.kts בשם הקובץ.

המרת התחביר

יש כמה הבדלים כלליים בתחביר בין Groovy ל-Kotlin, ולכן צריך להחיל את השינויים האלה בכל סקריפט ה-build.

הוספת סוגריים לקריאות ל-method

ב-Groovy אפשר להשמיט סוגריים בקריאות ל-method, בעוד שב-Kotlin צריך להשתמש בהם. כדי להעביר את ההגדרות, צריך להוסיף סוגריים לקריאות האלה ל-method. הקוד הזה מראה איך להגדיר הגדרה ב-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
}

המרת מחרוזות

אלה ההבדלים במחרוזת בין גרובי ל-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 לכל קובץ build בזמן העברת התוכן שלו. לדוגמה, בוחרים קובץ build, כמו הקובץ settings.gradle. משנים את שם הקובץ ל-settings.gradle.kts וממירים את תוכן הקובץ ל-Kotlin. חשוב לוודא שהפרויקט עדיין עובר הידור אחרי ההעברה של כל קובץ build.

קודם מעבירים את הקבצים הכי קטנים, צוברים ניסיון ואז ממשיכים. אפשר לשלב בפרויקט קבצי build של 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. לדוגמה, לרכיבים בוליאניים של DSL buildTypes, צריך להוסיף להם את הקידומת 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")

הגדרת סוגי build

ב-Kotlin DSL, רק סוגי ה-build של ניפוי באגים ושל גרסה זמינים באופן משתמע. צריך ליצור באופן ידני את כל סוגי ה-build המותאמים אישית האחרים.

ב-Groovy אפשר להשתמש בסוגי build מסוימים, כמו debug,‏ release ועוד, בלי ליצור אותם קודם. קטע הקוד הבא מציג הגדרה עם סוגי ה-build debug,‏ release ו-benchmark ב-Groovy.

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

כדי ליצור את ההגדרה המקבילה ב-Kotlin, צריך ליצור את סוג ה-build benchmark באופן מפורש.

buildTypes {
 debug {
   ...
 }

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

מעבר מ-buildscript לבלוק של פלאגינים

אם ב-build שלכם נעשה שימוש בבלוק buildscript {} כדי להוסיף יישומי פלאגין לפרויקט, עליכם לבצע רפאקציה (refactor) כדי להשתמש במקום זאת בבלוק plugins {}. בעזרת הבלוק plugins {} קל יותר להחיל פלאגינים, והוא פועל היטב עם קטלוגים של גרסאות.

בנוסף, כשמשתמשים בבלוק plugins {} בקובצי ה-build, Android Studio מזהה את ההקשר גם כשה-build נכשל. ההקשר הזה עוזר לבצע תיקונים בקובצי ה-DSL של Kotlin, כי הוא מאפשר לסביבת הפיתוח המשולבת של Studio לבצע השלמה אוטומטית של קוד ולספק הצעות מועילות אחרות.

איך מוצאים את מזהי הפלאגינים

בעוד שהבלוק buildscript {} מוסיף את הפלאגינים לנתיב ה-classpath של ה-build באמצעות הקואורדינטות של Maven של הפלאגין, למשל com.android.tools.build:gradle:7.4.0, בבלוק plugins {} נעשה שימוש במזהי הפלאגין במקום זאת.

ברוב יישומי הפלאגין מזהה הפלאגין הוא המחרוזת שבה מחילים אותם באמצעות apply plugin. לדוגמה, מזהי הפלאגינים הבאים הם חלק מAndroid Gradle Plugin:

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

רשימת הפלאגינים המלאה מופיעה במאגר Google Maven.

אפשר להפנות ליישומי פלאגין של Kotlin בכמה מזהי יישומי פלאגין. מומלץ להשתמש במזהה הפלאגין במרחב השמות, ולבצע רפאקציה מקיצור דרך למזהה הפלאגין במרחב השמות לפי הטבלה הבאה:

מזהים מקוצרים של פלאגינים מזהי פלאגין במרחב שמות
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 Plugin Portal, ב-Maven Central Repository ובמאגר Google Maven. במאמר פיתוח פלאגינים מותאמים אישית של Gradle מוסבר בהרחבה איך פועלים מזהי הפלאגינים.

ביצוע הרפורמה

אחרי שמוצאים את המזהים של הפלאגינים שבהם אתם משתמשים, מבצעים את השלבים הבאים:

  1. אם עדיין יש לכם מאגרים של יישומי פלאגין שהוגדרו בבלוק buildscript {}, תוכלו להעביר אותם לקובץ settings.gradle במקום זאת.

  2. מוסיפים את התוספים לבלוק plugins {} בקובץ build.gradle ברמה העליונה. כאן צריך לציין את המזהה ואת הגרסה של הפלאגין. אם אין צורך להחיל את הפלאגין על פרויקט הבסיס, משתמשים ב-apply false.

  3. מסירים את הרשומות של classpath מקובץ build.gradle.kts ברמה העליונה.

  4. כדי להחיל את הפלאגינים, מוסיפים אותם לבלוק plugins {} בקובץ build.gradle ברמת המודול. צריך לציין כאן רק את המזהה של הפלאגין, כי הגרסה עוברת בירושה מהפרויקט ברמה הבסיסית (root).

  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 {} זמינים במאמר Applying plugins בתיעוד של Gradle.

שונות

בדפי המסמכים הבאים תוכלו למצוא דוגמאות לקוד Kotlin לפונקציונליות אחרת:

בעיות מוכרות

כרגע בעיה ידועה היא שמהירות ה-build עשויה להיות איטית יותר ב-Kotlin מאשר ב-Groovy.

איך מדווחים על בעיות

הוראות לשליחת המידע שנחוץ לנו כדי לסווג את הבעיה מפורטות במאמר פרטים לגבי כלי build ובאגים ב-Gradle. לאחר מכן, דווחו על באג באמצעות הכלי הציבורי של Google למעקב אחר בעיות.

משאבים נוספים

דוגמה עובדת לקובצי build של Gradle שנכתבו ב-Kotlin מופיעה ב-Now In Android sample app ב-GitHub.