הוספת תלויות 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" }
   

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

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

לדוגמה, כדי להוסיף תלות בינארית מרחוק רק לגרסת המוצר 'חינם' באמצעות ההגדרה 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

כשמבצעים 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 שלא נעשה בו שימוש בקטלוגים של גרסאות:

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

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