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

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

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'

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