הוספת תלויות 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 ברמת המודול ייראה כך:

   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 qualifier, ולכן אי אפשר להשתמש ב-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

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

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