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

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

احتیاط: هنگام تعیین وابستگی‌ها، نباید از شماره‌های نسخه پویا مانند 'com.android.tools.build:gradle:3.+' استفاده کنید. استفاده از این ویژگی می تواند باعث بروز رسانی های غیرمنتظره نسخه، مشکل در حل تفاوت های نسخه و عملکرد ضعیف شود.

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

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

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

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

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

پیکربندی	رفتار
implementation	Gradle وابستگی را به مسیر کلاس کامپایل اضافه می کند و وابستگی را به خروجی ساخت بسته می کند. وقتی ماژول شما یک وابستگی implementation را پیکربندی می کند، به Gradle می فهماند که نمی خواهید ماژول در زمان کامپایل وابستگی را به ماژول های دیگر نشت دهد. یعنی وابستگی برای ماژول های دیگر که به ماژول فعلی وابسته هستند در دسترس قرار نمی گیرد. استفاده از این پیکربندی وابستگی به جای api می‌تواند منجر به بهبودهای قابل توجهی در زمان ساخت شود زیرا تعداد ماژول‌هایی را که سیستم بیلد برای کامپایل مجدد نیاز دارد کاهش می‌دهد. به عنوان مثال، اگر یک وابستگی implementation API خود را تغییر دهد، Gradle فقط آن وابستگی و ماژول‌هایی را که مستقیماً به آن وابسته هستند، دوباره کامپایل می‌کند. اکثر ماژول های برنامه و تست باید از این پیکربندی استفاده کنند.
api	Gradle وابستگی را به مسیر کلاس کامپایل و خروجی ساخت اضافه می کند. هنگامی که یک ماژول دارای یک وابستگی api است، به Gradle می‌داند که ماژول می‌خواهد آن وابستگی را به صورت گذرا به ماژول‌های دیگر صادر کند، به طوری که هم در زمان اجرا و هم در زمان کامپایل در دسترس آنها باشد. از این پیکربندی با احتیاط و فقط با وابستگی هایی استفاده کنید که باید به طور موقت به سایر مصرف کنندگان بالادستی صادر کنید. اگر یک وابستگی api API خارجی خود را تغییر دهد، Gradle همه ماژول‌هایی را که در زمان کامپایل به آن وابستگی دسترسی دارند، دوباره کامپایل می‌کند. داشتن تعداد زیادی وابستگی api می تواند زمان ساخت را به میزان قابل توجهی افزایش دهد. مگر اینکه بخواهید API یک وابستگی را در معرض یک ماژول جداگانه قرار دهید، ماژول های کتابخانه باید در عوض از وابستگی های implementation استفاده کنند.
compileOnly	Gradle این وابستگی را فقط به مسیر کلاس کامپایل اضافه می کند (یعنی به خروجی ساخت اضافه نمی شود). این زمانی مفید است که در حال ایجاد یک ماژول اندروید هستید و در طول کامپایل به وابستگی نیاز دارید، اما اختیاری است که آن را در زمان اجرا داشته باشید. برای مثال، اگر به کتابخانه‌ای وابسته هستید که فقط شامل حاشیه‌نویسی در زمان کامپایل است - معمولاً برای تولید کد استفاده می‌شود اما اغلب در خروجی ساخت گنجانده نمی‌شود - می‌توانید آن کتابخانه را compileOnly علامت‌گذاری کنید. اگر از این پیکربندی استفاده می‌کنید، ماژول کتابخانه شما باید دارای یک شرط زمان اجرا باشد تا بررسی کند که آیا وابستگی در دسترس است یا خیر، و سپس رفتار آن را به آرامی تغییر دهید تا در صورت عدم ارائه همچنان بتواند کار کند. این به کاهش اندازه برنامه نهایی با اضافه نکردن وابستگی های گذرا که حیاتی نیستند کمک می کند. توجه: نمی‌توانید از پیکربندی compileOnly با وابستگی‌های Android Archive (AAR) استفاده کنید.
runtimeOnly	Gradle وابستگی را برای استفاده در زمان اجرا فقط به خروجی ساخت اضافه می کند. یعنی به مسیر کلاس کامپایل اضافه نمی شود. این به ندرت در اندروید استفاده می شود، اما معمولاً در برنامه های سرور برای ارائه پیاده سازی گزارش استفاده می شود. برای مثال، یک کتابخانه می‌تواند از یک API ورود به سیستم استفاده کند که شامل پیاده‌سازی نباشد. مصرف‌کنندگان آن کتابخانه می‌توانند آن را به عنوان یک وابستگی implementation اضافه کنند و یک وابستگی runtimeOnly برای پیاده‌سازی گزارش‌گیری واقعی برای استفاده قرار دهند.
ksp kapt annotationProcessor	این پیکربندی‌ها کتابخانه‌هایی را فراهم می‌کنند که یادداشت‌ها و سایر نمادهای کد شما را قبل از کامپایل پردازش می‌کنند. آنها معمولاً کد شما را تأیید می کنند یا کد اضافی تولید می کنند و کدی را که باید بنویسید کاهش می دهند. برای افزودن چنین وابستگی، باید آن را با استفاده از پیکربندی‌های ksp ، kapt یا annotationProcessor به مسیر کلاس پردازشگر حاشیه‌نویسی اضافه کنید. استفاده از این تنظیمات با جدا کردن مسیر کلاس کامپایل از مسیر کلاس پردازشگر حاشیه نویسی، عملکرد ساخت را بهبود می بخشد. اگر Gradle پردازنده‌های حاشیه‌نویسی را در مسیر کلاس کامپایل بیابد، اجتناب از کامپایل را غیرفعال می‌کند، که بر زمان ساخت تأثیر منفی می‌گذارد (Gradle 5.0 و بالاتر، پردازنده‌های حاشیه نویسی موجود در مسیر کلاس کامپایل را نادیده می‌گیرد). پلاگین Android Gradle فرض می کند که اگر فایل JAR آن حاوی فایل زیر باشد، یک وابستگی یک پردازنده حاشیه نویسی است: META-INF/services/javax.annotation.processing.Processor اگر افزونه یک پردازنده حاشیه نویسی را که در مسیر کلاس کامپایل است شناسایی کند، یک خطای ساخت ایجاد می کند. ksp یک پردازنده نماد Kotlin است و توسط کامپایلر Kotlin اجرا می شود. kapt و apt ابزارهای جداگانه ای هستند که یادداشت ها را قبل از اجرای کامپایلرهای Kotlin یا Java پردازش می کنند. هنگام تصمیم گیری برای استفاده از پیکربندی، موارد زیر را در نظر بگیرید: اگر یک پردازنده به عنوان یک پردازنده نماد Kotlin در دسترس است، از آن به عنوان یک وابسته ksp استفاده کنید. برای جزئیات بیشتر در مورد استفاده از پردازشگرهای نماد Kotlin به مهاجرت از kapt به ksp مراجعه کنید. اگر پردازنده به عنوان پردازنده نماد Kotlin در دسترس نیست: اگر پروژه شما دارای منبع Kotlin است (اما می تواند منبع جاوا را نیز شامل شود)، از kapt برای گنجاندن آن استفاده کنید . اگر پروژه شما فقط از منبع جاوا استفاده می کند، از annotationProcessor برای اضافه کردن آن استفاده کنید. برای اطلاعات بیشتر در مورد استفاده از پردازشگرهای حاشیه نویسی، به افزودن پردازنده های حاشیه نویسی مراجعه کنید.
lintChecks	از این پیکربندی برای گنجاندن کتابخانه‌ای حاوی بررسی‌های پرز که می‌خواهید Gradle هنگام ساخت پروژه برنامه Android خود اجرا کند، استفاده کنید. توجه داشته باشید که AARهایی که حاوی یک فایل lint.jar هستند به طور خودکار چک های تعریف شده در آن فایل lint.jar را اجرا می کنند. شما نیازی به افزودن وابستگی صریح lintChecks ندارید. این به شما امکان می‌دهد کتابخانه‌ها و بررسی‌های لینت مرتبط را در یک وابستگی واحد تعریف کنید و اطمینان حاصل کنید که چک‌های شما زمانی که مصرف‌کنندگان از کتابخانه شما استفاده می‌کنند اجرا می‌شوند.
lintPublish	از این پیکربندی در پروژه‌های کتابخانه Android استفاده کنید تا بررسی‌های لینت را که می‌خواهید Gradle در فایل و بسته lint.jar در AAR خود کامپایل کند، اضافه کنید. این باعث می‌شود پروژه‌هایی که AAR شما را مصرف می‌کنند، آن بررسی‌های لینت را نیز اعمال کنند. اگر قبلاً از پیکربندی وابستگی lintChecks برای گنجاندن بررسی های lint در AAR منتشر شده استفاده می کردید، باید آن وابستگی ها را به جای استفاده از پیکربندی lintPublish منتقل کنید. کاتلین 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 این فراداده را بررسی می کند تا هشدارهایی را در مورد مشکلات شناخته شده با 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 هشدارهای پرز را در فایل کاتالوگ نسخه و گفتگوی ساختار پروژه برای SDK های عمومی در فهرست SDK Google Play در صورت بروز مشکلات زیر نشان می دهد:

• SDK ها توسط نویسندگانشان به عنوان قدیمی علامت گذاری شده اند.
• SDKها خط‌مشی‌های 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')
}

این فایل ساخت، وابستگی به نسخه 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'

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