הוספת תלויות build

מערכת ה-build של Gradle ב-Android Studio מאפשרת לכם לכלול קבצים בינאריים חיצוניים או מודולים אחרים של ספריות ב-build שלכם כתלות. יחסי התלות יכולים להיות במחשב שלכם או במאגר מרוחק, וכל יחסי תלות טרנזיטיביים שהם מצהירים עליהם נכללים גם הם באופן אוטומטי. בדף הזה מוסבר איך להשתמש ביחסי תלות בפרויקט Android, כולל פרטים על התנהגויות והגדרות שספציפיות לפלאגין Android Gradle‏ (AGP). מדריך מפורט יותר בנושא יחסי תלות ב-Gradle זמין כאן. עם זאת, חשוב לזכור שבפרויקט Android אפשר להשתמש רק בהגדרות יחסי התלות שמוגדרות בדף הזה.

הוספת תלות בספרייה או בתוסף

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

הוראות להוספה וניהול של יחסי תלות מקוריים (לא נפוץ) מופיעות במאמר יחסי תלות מקוריים.

בדוגמה הבאה, אנחנו מוסיפים לפרויקט תלות בקובץ בינארי מרוחק (ספריית Jetpack Macrobenchmark), תלות במודול של ספרייה מקומית (myLibrary) ותלות בפלאגין (פלאגין Android Gradle). אלה השלבים הכלליים להוספת יחסי התלות האלה לפרויקט:

  1. מוסיפים כינוי לגרסה של התלות שרוצים להשתמש בה בקטע [versions] של קובץ קטלוג הגרסאות, שנקרא libs.versions.toml (בספרייה gradle בתצוגה Project או Gradle Scripts בתצוגה Android):

    [versions]
agp = "8.3.0"
androidx-macro-benchmark = "1.2.2"
my-library = "1.4"

[libraries]
...

[plugins]
...

    כינויים יכולים לכלול מקפים או קווים תחתונים. כינויים כאלה יוצרים ערכים מקוננים שאפשר להפנות אליהם בסקריפטים של build. ההפניות מתחילות בשם הקטלוג, החלק libs של libs.versions.toml. כשמשתמשים בקטלוג עם גרסה אחת, מומלץ להשאיר את ערך ברירת המחדל libs.

  2. מוסיפים כינוי לתלות בקטע [libraries] (לבינאריים מרוחקים או למודולים של ספריות מקומיות) או בקטע [plugins] (לתוספים) בקובץ libs.versions.toml.

    [versions]
...

[libraries]
androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }

[plugins]
androidApplication = { id = "com.android.application", version.ref = "agp" }

    חלק מהספריות זמינות ב-BOM (רשימת חומרים) שפורסם ומקובצות בו משפחות של ספריות והגרסאות שלהן. אתם יכולים לכלול BOM בקטלוג הגרסאות ובקובצי ה-build, ולאפשר לו לנהל את הגרסאות האלה בשבילכם. לפרטים נוספים, אפשר לעיין במאמר בנושא שימוש ב-Bill of Materials.

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

    Kotlin

    plugins {
  alias(libs.plugins.androidApplication)
}

dependencies {
  implementation(libs.androidx.benchmark.macro)
  implementation(libs.my.library)
}

    מגניב

    plugins {
  alias 'libs.plugins.androidApplication'
}

dependencies {
  implementation libs.androidx.benchmark.macro
  implementation libs.my.library
}

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

הגדרת יחסי תלות

בתוך הבלוק dependencies, אפשר להצהיר על תלות בספרייה באמצעות אחת מתצורות התלות השונות (כמו implementation שמוצגת למעלה). כל הגדרה של יחסי תלות מספקת ל-Gradle הוראות שונות לגבי אופן השימוש ביחסי התלות. בטבלה הבאה מתוארות כל ההגדרות שאפשר להשתמש בהן לתלות בפרויקט Android.

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

