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

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

Kotlin עדיף על פני גרובי בכתיבת סקריפטים של Gradle מכיוון ש-Kotlin לקריאות נוספות, ומספקות תמיכה טובה יותר בבדיקה בזמן הידור (IDE) ובתמיכה בסביבת פיתוח משולבת (IDE).

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

הדף הזה מספק מידע בסיסי על המרת האפליקציה שלך ל-Android Gradle build של קבצים מ-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 לתוסף.

המרת התחביר

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

הוספת סוגריים לקריאות שיטות

גרובי מאפשר להשמיט סוגריים בקריאות שיטה, בעוד ש-Kotlin דורש אותם. כדי להעביר את ההגדרות האישיות, צריך להוסיף סוגריים לסוגים האלה קריאות ל-method. הקוד הזה מראה איך לקבוע הגדרה ב-Groovy:

compileSdkVersion 30

זהו אותו הקוד שכתוב ב-Kotlin:

compileSdkVersion(30)

הוספת = למטלות הקצאה

ה-DSL של Graovy מאפשר להשמיט את אופרטור ההקצאה = כאשר להקצות מאפיינים, ואילו Kotlin דורשים זאת. הקוד הזה מראה איך הקצאת מאפיינים ב-Groovy:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

הקוד הזה מראה איך להקצות מאפיינים ב-Kotlin:

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

המרת מחרוזות

אלה ההבדלים במחרוזת בין גרובי ל-Kotlin:

  • מירכאות כפולות למחרוזות: למרות ש-Groovy מאפשר להגדיר מחרוזות באמצעות מירכאות בודדות, Kotlin דורש מירכאות כפולות.

  • אינטרפולציה למחרוזות בביטויים מקווקווים: ב-Groviy, אפשר להשתמש רק התחילית $ עבור אינטרפולציות למחרוזות לביטויים מקווקווים, אבל הפונקציה 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

גרובי משתמש בלוגיקת ניכויים של נכסים על סמך שמות המאפיינים. בנכס בוליאני foo, השיטות להסרה יכול להיות getFoo, setFoo או isFoo. כך שפעם המירה ל-Kotlin צריך לשנות את שמות המאפיינים ל-methods עם כפילויות שלא נתמכים על ידי 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 מוגדרות באמצעות תחביר שונה. מגניב משתמשת ב-[], ו-Kotlin קורא לשיטות ליצירת איסוף מפורשות listOf או mapOf. חשוב להחליף את הטקסט [] בטקסט listOf או mapOf כאשר .

כך מגדירים רשימה ב-Groovy לעומת Kotlin:

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

זהו אותו הקוד שכתוב ב-Kotlin:

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

כך מגדירים מפה ב-Groviy לעומת 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 של benchmark גרובי.

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

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

buildTypes {
 debug {
   ...
 }

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

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

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

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

איתור מזהי יישומי הפלאגין

בזמן שהבלוק buildscript {} מוסיף את יישומי הפלאגין לנתיב הכיתה של ה-build באמצעות ה קואורדינטות של 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 בכמה מזהי יישומי פלאגין. מומלץ להשתמש מזהה פלאגין עם מרחב שמות, וערך מחדש ממזהה פלאגין ממרחב שמות מקוצר על ידי הטבלה הבאה:

מזהים של יישומי פלאגין מקוצרים מזהים של יישומי פלאגין עם מרחב שמות
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 את הרצף מאגר 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 לפונקציות אחרות דפי תיעוד:

בעיות מוכרות

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

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

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

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

לדוגמה פעילה לקובצי build של Gradle שנכתבו באמצעות Kotlin, אפשר לעיין ב עכשיו באפליקציה לדוגמה ל-Android ב-GitHub.