این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ساخت خود را پیکربندی کنید

سیستم ساخت اندروید منابع برنامه و کد منبع را جمع‌آوری می‌کند و آن‌ها را در فایل‌های APK یا Android App Bundle بسته‌بندی می‌کند که می‌توانید آن‌ها را آزمایش، استقرار، امضا و توزیع کنید.

در نمای کلی ساخت Gradle و ساختار ساخت اندروید ، مفاهیم ساخت و ساختار یک برنامه اندروید را مورد بحث قرار دادیم. اکنون زمان پیکربندی بیلد است.

واژه نامه ساخت اندروید

Gradle و پلاگین Android Gradle به شما کمک می کنند تا جنبه های زیر ساخت خود را پیکربندی کنید:

انواع ساخت

انواع ساخت ویژگی‌های خاصی را تعریف می‌کنند که Gradle هنگام ساخت و بسته‌بندی اپلیکیشن شما از آن‌ها استفاده می‌کند. انواع ساخت معمولاً برای مراحل مختلف چرخه عمر توسعه شما پیکربندی می شوند.

برای مثال، نوع ساخت اشکال‌زدایی، گزینه‌های اشکال‌زدایی را فعال می‌کند و برنامه را با کلید اشکال‌زدایی امضا می‌کند، در حالی که نوع ساخت انتشار ممکن است کوچک شود، مبهم شود، و برنامه شما را با کلید انتشار برای توزیع امضا کند.

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

طعم های محصول

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

انواع ساخت

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

ورودی های آشکار

می توانید مقادیری را برای برخی از ویژگی های فایل مانیفست در پیکربندی نوع ساخت مشخص کنید. این مقادیر ساختنی مقادیر موجود در فایل مانیفست را نادیده می گیرند. اگر می خواهید چندین گونه از برنامه خود را با نام برنامه متفاوت، حداقل نسخه SDK یا نسخه هدف SDK ایجاد کنید، مفید است. وقتی چند مانیفست وجود دارد، ابزار ادغام مانیفست تنظیمات مانیفست را ادغام می‌کند .

وابستگی ها

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

امضا کردن

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

کاهش کد و منابع

سیستم ساخت به شما امکان می دهد یک فایل قوانین ProGuard متفاوت را برای هر نوع ساخت مشخص کنید. هنگام ساخت برنامه شما، سیستم ساخت مجموعه قوانین مناسبی را اعمال می کند تا کد و منابع شما را با استفاده از ابزارهای کوچک سازی داخلی خود، مانند R8، کوچک کند . کوچک کردن کد و منابع می تواند به کاهش اندازه APK یا AAB شما کمک کند.

پشتیبانی از چندین APK

سیستم ساخت به شما امکان می دهد به طور خودکار APK های مختلفی بسازید که هر کدام فقط حاوی کد و منابع مورد نیاز برای تراکم صفحه نمایش یا رابط باینری برنامه (ABI) هستند. برای اطلاعات بیشتر به ساخت چندین APK مراجعه کنید. با این حال، انتشار یک AAB منفرد رویکرد توصیه‌شده است، زیرا علاوه بر تراکم صفحه نمایش و ABI، تقسیم بر اساس زبان را ارائه می‌دهد، در حالی که نیازی به آپلود چندین مصنوع در Google Play نیست. همه برنامه‌های جدید ارسال شده پس از آگوست ۲۰۲۱ باید از AAB استفاده کنند.

نسخه های جاوا در بیلدهای اندروید

چه کد منبع شما به زبان جاوا، کاتلین یا هر دو نوشته شده باشد، مکان‌های مختلفی وجود دارد که باید یک نسخه زبان JDK یا جاوا را برای ساخت خود انتخاب کنید. برای جزئیات بیشتر به نسخه های جاوا در بیلدهای اندروید مراجعه کنید.

ساخت فایل های پیکربندی

برای ایجاد تنظیمات ساخت سفارشی، باید تغییراتی در یک یا چند فایل پیکربندی ساخت ایجاد کنید. این فایل‌های متن ساده از یک زبان مخصوص دامنه (DSL) برای توصیف و دستکاری منطق ساخت با استفاده از اسکریپت Kotlin استفاده می‌کنند، که طعمی از زبان Kotlin است. همچنین می‌توانید از Groovy ، که یک زبان پویا برای ماشین مجازی جاوا (JVM) است، برای پیکربندی ساخت‌های خود استفاده کنید.

برای شروع پیکربندی بیلد خود نیازی به دانستن اسکریپت Kotlin یا Groovy ندارید زیرا افزونه Android Gradle اکثر عناصر DSL مورد نیاز را معرفی می کند. برای کسب اطلاعات بیشتر در مورد پلاگین Android Gradle DSL، مستندات مرجع DSL را بخوانید. اسکریپت Kotlin همچنین بر پایه Gradle Kotlin DSL متکی است

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