שימוש בהגדרת התלות הזו במקום ב-api יכול לשפר באופן משמעותי את זמן הבנייה, כי הוא מצמצם את מספר המודולים שמערכת הבנייה צריכה לקמפל מחדש. לדוגמה, אם API של יחסי תלות של implementation משתנה, Gradle מבצע קומפילציה מחדש רק של יחסי התלות האלה ושל המודולים שתלויים בהם ישירות. רוב מודולי האפליקציות ומודולי הבדיקה צריכים להשתמש בהגדרה הזו.
api ‫Gradle מוסיף את התלות לנתיב המחלקה של הקומפילציה ולפלט של ה-build. כשמודול כולל תלות api, הוא מאפשר ל-Gradle לדעת שהמודול רוצה לייצא את התלות הזו באופן טרנזיטיבי למודולים אחרים, כדי שהיא תהיה זמינה להם בזמן הריצה ובזמן ההידור.

צריך להשתמש בהגדרה הזו בזהירות ורק עם תלות שצריך לייצא באופן טרנזיטיבי לצרכנים אחרים במעלה הזרם. אם תלות api משנה את ה-API החיצוני שלה, Gradle מבצע קומפילציה מחדש של כל המודולים שיש להם גישה לתלות הזו בזמן הקומפילציה. מספר גדול של תלויות apiיכול להגדיל משמעותית את זמן הבנייה. אלא אם רוצים לחשוף את ה-API של יחסי תלות למודול נפרד, מודולים של ספריות צריכים להשתמש במקום זאת ביחסי תלות מסוג implementation.
compileOnly ‫Gradle מוסיף את התלות רק לנתיב המחלקה של הקומפילציה (כלומר, הוא לא מתווסף לפלט של הבנייה). האפשרות הזו שימושית כשיוצרים מודול Android וצריך את התלות במהלך ההידור, אבל לא חובה שהיא תהיה קיימת בזמן הריצה. לדוגמה, אם אתם מסתמכים על ספרייה שכוללת רק הערות בזמן קומפילציה – בדרך כלל משתמשים בהן כדי ליצור קוד, אבל לרוב הן לא נכללות בפלט של הבנייה – אתם יכולים לסמן את הספרייה הזו ב-compileOnly.

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

הערה: אי אפשר להשתמש בהגדרת compileOnly עם תלות ב-Android Archive ‏ (AAR).

runtimeOnly ‫Gradle מוסיף את יחסי התלות רק לפלט של הבנייה, לשימוש בזמן הריצה. כלומר, הוא לא נוסף לנתיב המחלקה של הקומפילציה. השימוש בה נדיר ב-Android, אבל נפוץ באפליקציות של שרתים כדי לספק הטמעות של רישום ביומן. לדוגמה, ספרייה יכולה להשתמש ב-Logging API שלא כולל הטמעה. משתמשים בספרייה הזו יכולים להוסיף אותה כimplementation תלות ולכלול תלות runtimeOnly בהטמעה בפועל של הרישום ביומן.
ksp
kapt
annotationProcessor

ההגדרות האלה מספקות ספריות שמעבדות הערות וסמלים אחרים בקוד לפני שהוא עובר קומפילציה. בדרך כלל הם מאמתים את הקוד או יוצרים קוד נוסף, וכך מצמצמים את כמות הקוד שצריך לכתוב.

כדי להוסיף תלות כזו, צריך להוסיף אותה לנתיב המחלקה של מעבד ההערות באמצעות ההגדרות ksp, kapt או annotationProcessor. השימוש בהגדרות האלה משפר את ביצועי הבנייה על ידי הפרדה בין נתיב המחלקה של הקומפילציה לבין נתיב המחלקה של מעבד ההערות. אם Gradle מוצא מעבדי הערות בנתיב המחלקה של הקומפילציה, הוא משבית את הימנעות מהקומפילציה, מה שמשפיע לרעה על זמן הבנייה (Gradle מגרסה 5.0 ואילך מתעלם ממעבדי הערות שנמצאים בנתיב המחלקה של הקומפילציה).

הפלאגין Android Gradle מניח שתלות היא מעבד הערות אם קובץ ה-JAR שלה מכיל את הקובץ הבא:

META-INF/services/javax.annotation.processing.Processor

אם התוסף מזהה מעבד הערות שנמצא בנתיב המחלקה של הקומפילציה, הוא יוצר שגיאת בנייה.

‫ksp הוא מעבד סמלים של Kotlin, והוא מופעל על ידי הקומפיילר של Kotlin.

