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

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

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

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

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

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

1. הוסף כינוי לגרסת התלות הרצויה הקטע [versions] בקובץ קטלוג הגרסאות, שנקרא libs.versions.toml (בספרייה gradle ב- תצוגת פרויקט או סקריפטים של Gradle בתצוגת 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 וקובצי 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. אם המיקום במקום זאת, ברצונך להצהיר על תלות רק של גרסת ספציפית הוגדר מקור הווריאנט או עבור מקור בדיקה set, צריך להשתמש באותיות רישיות בהגדרה ולהוסיף לו את השם של הווריאנט של ה-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.5.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.5.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 המסוף בודק את המטא-נתונים האלה כדי לספק התראות על בעיות ידועות בערכות 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 תיבת דו-שיח מבנה של ערכות SDK ציבוריות Google Play SDK Index במקרים הבאים:

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

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

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