فایل Gradle Wrapper

Gradle wrapper ( gradlew ) یک برنامه کوچک همراه با کد منبع شما است که خود Gradle را دانلود و راه اندازی می کند. این باعث می شود که اجرای بیلد سازگارتر باشد. توسعه دهندگان منبع برنامه را دانلود کرده و gradlew اجرا می کنند. این توزیع Gradle مورد نیاز را دانلود می کند و Gradle را برای ساخت برنامه شما راه اندازی می کند.

فایل gradle/wrapper/gradle-wrapper.properties حاوی یک ویژگی است، distributionUrl ، که توضیح می‌دهد از کدام نسخه Gradle برای اجرای ساخت شما استفاده می‌شود.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

فایل تنظیمات Gradle

فایل settings.gradle.kts (برای Kotlin DSL) یا فایل settings.gradle (برای Groovy DSL) در فهرست اصلی پروژه قرار دارد. این فایل تنظیمات، تنظیمات مخزن در سطح پروژه را تعریف می‌کند و به Gradle اطلاع می‌دهد که چه ماژول‌هایی را هنگام ساخت برنامه شما باید شامل شود. پروژه های چند ماژول باید هر ماژول را مشخص کنند که باید وارد ساخت نهایی شود.

برای اکثر پروژه ها، فایل به صورت پیش فرض به شکل زیر است:

کاتلین

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

شیار

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

فایل ساخت سطح بالا

فایل build.gradle.kts سطح بالا (برای Kotlin DSL) یا فایل build.gradle (برای Groovy DSL) در دایرکتوری اصلی پروژه قرار دارد. معمولاً نسخه های متداول افزونه های مورد استفاده توسط ماژول ها در پروژه شما را تعریف می کند.

نمونه کد زیر تنظیمات پیش‌فرض و عناصر DSL در اسکریپت ساخت سطح بالا را پس از ایجاد یک پروژه جدید توضیح می‌دهد:

کاتلین

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id("com.android.application") version "8.7.0" apply false
    id("com.android.library") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.20" apply false
}

شیار

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id 'com.android.application' version '8.7.0' apply false
    id 'com.android.library' version '8.7.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.0.20' apply false
}

فایل ساخت در سطح ماژول

build.gradle.kts در سطح ماژول (برای Kotlin DSL) یا فایل build.gradle (برای Groovy DSL) در هر project / module / دایرکتوری قرار دارد. این به شما امکان می‌دهد تنظیمات ساخت را برای ماژول خاصی که در آن قرار دارد پیکربندی کنید. پیکربندی این تنظیمات ساخت به شما امکان می‌دهد گزینه‌های بسته‌بندی سفارشی، مانند انواع ساخت‌های اضافی و طعم‌های محصول، و لغو تنظیمات در مانیفست main/ برنامه یا اسکریپت ساخت سطح بالا را ارائه دهید. .

تنظیمات Android SDK

فایل ساخت در سطح ماژول برای برنامه شما شامل تنظیماتی است که نشان می‌دهد نسخه‌های Android SDK مورد استفاده هنگام کامپایل، انتخاب رفتارهای پلتفرم و مشخص کردن حداقل نسخه‌ای که برنامه شما روی آن اجرا می‌شود.

مروری بر مشخصات SDK در یک ساخت Gradle — **شکل 1.** SDK های اندروید در یک ساخت

compileSdk

compileSdk تعیین می کند که کدام API های Android و Java در هنگام کامپایل کد منبع شما در دسترس هستند. برای استفاده از جدیدترین ویژگی‌های اندروید، هنگام کامپایل، از جدیدترین Android SDK استفاده کنید.

برخی از APIهای پلتفرم Android ممکن است در سطوح API قدیمی در دسترس نباشند. می‌توانید به‌طور مشروط از استفاده از ویژگی‌های جدیدتر محافظت کنید یا از کتابخانه‌های سازگاری AndroidX برای استفاده از ویژگی‌های جدیدتر با سطوح پایین‌تر API Android استفاده کنید.

هر Android SDK زیرمجموعه ای از API های جاوا را برای استفاده در برنامه شما فراهم می کند. جدول کدام API های جاوا را می توانم در کد منبع جاوا یا کاتلین خود استفاده کنم نشان می دهد که کدام سطح Java API بر اساس نسخه Android SDK در دسترس است. APIهای جدیدتر جاوا در نسخه های قبلی اندروید از طریق desugaring پشتیبانی می شوند که باید در ساخت شما فعال باشد.