‫kapt ו-apt הם כלים נפרדים שמבצעים עיבוד של הערות לפני שהקומפיילרים של Kotlin או Java מופעלים.

כשמחליטים באיזו הגדרה להשתמש, כדאי להביא בחשבון את הנקודות הבאות:

  • אם מעבד זמין כמעבד סמלים של Kotlin, משתמשים בו כתלות ksp. מידע נוסף על השימוש ב-Kotlin Symbol Processors זמין במאמר העברה מ-kapt ל-ksp.
  • אם המעבד לא זמין כמעבד סמלים של Kotlin:
    • אם הפרויקט שלכם כולל מקור Kotlin (אבל יכול לכלול גם מקור Java), משתמשים ב-kapt כדי לכלול אותו.
    • אם הפרויקט משתמש רק במקור Java, צריך להשתמש ב-annotationProcessor כדי לכלול אותו.

מידע נוסף על השימוש במעבדי הערות זמין במאמר בנושא הוספת מעבדי הערות.
lintChecks

משתמשים בהגדרה הזו כדי לכלול ספרייה שמכילה בדיקות lint שרוצים ש-Gradle יבצע כשיוצרים את פרויקט האפליקציה ל-Android.

שימו לב שספריות AAR שמכילות קובץ lint.jar יפעילו אוטומטית בדיקות שמוגדרות בקובץ lint.jar הזה, ולא צריך להוסיף תלות מפורשת ב-lint.jar.lintChecks כך אפשר להגדיר ספריות ובדיקות lint משויכות בתלות אחת, ולוודא שהבדיקות יופעלו כשהצרכנים משתמשים בספרייה.
lintPublish משתמשים בהגדרה הזו בפרויקטים של ספריות Android כדי לכלול בדיקות lint שרוצים ש-Gradle יקמפל לקובץ lint.jar ויארוז ב-AAR. כתוצאה מכך, גם בפרויקטים שצורכים את ה-AAR שלכם יופעלו בדיקות ה-lint האלה. אם השתמשתם בעבר בהגדרת התלות lintChecks כדי לכלול בדיקות lint ב-AAR שפורסם, אתם צריכים להעביר את התלויות האלה להגדרה lintPublish.

Kotlin

dependencies {
  // Executes lint checks from the ":checks" project at build time.
  lintChecks(project(":checks"))
  // Compiles lint checks from the ":checks-to-publish" into a
  // lint.jar file and publishes it to your Android library.
  lintPublish(project(":checks-to-publish"))
}

מגניב

dependencies {
  // Executes lint checks from the ':checks' project at build time.
  lintChecks project(':checks')
  // Compiles lint checks from the ':checks-to-publish' into a
  // lint.jar file and publishes it to your Android library.
  lintPublish project(':checks-to-publish')
}

הגדרת יחסי תלות לגרסת build ספציפית

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

לדוגמה, כדי להוסיף תלות בינארית מרחוק רק לגרסת המוצר 'החינמית' באמצעות ההגדרה implementation, משתמשים בקוד הבא:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

מגניב

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

עם זאת, אם רוצים להוסיף תלות בווריאנט שמשלב בין טעם מוצר לסוג בנייה, צריך לאתחל את שם ההגדרה:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

מגניב

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

כדי להוסיף תלות ב-implementation לבדיקות המקומיות ולבדיקות המכשירים, צריך להשתמש בפורמט הבא:

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

מגניב

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

עם זאת, יש הגדרות מסוימות שלא מתאימות למצב הזה. לדוגמה, מכיוון שמודולים אחרים לא יכולים להיות תלויים ב-androidTest, מוצגת האזהרה הבאה אם משתמשים בהגדרה androidTestApi:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

סדר התלות

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

לדוגמה, אם בפרויקט מוגדרים הערכים הבאים:

  • תלות ב-LIB_A וב-LIB_B (בסדר הזה)
  • ‫LIB_A תלוי ב-LIB_C וב-LIB_D (בסדר הזה)
  • וגם LIB_B תלוי ב-LIB_C

אז סדר התלות השטוח יהיה כזה:

  1. LIB_A
  2. LIB_D
  3. LIB_B
  4. LIB_C

