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

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

זהירות: כשמציינים יחסי תלות, לא משתמשים בגרסה דינמית למשל 'com.android.tools.build:gradle:3.+'. השימוש בתכונה הזו לגרום לעדכוני גרסאות לא צפויים, קשיים בפתרון הבדלים בין גרסאות ברמת ביצועים נמוכה.

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

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

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

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

הערה: אפשר להצהיר על קטלוגים של גרסאות בהגדרות קובץ, אבל מומלץ להשתמש בקובץ toml נפרד כדי לקבל תמיכה נוספת עם הקוד הצעות והדגשה ב-Android Studio.

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 שלך.

הגדרות אישיות	התנהגות
implementation	Gradle מוסיף את התלות ל-Classpath חבילות את התלות בפלט של ה-build. כאשר מגדיר תלות של implementation, מודיעה ל-Gradle שאתם לא רוצים שהמודול ידליף או תלות במודולים אחרים בזמן ההידור. כלומר, התלות לא זמינה למודולים אחרים שתלויים של מודל טרנספורמר. שימוש בתצורת התלות במקום התוצאות של api יכולות לשפר משמעותית את זמן ה-build כי זה מפחית את מספר המודולים שמערכת ה-build צריכה כדי להדר מחדש. לדוגמה, אם implementation של התלות משנה את ה-API שלה, Gradle יוצרת מחדש רק את התלות הזאת ואת המודולים שתלויים בו באופן ישיר. רוב האפליקציות והבדיקות המודולים צריכים להשתמש בתצורה הזו.
api	Gradle מוסיף את התלות ל-classpath ול-build הפלט. כשהמודול כולל תלות ב-api, להודיע ל-Gradle שהמודול רוצה לייצא באופן זמני שתלויות במודולים אחרים, כדי שהיא תהיה זמינה להם גם סביבת זמן ריצה וגם זמן הידור. חשוב להשתמש בתצורה הזו בזהירות ורק עם יחסי תלות אתם צריכים לייצא באופן זמני לצרכנים אחרים ב-upstream. אם התלות של api משנה את ה-API החיצוני שלה, Gradle מאפשרת הידור מחדש של כל המודולים שיש להם גישה לתלות הזאת בזמן האימון. כשיש מספר גדול של יחסי תלות של api, מאריכים משמעותית את זמן ה-build. אלא אם ברצונך לחשוף של תלות ב-API למודול נפרד, משתמשים ביחסי תלות של implementation.
compileOnly	Gradle מוסיף את התלות ל-classpath בלבד (כלומר, הוא לא נוסף לפלט של ה-build). האפשרות הזאת שימושית במקרים אתם יוצרים מודול של Android, וצריך להשתמש בתלות compilation, אבל לא חייבים להציג אותו בזמן הריצה. עבור לדוגמה, אם הסתמכת על ספרייה שכוללת רק הערות בזמן הידור – לרוב משמשות ליצירת קוד אבל לעיתים קרובות היא לא כלולה בפלט ה-build – אפשר לסמן את הספרייה הזו compileOnly. אם משתמשים בתצורה הזו, מודול הספרייה כולל תנאי זמן ריצה כדי לבדוק אם התלות ולאחר מכן לשנות קלות את ההתנהגות שלו כדי שהוא עדיין יוכל אם היא לא סופקה. זה עוזר להקטין את הגודל של באפליקציה הסופית בכך שהיא לא מוסיפה יחסי תלות זמניים שאינם חיוניים. הערה: לא ניתן להשתמש ב-compileOnly עם יחסי תלות של Android Archive (AAR).
runtimeOnly	Gradle מוסיפה את התלות לפלט ה-build בלבד, לשימוש במהלך זמן הריצה. כלומר, הוא לא נוסף לנתיב הכיתה של הידור. בשימוש לעיתים רחוקות ב-Android, אבל בדרך כלל בשימוש בשרת כדי לספק הטמעות של רישום ביומן. לדוגמה, יכולה להשתמש ב-API לרישום ביומן שלא כולל יישום בפועל. צרכנים של הספרייה הזו יכולים להוסיף אותה בתור תלות ב-implementation וכוללים תלות של runtimeOnly ברישום ביומן בפועל שבו צריך להשתמש.
ksp kapt annotationProcessor	ההגדרות האלה מספקות ספריות שמעבדות הערות וסמלים אחרים בקוד שלך לפני שהוא עבר הידור. לרוב הם לאמת את הקוד או ליצור קוד נוסף, וכך לצמצם את כמות הקוד צריכים לכתוב. כדי להוסיף תלות כזו, צריך להוסיף אותה לנתיב ה-classpath של מעבד ההערות באמצעות ההגדרות ksp, kapt או annotationProcessor. שימוש באלה לשיפור ביצועי ה-build על ידי הפרדה בין classpath מה-classpath של מעבד ההערות. אם Gradle תמצא שמעבדי הערות בנתיב ההדר, הוא משבית הידור הימנעו מלכתחילה, שמשפיעה לרעה על זמן ה-build (Gradle מעבדי הערות להתעלמות מגרסה 5.0 ואילך שנמצאו בהידור ). הפלאגין Android Gradle מניח שתלות היא הערה אם קובץ ה-JAR שלו מכיל את הקובץ הבא: META-INF/services/javax.annotation.processing.Processor אם הפלאגין מזהה מעבד הערות שנמצא להדר את ה-classpath, הוא יפיק שגיאת build. ksp הוא מעבד סמלים של Kotlin, ומופעל על ידי מהדר של Kotlin. kapt ו-apt הם כלים נפרדים לעבד הערות לפני הפעלת מהדרים של Kotlin או Java. כדי להחליט באיזו הגדרה להשתמש, כדאי להביא בחשבון את הבאים: אם מעבד זמין כמעבד סמלים של Kotlin, השתמשו בתור תלות ב-ksp. ראו העברה מ-kapt ל-ksp לפרטים על השימוש במעבדי סמלים של Kotlin. אם המעבד לא זמין כמעבד סמלים של Kotlin: אם הפרויקט כולל מקור Kotlin (אבל יכול גם כולל את מקור Java), שימוש ב-kapt כדי לכלול אותה. אם בפרויקט שלך נעשה שימוש רק במקור Java, עליך להשתמש ב- annotationProcessor כדי לכלול אותה. למידע נוסף על השימוש במעבדי הערות: הוספת מעבדי הערות.
lintChecks	צריך להשתמש בהגדרה הזו כדי לכלול ספרייה שמכילה איתור שגיאות בקוד בדיקות שרוצים ש-Gradle יבצע כשמפתחים את האפליקציה ל-Android פרויקט. חשוב לשים לב שהצעות AAR שמכילות קובץ lint.jar להריץ אוטומטית בדיקות שהוגדרו באותו קובץ lint.jar; אין צורך להוסיף תלות מפורשת ב-lintChecks. כך אפשר להגדיר ספריות ובדיקות לאיתור שגיאות בקוד (lint) משויכות תלות, כדי להבטיח שהבדיקות יופעלו כשהצרכנים משתמשים לספרייה.
lintPublish	שימוש בהגדרה הזו בפרויקטים של ספריית Android כדי לכלול איתור שגיאות בקוד בדיקות שרוצים להדר ב-Gradle לקובץ lint.jar וחבילה ב-AAR. הדבר גורם לפרויקטים שצורכים AAR כדי להחיל גם את בדיקות השגיאות האלה. אם בעבר השתמשתם הגדרת התלות של lintChecks כדי לכלול איתור שגיאות בקוד של הבדיקות ב-AAR שפורסם, צריך להעביר את יחסי התלות האלה כדי להשתמש במקום זאת בהגדרות האישיות של lintPublish. Kotlin 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, צריך להשתמש כך:

Kotlin

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

מגניב

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

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

Kotlin

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

Kotlin

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

Kotlin

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' קבוצת מרחב שמות. הקובץ הבינארי המרוחק הצהרת תלות היא קיצור של:

Kotlin

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 הזה.

Kotlin

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

Kotlin

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

מגניב

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