اگر compileSdk شما با نسخه فعلی Android Studio، AGP یا الزامات وابستگی کتابخانه پروژه شما در تضاد باشد، Android Studio هشدارهایی را نشان می دهد.

minSdk

minSdk پایین ترین نسخه اندرویدی را که می خواهید برنامه شما از آن پشتیبانی کند را مشخص می کند. تنظیم minSdk دستگاه‌هایی را که می‌توانند برنامه شما را نصب کنند محدود می‌کند.

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

وقتی کد خود را در Android Studio ویرایش می کنید یا در حین ساخت بررسی می کنید، lint در مورد API هایی که استفاده می کنید و در minSdk موجود نیستند هشدار می دهد. شما باید با مشروط کردن ویژگی‌های جدیدتر یا با استفاده از Appcompat برای سازگاری به عقب، این موارد را برطرف کنید.

targetSdk

targetSdk دو هدف را دنبال می کند:

رفتار زمان اجرا برنامه شما را تنظیم می کند.
این نشان می دهد که شما با کدام نسخه از Android آزمایش کرده اید.

اگر روی دستگاهی اجرا می‌کنید که از نسخه بالاتر Android نسبت به targetSdk شما استفاده می‌کند، Android برنامه شما را در حالت سازگاری اجرا می‌کند که رفتاری مشابه با نسخه پایین‌تر نشان داده شده در targetSdk شما دارد. برای مثال، زمانی که API 23 مدل مجوزهای زمان اجرا را معرفی کرد، همه برنامه‌ها آماده نبودند که فوراً آن را بپذیرند. با تنظیم targetSdk روی 22، این برنامه ها می توانند بدون استفاده از مجوزهای زمان اجرا بر روی دستگاه های API 23 اجرا شوند و می توانند از ویژگی های موجود در آخرین نسخه compileSdk استفاده کنند. خط مشی توزیع Google Play سیاست های اضافی را در سطح API هدف اعمال می کند.

مقدار targetSdk باید کمتر یا مساوی با مقدار compileSdk باشد.

توجه: لازم نیست مقادیر compileSdk و targetSdk یکسان باشند. اصول اساسی زیر را در نظر داشته باشید:

compileSdk به شما امکان دسترسی به API های جدید را می دهد
targetSdk رفتار زمان اجرا برنامه شما را تنظیم می کند
targetSdk باید کمتر یا مساوی با compileSdk باشد

نمونه اسکریپت ساخت ماژول برنامه

این نمونه اسکریپت ساخت ماژول برنامه اندروید، برخی از عناصر و تنظیمات اولیه DSL را تشریح می کند:

کاتلین

/**
 * The first section in the build configuration applies the Android Gradle plugin
 * to this build and makes the android block available to specify
 * Android-specific build options.
 */

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

/**
 * Locate (and possibly download) a JDK used to build your kotlin
 * source code. This also acts as a default for sourceCompatibility,
 * targetCompatibility and jvmTarget. Note that this does not affect which JDK
 * is used to run the Gradle build itself, and does not need to take into
 * account the JDK version required by Gradle plugins (such as the
 * Android Gradle Plugin)
 */
kotlin {
    jvmToolchain(11)
}

/**
 * The android block is where you configure all your Android-specific
 * build options.
 */

android {

    /**
     * The app's namespace. Used primarily to access app resources.
     */

    namespace = "com.example.myapp"

    /**
     * compileSdk specifies the Android API level Gradle should use to
     * compile your app. This means your app can use the API features included in
     * this API level and lower.
     */

    compileSdk = 33

    /**
     * The defaultConfig block encapsulates default settings and entries for all
     * build variants and can override some attributes in main/AndroidManifest.xml
     * dynamically from the build system. You can configure product flavors to override
     * these values for different versions of your app.
     */

    defaultConfig {

        // Uniquely identifies the package for publishing.
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdk = 21

        // Specifies the API level used to test the app.
        targetSdk = 33

        // Defines the version number of your app.
        versionCode = 1

        // Defines a user-friendly version name for your app.
        versionName = "1.0"
    }

    /**
     * The buildTypes block is where you can configure multiple build types.
     * By default, the build system defines two build types: debug and release. The
     * debug build type is not explicitly shown in the default build configuration,
     * but it includes debugging tools and is signed with the debug key. The release
     * build type applies ProGuard settings and is not signed by default.
     */

    buildTypes {

        /**
         * By default, Android Studio configures the release build type to enable code
         * shrinking, using minifyEnabled, and specifies the default ProGuard rules file.
         */

        getByName("release") {
            isMinifyEnabled = true // Enables code shrinking for the release build type.
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }

    /**
     * The productFlavors block is where you can configure multiple product flavors.
     * This lets you create different versions of your app that can
     * override the defaultConfig block with their own settings. Product flavors
     * are optional, and the build system does not create them by default.
     *
     * This example creates a free and paid product flavor. Each product flavor
     * then specifies its own application ID, so that they can exist on the Google
     * Play Store or an Android device simultaneously.
     *
     * If you declare product flavors, you must also declare flavor dimensions
     * and assign each flavor to a flavor dimension.
     */

    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            dimension = "tier"
            applicationId = "com.example.myapp.free"
        }

        create("paid") {
            dimension = "tier"
            applicationId = "com.example.myapp.paid"
        }
    }

    /**
     * To override source and target compatibility (if different from the
     * toolchain JDK version), add the following. All of these
     * default to the same value as kotlin.jvmToolchain. If you're using the
     * same version for these values and kotlin.jvmToolchain, you can
     * remove these blocks.
     */
    //compileOptions {
    //    sourceCompatibility = JavaVersion.VERSION_11
    //    targetCompatibility = JavaVersion.VERSION_11
    //}
    //kotlinOptions {
    //    jvmTarget = "11"
    //}
}

