افزودن وابستگی‌های ساخت

سیستم ساخت Gradle در Android Studio به شما امکان می‌دهد تا باینری‌های خارجی یا سایر ماژول‌های کتابخانه را به‌عنوان وابستگی به ساخت خود اضافه کنید. وابستگی‌ها می‌توانند در دستگاه شما یا در مخزن راه دور قرار داشته باشند و هرگونه وابستگی انتقالی که اعلام می‌کنند نیز به‌طور خودکار گنجانده می‌شود. این صفحه نحوه استفاده از وابستگی‌ها را با پروژه Android شما شرح می‌دهد، ازجمله جزئیات درباره رفتارها و پیکربندی‌هایی که مختص افزایه Android Gradle (AGP) است. برای راهنمای مفهومی عمیق‌تر درباره وابستگی‌های Gradle، راهنمای Gradle برای مدیریت وابستگی را ببینید، اما به‌خاطر داشته باشید که پروژه Android شما باید فقط از پیکربندی‌های وابستگی تعریف‌شده در این صفحه استفاده کند.

افزودن وابستگی کتابخانه یا افزونه

بهترین راه برای افزودن و مدیریت وابستگی‌های ساخت، استفاده از کاتالوگ‌های نسخه است، روشی که پروژه‌های جدید به‌طور پیش‌فرض استفاده می‌کنند. این بخش رایج‌ترین انواع پیکربندی‌های مورداستفاده برای پروژه‌های Android را پوشش می‌دهد؛ برای گزینه‌های بیشتر، به اسناد Gradle مراجعه کنید. برای نمونه‌ای از برنامه‌ای که از کاتالوگ‌های نسخه استفاده می‌کند، اکنون در Android را ببینید. اگر ازقبل وابستگی‌های ساخت را بدون کاتالوگ‌های نسخه راه‌اندازی کرده‌اید و پروژه چندپیمانه‌ای دارید، توصیه می‌کنیم انتقال دهید.

برای راهنمایی درباره افزودن و مدیریت وابستگی‌های بومی (غیررایج)، به وابستگی‌های بومی مراجعه کنید.

در مثال زیر، یک وابستگی دودویی ازراه‌دور (کتابخانه 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]
   ...
   

   نام‌های مستعار می‌توانند شامل خط تیره یا زیرخط باشند. این نام‌های مستعار مقادیر تودرتویی تولید می‌کنند که می‌توانید در اسکریپت‌های ساخت به آن‌ها ارجاع دهید. مرجع‌ها با نام کاتالوگ شروع می‌شوند، بخش 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 را در کاتالوگ نسخه و فایل‌های ساخت خود بگنجانید و اجازه دهید آن نسخه‌ها را برای شما مدیریت کند. برای جزئیات، به استفاده از فهرست مواد مراجعه کنید.

3. ارجاعی به نام مستعار وابستگی به اسکریپت ساخت ماژول(هایی) که به وابستگی نیاز دارند اضافه کنید. هنگام ارجاع به نام مستعار از اسکریپت ساخت، زیرخط‌ها و خط تیره‌های آن را به نقطه تبدیل کنید. اسکریپت ساخت سطح ماژول ما به این شکل خواهد بود:

   کاتلین

   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')
}

پیکربندی وابستگی‌ها برای یک تنوع ساخت خاص

همه پیکربندی‌های قبلی وابستگی‌ها را بر همه تنوع‌های ساخت اعمال می‌کنند. اگر درعوض می‌خواهید وابستگی را فقط برای مجموعه منبع تنوع ساخت خاص یا برای مجموعه منبع آزمایشی اعلام کنید، باید نام پیکربندی را با حروف بزرگ بنویسید و نام تنوع ساخت یا مجموعه منبع آزمایشی را به‌عنوان پیشوند به آن اضافه کنید.

برای مثال، برای افزودن وابستگی دودویی ازراه‌دور فقط به نسخه ویژه محصول «رایگان» خود بااستفاده از پیکربندی implementation، از این استفاده کنید:

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

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

بااین‌حال، اگر می‌خواهید وابستگی‌ای برای متغیری اضافه کنید که نسخه ویژه محصول و نوع ساخت را ترکیب می‌کند، باید نام پیکربندی را مقداردهی اولیه کنید:

// 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»