כך אפשר לוודא שגם LIB_A וגם LIB_B יכולים לבטל את LIB_C, ועדיין LIB_D נמצא בעדיפות גבוהה יותר מ-LIB_B כי LIB_A (שתלוי בו) נמצא בעדיפות גבוהה יותר מ-LIB_B.

מידע נוסף על מיזוג של מניפסטים ממקורות שונים של פרויקטים או מהתלויות שלהם זמין במאמר בנושא מיזוג של כמה קובצי מניפסט.

מידע על תלות ב-Play Console

כשמבצעים build לאפליקציה, AGP כולל מטא-נתונים שמתארים את יחסי התלות של הספריות שעוברות קומפילציה באפליקציה. כשמעלים את האפליקציה, מערכת Play Console בודקת את המטא-נתונים האלה כדי לספק התראות על בעיות ידועות בערכות SDK וביחסי תלות שהאפליקציה משתמשת בהם, ובמקרים מסוימים, לספק משוב פרקטי לפתרון הבעיות האלה.

הנתונים דחוסים, מוצפנים באמצעות מפתח חתימה של Google Play ומאוחסנים בבלוק החתימה של אפליקציית הגרסה. מומלץ לשמור את קובץ התלות הזה כדי להבטיח חוויית משתמש בטוחה וחיובית. כדי לבטל את ההגדרה, צריך לכלול את הבלוק dependenciesInfo הבא בקובץ build.gradle.kts של המודול.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

למידע נוסף על המדיניות שלנו ועל בעיות פוטנציאליות ביחסי תלות, אפשר לעיין בדף התמיכה בנושא שימוש בערכות SDK של צד שלישי באפליקציה.

תובנות לגבי SDK

ב-Android Studio מוצגות אזהרות של lint בקובץ קטלוג הגרסאות ובתיבת הדו-שיח Project Structure לגבי ערכות SDK ציבוריות ב-Google Play SDK Index כשהבעיות הבאות רלוונטיות:

  • המחברים של ערכות ה-SDK סימנו אותן כמיושנות.
  • ערכות ה-SDK מפירות את המדיניות של Play.
  • ב-SDK יש נקודות חולשה ידועות באבטחה.
  • ערכות ה-SDK הוצאו משימוש על ידי המחברים שלהן.

האזהרות הן סימן לכך שכדאי לעדכן את התלויות האלה, כי שימוש בגרסאות מיושנות עלול למנוע ממך לפרסם ב-Google Play Console בעתיד.

הוספת יחסי תלות ב-build בלי קטלוגים של גרסאות

מומלץ להשתמש בקטלוגים של גרסאות כדי להוסיף תלות ולנהל אותה, אבל יכול להיות שלא תצטרכו אותם בפרויקטים פשוטים. דוגמה לקובץ build שלא נעשה בו שימוש בקטלוגים של גרסאות:

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

מגניב

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

בקובץ ה-build הזה מוצהרת תלות בגרסה 12.3 של הספרייה app-magic, בתוך קבוצת מרחב השמות com.example.android. ההצהרה על תלות בבינארי מרחוק היא קיצור של הפעולות הבאות:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

מגניב

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

קובץ ה-build גם מכריז על תלות במודול ספריית Android בשם mylibrary. השם הזה חייב להיות זהה לשם הספרייה שהוגדר באמצעות include: בקובץ settings.gradle.kts. כשיוצרים את האפליקציה, מערכת ה-build מהדרת את מודול הספרייה ואורזת את התוכן המהודר שמתקבל באפליקציה.

קובץ ה-build גם מכריז על תלות בתוסף Android Gradle‏ (com.application.android). אם יש לכם כמה מודולים שמשתמשים באותו תוסף, יכולה להיות רק גרסה אחת של התוסף בנתיב המחלקה של ה-build בכל המודולים. במקום לציין את הגרסה בכל אחד מסקריפטים של build של מודולים, צריך לכלול את יחסי התלות של הפלאגין בסקריפט ה-build של השורש עם הגרסה, ולציין שלא להחיל אותו. הוספת apply false אומרת ל-Gradle לציין את גרסת הפלאגין אבל לא להשתמש בה ב-build הבסיסי. בדרך כלל סקריפט הבנייה של השורש ריק, למעט הבלוק plugins הזה.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

מגניב

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

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

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

מגניב

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}