/**
 * The dependencies block in the module-level build configuration file
 * specifies dependencies required to build only the module itself.
 * To learn more, go to Add build dependencies.
 */

dependencies {
    implementation(project(":lib"))
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
}

شیار

/**
 * The first line in the build configuration applies the Android Gradle plugin
 * to this build and makes the android block available to specify
 * Android-specific build options.
 */

plugins {
    id 'com.android.application'
}

/**
 * Locate (and possibly download) a JDK used to build your kotlin
 * source code. This also acts as a default for sourceCompatibility,
 * targetCompatibility and jvmTarget. Note that this does not affect which JDK
 * is used to run the Gradle build itself, and does not need to take into
 * account the JDK version required by Gradle plugins (such as the
 * Android Gradle Plugin)
 */
kotlin {
    jvmToolchain 11
}

/**
 * The android block is where you configure all your Android-specific
 * build options.
 */

android {

    /**
     * The app's namespace. Used primarily to access app resources.
     */

    namespace 'com.example.myapp'

    /**
     * compileSdk specifies the Android API level Gradle should use to
     * compile your app. This means your app can use the API features included in
     * this API level and lower.
     */

    compileSdk 33

    /**
     * The defaultConfig block encapsulates default settings and entries for all
     * build variants and can override some attributes in main/AndroidManifest.xml
     * dynamically from the build system. You can configure product flavors to override
     * these values for different versions of your app.
     */

    defaultConfig {

        // Uniquely identifies the package for publishing.
        applicationId 'com.example.myapp'

        // Defines the minimum API level required to run the app.
        minSdk 21

        // Specifies the API level used to test the app.
        targetSdk 33

        // Defines the version number of your app.
        versionCode 1

        // Defines a user-friendly version name for your app.
        versionName "1.0"
    }

    /**
     * The buildTypes block is where you can configure multiple build types.
     * By default, the build system defines two build types: debug and release. The
     * debug build type is not explicitly shown in the default build configuration,
     * but it includes debugging tools and is signed with the debug key. The release
     * build type applies ProGuard settings and is not signed by default.
     */

    buildTypes {

        /**
         * By default, Android Studio configures the release build type to enable code
         * shrinking, using minifyEnabled, and specifies the default ProGuard rules file.
         */

        release {
              minifyEnabled true // Enables code shrinking for the release build type.
              proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }

    /**
     * The productFlavors block is where you can configure multiple product flavors.
     * This lets you create different versions of your app that can
     * override the defaultConfig block with their own settings. Product flavors
     * are optional, and the build system does not create them by default.
     *
     * This example creates a free and paid product flavor. Each product flavor
     * then specifies its own application ID, so that they can exist on the Google
     * Play Store or an Android device simultaneously.
     *
     * If you declare product flavors, you must also declare flavor dimensions
     * and assign each flavor to a flavor dimension.
     */

    flavorDimensions "tier"
    productFlavors {
        free {
            dimension "tier"
            applicationId 'com.example.myapp.free'
        }

        paid {
            dimension "tier"
            applicationId 'com.example.myapp.paid'
        }
    }

    /**
     * To override source and target compatibility (if different from the
     * tool chain JDK version), add the following. All of these
     * default to the same value as kotlin.jvmToolchain. If you're using the
     * same version for these values and kotlin.jvmToolchain, you can
     * remove these blocks.
     */
    //compileOptions {
    //    sourceCompatibility JavaVersion.VERSION_11
    //    targetCompatibility JavaVersion.VERSION_11
    //}
    //kotlinOptions {
    //    jvmTarget = '11'
    //}
}

/**
 * The dependencies block in the module-level build configuration file
 * specifies dependencies required to build only the module itself.
 * To learn more, go to Add build dependencies.
 */

dependencies {
    implementation project(":lib")
    implementation 'androidx.appcompat:appcompat:1.7.0'
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

فایل های ویژگی های Gradle

Gradle همچنین شامل دو فایل ویژگی است که در دایرکتوری پروژه ریشه شما قرار دارد و می توانید از آنها برای تعیین تنظیمات خود جعبه ابزار ساخت Gradle استفاده کنید:

gradle.properties

اینجاست که می‌توانید تنظیمات Gradle را در سطح پروژه، مانند حداکثر اندازه هیپ دیمون Gradle، پیکربندی کنید. برای اطلاعات بیشتر، به Build Environment مراجعه کنید.

local.properties

ویژگی های محیط محلی را برای سیستم ساخت پیکربندی می کند، از جمله موارد زیر:

ndk.dir - مسیر NDK. این ملک منسوخ شده است. همه نسخه‌های دانلود شده NDK در فهرست ndk در فهرست راهنمای Android SDK نصب می‌شوند.
sdk.dir - مسیری به Android SDK.
cmake.dir - مسیر CMake.
ndk.symlinkdir - در Android Studio نسخه 3.5 و بالاتر، یک پیوند نمادین به NDK ایجاد می کند که می تواند کوتاهتر از مسیر NDK نصب شده باشد.

NDK را به یک مسیر کوتاه‌تر (فقط برای ویندوز) ترسیم کنید

در ویندوز، ابزارهای موجود در پوشه NDK نصب شده، مانند ld.exe ، به مسیرهای طولانی ختم می شوند. ابزارها مسیرهای طولانی را به خوبی پشتیبانی نمی کنند.

برای ایجاد یک مسیر کوتاه‌تر، در local.properties ، ویژگی ndk.symlinkdir به گونه‌ای تنظیم کنید که از افزونه Android Gradle درخواست ایجاد یک پیوند نمادین به NDK کند. مسیر آن سیملینک می تواند کوتاه تر از پوشه NDK موجود باشد. به عنوان مثال، ndk.symlinkdir = C:\ منجر به پیوند نمادین زیر می شود: C:\ndk\19.0.5232133

همگام سازی پروژه با فایل های Gradle

وقتی در فایل‌های پیکربندی ساخت در پروژه خود تغییراتی ایجاد می‌کنید، Android Studio از شما می‌خواهد که فایل‌های پروژه خود را همگام‌سازی کنید تا بتواند تغییرات پیکربندی ساخت را وارد کند و برخی بررسی‌ها را انجام دهد تا مطمئن شود پیکربندی شما خطای ساخت ایجاد نمی‌کند.

برای همگام‌سازی فایل‌های پروژه، روی همگام‌سازی اکنون در نوار اعلان که هنگام ایجاد تغییر ظاهر می‌شود، همانطور که در شکل 2 نشان داده شده است، کلیک کنید یا روی همگام‌سازی پروژه کلیک کنید. از نوار منو اگر Android Studio هر گونه خطایی را در پیکربندی شما پیدا کند - برای مثال، کد منبع شما از ویژگی‌های API استفاده می‌کند که فقط در سطح API بالاتر از compileSdkVersion شما در دسترس هستند - پنجره پیام‌ها مشکل را توضیح می‌دهد.

**شکل 2.** پروژه را با فایل های پیکربندی ساخت در اندروید استودیو همگام سازی کنید.

مجموعه های منبع

Android Studio به طور منطقی کد منبع و منابع را برای هر ماژول در مجموعه های منبع گروه بندی می کند. هنگامی که یک ماژول جدید ایجاد می کنید، Android Studio یک مجموعه main/ منبع را در ماژول ایجاد می کند. مجموعه main/ منبع یک ماژول شامل کد و منابعی است که توسط همه انواع ساخت آن استفاده می شود.

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

src/main/: این مجموعه منبع شامل کد و منابع مشترک برای همه انواع ساخت است.
src/ buildType /: این مجموعه منبع را ایجاد کنید تا شامل کد و منابع فقط برای یک نوع ساخت خاص باشد.
src/ productFlavor /: این مجموعه منبع را به گونه‌ای ایجاد کنید که کد و منابع را فقط برای طعم محصول خاص شامل شود.
توجه: اگر بیلد خود را طوری پیکربندی کنید که چندین طعم محصول را ترکیب کند ، می‌توانید فهرست‌های منبع مجموعه را برای هر ترکیبی از طعم‌های محصول بین ابعاد طعم ایجاد کنید: src/ productFlavor1 ProductFlavor2 / .
src/ productFlavorBuildType /: این مجموعه منبع را ایجاد کنید تا شامل کد و منابع فقط برای یک نوع ساخت خاص باشد.

به عنوان مثال، برای تولید نسخه "fullDebug" برنامه شما، سیستم ساخت، کد، تنظیمات و منابع را از مجموعه های منبع زیر ادغام می کند:

src/fullDebug/ (مجموعه منبع نوع ساخت)
src/debug/ (مجموعه منبع نوع ساخت)
src/full/ (مجموعه منبع طعم محصول)
src/main/ (مجموعه منبع اصلی)

توجه: هنگامی که یک فایل یا دایرکتوری جدید در Android Studio ایجاد می کنید، از گزینه های منو File > New برای ایجاد آن برای یک مجموعه منبع خاص استفاده کنید. مجموعه های منبعی که می توانید از بین آنها انتخاب کنید بر اساس پیکربندی های ساخت شما هستند و Android Studio به طور خودکار فهرست های مورد نیاز را در صورتی که قبلا وجود نداشته باشند ایجاد می کند.

اگر مجموعه‌های منبع مختلف حاوی نسخه‌های متفاوتی از یک فایل باشند، Gradle هنگام تصمیم‌گیری برای استفاده از کدام فایل از ترتیب اولویت زیر استفاده می‌کند. مجموعه‌های منبع در سمت چپ، فایل‌ها و تنظیمات مجموعه‌های منبع را در سمت راست لغو می‌کنند:

نوع ساخت > نوع ساخت > طعم محصول > مجموعه منبع اصلی > وابستگی های کتابخانه

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

هنگام ادغام چند مانیفست ، Gradle از ترتیب اولویت یکسانی استفاده می کند، بنابراین هر نوع ساخت می تواند مؤلفه ها یا مجوزهای مختلفی را در مانیفست نهایی تعریف کند. برای کسب اطلاعات بیشتر درباره ایجاد مجموعه‌های منبع سفارشی، ایجاد مجموعه‌های منبع را بخوانید.

کاتالوگ های نسخه

اگر ساخت شما حاوی چندین ماژول با وابستگی های مشترک است، یا چندین پروژه مستقل با وابستگی مشترک دارید، توصیه می کنیم از یک کاتالوگ نسخه یا صورتحساب مواد (BOM) برای مشخص کردن نسخه های رایج استفاده کنید.

سیستم های ساخت دیگر

ساخت برنامه های اندروید با Bazel امکان پذیر است اما به طور رسمی پشتیبانی نمی شود. اندروید استودیو به طور رسمی از پروژه های Bazel پشتیبانی نمی کند.

برای درک بهتر محدودیت‌های فعلی ساختمان با Bazel، به مسائل شناخته شده مراجعه کنید.

واژه نامه ساخت اندروید

Gradle و پلاگین Android Gradle به شما کمک می کنند تا جنبه های زیر ساخت خود را پیکربندی کنید:

انواع ساخت

طعم های محصول

انواع ساخت

ورودی های آشکار

وابستگی ها

امضا کردن

کاهش کد و منابع

پشتیبانی از چندین APK

نسخه های جاوا در بیلدهای اندروید

ساخت فایل های پیکربندی

فایل Gradle Wrapper

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

فایل تنظیمات Gradle

برای اکثر پروژه ها، فایل به صورت پیش فرض به شکل زیر است:

کاتلین

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

شیار

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. Here we
      * define the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

فایل ساخت سطح بالا

نمونه کد زیر تنظیمات پیش‌فرض و عناصر DSL در اسکریپت ساخت سطح بالا را پس از ایجاد یک پروژه جدید توضیح می‌دهد:

کاتلین

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id("com.android.application") version "8.7.0" apply false
    id("com.android.library") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.20" apply false
}

شیار

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id 'com.android.application' version '8.7.0' apply false
    id 'com.android.library' version '8.7.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.0.20' apply false
}

