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

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

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

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

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

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

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

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

با این حال، اگر می‌خواهید برای گونه‌ای که ترکیبی از product flavor و build type است، وابستگی اضافه کنید، باید نام پیکربندی را مقداردهی اولیه کنید:

// 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 برای تست‌های محلی و تست‌های instrumented، به این صورت عمل کنید:

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 این فراداده‌ها را بررسی می‌کند تا هشدارهایی را برای مشکلات شناخته شده با 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

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

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

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

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

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

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'

فایل ساخت همچنین یک وابستگی به یک ماژول کتابخانه اندروید با نام "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'
}