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

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

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

3. מוסיפים הפניה לכינוי של יחסי התלות לסקריפט ה-build של המודולים שדורשים את יחסי התלות. צריך להמיר את הקווים התחתונים והמקפים של כינוי החשבון לנקודות כשמפנים אליו מסקריפט 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.

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 או של קבוצת המקורות לבדיקה כתחילית.

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

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

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