فایل ساخت در سطح ماژول

تنظیمات Android SDK

compileSdk

minSdk

targetSdk

targetSdk دو هدف را دنبال می کند:

رفتار زمان اجرا برنامه شما را تنظیم می کند.
این نشان می دهد که شما با کدام نسخه از Android آزمایش کرده اید.

مقدار targetSdk باید کمتر یا مساوی با مقدار compileSdk باشد.

توجه: لازم نیست مقادیر compileSdk و targetSdk یکسان باشند. اصول اساسی زیر را در نظر داشته باشید:

compileSdk به شما امکان دسترسی به API های جدید را می دهد
targetSdk رفتار زمان اجرا برنامه شما را تنظیم می کند
targetSdk باید کمتر یا مساوی با compileSdk باشد

نمونه اسکریپت ساخت ماژول برنامه

این نمونه اسکریپت ساخت ماژول برنامه اندروید، برخی از عناصر و تنظیمات اولیه DSL را تشریح می کند:

کاتلین

/**
 * The first section in the build configuration applies the Android Gradle plugin
 * to this build and makes the android block available to specify
 * Android-specific build options.
 */

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

/**
 * Locate (and possibly download) a JDK used to build your kotlin
 * source code. This also acts as a default for sourceCompatibility,
 * targetCompatibility and jvmTarget. Note that this does not affect which JDK
 * is used to run the Gradle build itself, and does not need to take into
 * account the JDK version required by Gradle plugins (such as the
 * Android Gradle Plugin)
 */