هنگام ساختن برنامه، AGP فراداده‌ای را اضافه می‌کند که وابستگی‌های کتابخانه را که در برنامه شما کامپایل شده‌اند توصیف می‌کند. هنگام بارگذاری برنامه، «کنسول Play» این فراداده را بررسی می‌کند تا هشدارهایی برای مشکلات شناخته‌شده در کیت‌های توسعه نرم‌افزار و وابستگی‌هایی که برنامه شما استفاده می‌کند ارائه دهد و در برخی موارد، بازخوردهای قابل‌اجرایی برای حل این مشکلات ارائه دهد.

این داده‌ها فشرده می‌شوند، با کلید امضای Google Play رمزگذاری می‌شوند، و در بلوک امضای برنامه انتشار شما ذخیره می‌شوند. توصیه می‌کنیم این فایل وابستگی‌ها را برای تجربه کاربری ایمن و مثبت نگه دارید. با گنجاندن بلوک زیر در فایل build.gradle.kts واحدتان می‌توانید انصراف دهید: dependenciesInfo

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

برای اطلاعات بیشتر درباره خط‌مشی‌های ما و مشکلات احتمالی مربوط به وابستگی‌ها، صفحه پشتیبانی ما درباره استفاده از کیت‌های توسعه نرم‌افزار طرف سوم در برنامه را ببینید.

اطلاعات آماری کیت توسعه نرم‌افزار

«استودیو Android» هشدارهای Lint را در فایل کاتالوگ نسخه و گفتگوی ساختار پروژه برای کیت‌های توسعه نرم‌افزار عمومی در نمایه کیت توسعه نرم‌افزار Google Play نشان می‌دهد، درصورتی‌که مشکلات زیر وجود داشته باشد:

• کیت‌های توسعه نرم‌افزار توسط نویسندگانشان به‌عنوان قدیمی علامت‌گذاری شده‌اند.
• کیت‌های توسعه نرم‌افزار خط‌مشی‌های Play را نقض می‌کنند.
• کیت‌های توسعه نرم‌افزار آسیب‌پذیری‌های امنیتی شناخته‌شده‌ای دارند.
• کیت‌های توسعه نرم‌افزار توسط نویسندگانشان منسوخ شده‌اند.

این هشدارها نشان می‌دهند که باید آن وابستگی‌ها را به‌روز کنید، زیرا استفاده از نسخه‌های قدیمی ممکن است در آینده مانع از انتشار برنامه در «کنسول Google Play» شود.

افزودن وابستگی‌های ساخت بدون کاتالوگ‌های نسخه

توصیه می‌کنیم برای افزودن و مدیریت وابستگی‌ها از کاتالوگ‌های نسخه استفاده کنید، اما پروژه‌های ساده ممکن است به آن‌ها نیاز نداشته باشند. در اینجا نمونه‌ای از فایل ساخت آورده شده است که از کاتالوگ‌های نسخه استفاده نمی‌کند:

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')
}

این فایل ساخت وابستگی به نسخه ۱۲.۳ کتابخانه «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'

فایل ساخت همچنین وابستگی به واحد کتابخانه Android به‌نام «mylibrary» را اعلام می‌کند؛ این نام باید با نام کتابخانه تعریف‌شده با include: در فایل settings.gradle.kts شما مطابقت داشته باشد. وقتی برنامه‌تان را می‌سازید، سیستم ساخت، واحد کتابخانه را کامپایل می‌کند و محتوای کامپایل‌شده حاصل را در برنامه بسته‌بندی می‌کند.

فایل ساخت همچنین وابستگی به افزایه Android Gradle (com.application.android) را اعلام می‌کند. اگر چند ماژول دارید که از یک افزایه استفاده می‌کنند، فقط می‌توانید یک نسخه از افزایه را در مسیر کلاس ساخت در همه ماژول‌ها داشته باشید. به‌جای مشخص کردن نسخه در هریک از دستورگان ساخت پیمانه، باید وابستگی افزونه را در دستورگان ساخت ریشه با نسخه اضافه کنید و نشان دهید که اعمال نشود. افزودن apply false به Gradle می‌گوید که نسخه افزونه را یادداشت کند اما از آن در ساخت ریشه استفاده نکند. معمولاً اسکریپت ساخت ریشه خالی است، به‌جز این بلوک 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
}

اگر پروژه تک‌ماژولی دارید، می‌توانید نسخه را به‌طور صریح در اسکریپت ساخت سطح ماژول مشخص کنید و اسکریپت ساخت سطح پروژه را خالی بگذارید:

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

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