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

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

הוספת תלות בספרייה או בפלאגין

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

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

   Kotlin

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

   Groovy

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

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

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

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

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 או בקבוצת מקורות לבדיקה, צריך להשתמש באותיות רישיות בשם ההגדרה ולהוסיף לו את השם של גרסת ה-build או של קבוצת המקורות לבדיקה.

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

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

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

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

// 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 לבדיקות המקומיות ולבדיקות עם מכשירי המדידה, צריך להוסיף את הקוד הבא:

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

כשאתם מפתחים את האפליקציה, 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 מוצגות אזהרות על שגיאות בקוד בקובץ של קטלוג הגרסאות ובתיבת הדו-שיח Project Structure לגבי ערכות SDK ציבוריות בGoogle Play SDK Index במקרים הבאים:

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

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

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

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

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. ההצהרה על יחסי התלות הבינאריים מרחוק היא קיצור דרך לביטוי הבא:

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 plugin‏ (com.application.android). אם יש לכם כמה מודולים שמשתמשים באותו פלאגין, תוכלו להשתמש רק בגרסה אחת של הפלאגין ב-build classpath בכל המודולים. במקום לציין את הגרסה בכל אחד מתסריטי ה-build של המודול, צריך לכלול את יחסי התלות של הפלאגין בתסריט ה-build ברמה הבסיסית עם הגרסה, ולציין לא להחיל אותו. הוספת apply false מורה ל-Gradle לתעד את גרסת הפלאגין, אבל לא להשתמש בו ב-build ברמה הבסיסית. בדרך כלל סקריפט ה-build ברמה הבסיסית (root) ריק, מלבד הבלוק plugins הזה.

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 ברמת הפרויקט ריק:

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

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