kotlin {
    jvmToolchain(11)
}

/**
 * The android block is where you configure all your Android-specific
 * build options.
 */

android {

    /**
     * The app's namespace. Used primarily to access app resources.
     */

    namespace = "com.example.myapp"

    /**
     * compileSdk specifies the Android API level Gradle should use to
     * compile your app. This means your app can use the API features included in
     * this API level and lower.
     */

    compileSdk = 33

    /**
     * The defaultConfig block encapsulates default settings and entries for all
     * build variants and can override some attributes in main/AndroidManifest.xml
     * dynamically from the build system. You can configure product flavors to override
     * these values for different versions of your app.
     */

    defaultConfig {

        // Uniquely identifies the package for publishing.
        applicationId = "com.example.myapp"

        // Defines the minimum API level required to run the app.
        minSdk = 21

        // Specifies the API level used to test the app.
        targetSdk = 33

        // Defines the version number of your app.
        versionCode = 1

        // Defines a user-friendly version name for your app.
        versionName = "1.0"
    }

    /**
     * The buildTypes block is where you can configure multiple build types.
     * By default, the build system defines two build types: debug and release. The
     * debug build type is not explicitly shown in the default build configuration,
     * but it includes debugging tools and is signed with the debug key. The release
     * build type applies ProGuard settings and is not signed by default.
     */

    buildTypes {

        /**
         * By default, Android Studio configures the release build type to enable code
         * shrinking, using minifyEnabled, and specifies the default ProGuard rules file.
         */

        getByName("release") {
            isMinifyEnabled = true // Enables code shrinking for the release build type.
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }

    /**
     * The productFlavors block is where you can configure multiple product flavors.
     * This lets you create different versions of your app that can
     * override the defaultConfig block with their own settings. Product flavors
     * are optional, and the build system does not create them by default.
     *
     * This example creates a free and paid product flavor. Each product flavor
     * then specifies its own application ID, so that they can exist on the Google
     * Play Store or an Android device simultaneously.
     *
     * If you declare product flavors, you must also declare flavor dimensions
     * and assign each flavor to a flavor dimension.
     */

    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            dimension = "tier"
            applicationId = "com.example.myapp.free"
        }

        create("paid") {
            dimension = "tier"
            applicationId = "com.example.myapp.paid"
        }
    }

    /**
     * To override source and target compatibility (if different from the
     * toolchain JDK version), add the following. All of these
     * default to the same value as kotlin.jvmToolchain. If you're using the
     * same version for these values and kotlin.jvmToolchain, you can
     * remove these blocks.
     */
    //compileOptions {
    //    sourceCompatibility = JavaVersion.VERSION_11
    //    targetCompatibility = JavaVersion.VERSION_11
    //}
    //kotlinOptions {
    //    jvmTarget = "11"
    //}
}

/**
 * The dependencies block in the module-level build configuration file
 * specifies dependencies required to build only the module itself.
 * To learn more, go to Add build dependencies.
 */

dependencies {
    implementation(project(":lib"))
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
}

شیار

/**
 * The first line in the build configuration applies the Android Gradle plugin
 * to this build and makes the android block available to specify
 * Android-specific build options.
 */

plugins {
    id 'com.android.application'
}

/**
 * Locate (and possibly download) a JDK used to build your kotlin
 * source code. This also acts as a default for sourceCompatibility,
 * targetCompatibility and jvmTarget. Note that this does not affect which JDK
 * is used to run the Gradle build itself, and does not need to take into
 * account the JDK version required by Gradle plugins (such as the
 * Android Gradle Plugin)
 */
kotlin {
    jvmToolchain 11
}

/**
 * The android block is where you configure all your Android-specific
 * build options.
 */

android {

    /**
     * The app's namespace. Used primarily to access app resources.
     */

    namespace 'com.example.myapp'

    /**
     * compileSdk specifies the Android API level Gradle should use to
     * compile your app. This means your app can use the API features included in
     * this API level and lower.
     */

    compileSdk 33

    /**
     * The defaultConfig block encapsulates default settings and entries for all
     * build variants and can override some attributes in main/AndroidManifest.xml
     * dynamically from the build system. You can configure product flavors to override
     * these values for different versions of your app.
     */

    defaultConfig {

        // Uniquely identifies the package for publishing.
        applicationId 'com.example.myapp'

        // Defines the minimum API level required to run the app.
        minSdk 21

        // Specifies the API level used to test the app.
        targetSdk 33

        // Defines the version number of your app.
        versionCode 1

        // Defines a user-friendly version name for your app.
        versionName "1.0"
    }

    /**
     * The buildTypes block is where you can configure multiple build types.
     * By default, the build system defines two build types: debug and release. The
     * debug build type is not explicitly shown in the default build configuration,
     * but it includes debugging tools and is signed with the debug key. The release
     * build type applies ProGuard settings and is not signed by default.
     */

    buildTypes {

        /**
         * By default, Android Studio configures the release build type to enable code
         * shrinking, using minifyEnabled, and specifies the default ProGuard rules file.
         */

        release {
              minifyEnabled true // Enables code shrinking for the release build type.
              proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }

    /**
     * The productFlavors block is where you can configure multiple product flavors.
     * This lets you create different versions of your app that can
     * override the defaultConfig block with their own settings. Product flavors
     * are optional, and the build system does not create them by default.
     *
     * This example creates a free and paid product flavor. Each product flavor
     * then specifies its own application ID, so that they can exist on the Google
     * Play Store or an Android device simultaneously.
     *
     * If you declare product flavors, you must also declare flavor dimensions
     * and assign each flavor to a flavor dimension.
     */

    flavorDimensions "tier"
    productFlavors {
        free {
            dimension "tier"
            applicationId 'com.example.myapp.free'
        }

        paid {
            dimension "tier"
            applicationId 'com.example.myapp.paid'
        }
    }

    /**
     * To override source and target compatibility (if different from the
     * tool chain JDK version), add the following. All of these
     * default to the same value as kotlin.jvmToolchain. If you're using the
     * same version for these values and kotlin.jvmToolchain, you can
     * remove these blocks.
     */
    //compileOptions {
    //    sourceCompatibility JavaVersion.VERSION_11
    //    targetCompatibility JavaVersion.VERSION_11
    //}
    //kotlinOptions {
    //    jvmTarget = '11'
    //}
}

/**
 * The dependencies block in the module-level build configuration file
 * specifies dependencies required to build only the module itself.
 * To learn more, go to Add build dependencies.
 */

dependencies {
    implementation project(":lib")
    implementation 'androidx.appcompat:appcompat:1.7.0'
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

فایل های ویژگی های Gradle

gradle.properties

local.properties

ویژگی های محیط محلی را برای سیستم ساخت پیکربندی می کند، از جمله موارد زیر:

ndk.dir - مسیر NDK. این ملک منسوخ شده است. همه نسخه‌های دانلود شده NDK در فهرست ndk در فهرست راهنمای Android SDK نصب می‌شوند.
sdk.dir - مسیری به Android SDK.
cmake.dir - مسیر CMake.
ndk.symlinkdir - در Android Studio نسخه 3.5 و بالاتر، یک پیوند نمادین به NDK ایجاد می کند که می تواند کوتاهتر از مسیر NDK نصب شده باشد.

NDK را به یک مسیر کوتاه‌تر (فقط برای ویندوز) ترسیم کنید

همگام سازی پروژه با فایل های Gradle

مجموعه های منبع

src/main/: این مجموعه منبع شامل کد و منابع مشترک برای همه انواع ساخت است.
src/ buildType /: این مجموعه منبع را ایجاد کنید تا شامل کد و منابع فقط برای یک نوع ساخت خاص باشد.
src/ productFlavor /: این مجموعه منبع را به گونه‌ای ایجاد کنید که کد و منابع را فقط برای طعم محصول خاص شامل شود.
توجه: اگر بیلد خود را طوری پیکربندی کنید که چندین طعم محصول را ترکیب کند ، می‌توانید فهرست‌های منبع مجموعه را برای هر ترکیبی از طعم‌های محصول بین ابعاد طعم ایجاد کنید: src/ productFlavor1 ProductFlavor2 / .
src/ productFlavorBuildType /: این مجموعه منبع را ایجاد کنید تا شامل کد و منابع فقط برای یک نوع ساخت خاص باشد.

src/fullDebug/ (مجموعه منبع نوع ساخت)
src/debug/ (مجموعه منبع نوع ساخت)
src/full/ (مجموعه منبع طعم محصول)
src/main/ (مجموعه منبع اصلی)

نوع ساخت > نوع ساخت > طعم محصول > مجموعه منبع اصلی > وابستگی های کتابخانه

کاتالوگ های نسخه

سیستم های ساخت دیگر

برای درک بهتر محدودیت‌های فعلی ساختمان با Bazel، به مسائل شناخته شده مراجعه کنید.