ساختن برنامه از خط فرمان

می‌توانید همه وظایف ساخت دردسترس برای پروژه Android خود را بااستفاده از ابزار خط فرمان پوشش Gradle اجرا کنید. این ابزار به‌صورت فایل دسته‌ای برای Windows (gradlew.bat) و یک اسکریپت شل برای Linux و Mac (gradlew.sh) دردسترس است و از ریشه هر پروژه‌ای که با «استودیو Android» ایجاد می‌کنید قابل‌دسترسی است.

برای اجرای تکلیف با بسته‌بند، از یکی از فرمان‌های زیر در پنجره Terminal (از Android Studio، View > Tool Windows > Terminal را انتخاب کنید) استفاده کنید:

• در Windows Command Shell:

  gradlew task-name

• در Mac،‏ Linux، یا Windows PowerShell:

  ./gradlew task-name

برای دیدن فهرست همه وظایف ساخت دردسترس برای پروژه‌تان، tasks را اجرا کنید:

gradlew tasks

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

اگر ترجیح می‌دهید به‌جای ابزارهای خط فرمان از ابزارهای Android Studio استفاده کنید، به ساختن و اجرای برنامه مراجعه کنید.

درباره انواع ساخت

به‌طور پیش‌فرض، دو نوع ساخت برای هر برنامه Android دردسترس است: یکی برای اشکال‌زدایی برنامه—ساخت اشکال‌زدایی—و یکی برای انتشار برنامه برای کاربران—ساخت انتشار. پیش‌از اینکه بتوانید برنامه‌تان را در دستگاهی مستقر کنید، برونداد حاصل از هر ساخت باید با گواهینامه‌ای امضا شود. ساخت اشکال‌زدایی به‌طور خودکار با کلید اشکال‌زدایی ارائه‌شده توسط ابزارهای کیت توسعه نرم‌افزار امضا می‌شود (این کلید ناامن است و نمی‌توانید با آن در «فروشگاه Google Play» منتشر کنید)، و ساخت انتشار باید با کلید خصوصی خودتان امضا شود.

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

همچنین می‌توانید نوع ساخت سفارشی را در build.gradle.kts فایل خود تعریف کنید و آن را پیکربندی کنید تا با افزودن debuggable true به‌عنوان ساخت اشکال‌زدایی امضا شود. برای اطلاعات بیشتر، پیکربندی گونه‌های ساخت را ببینید.

ساختن و مستقر کردن فایل APK

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

ساختن APK اشکال‌زدایی

برای آزمایش و اشکال‌زدایی فوری برنامه، می‌توانید APK اشکال‌زدایی بسازید. ‫APK اشکال‌زدایی با کلید اشکال‌زدایی ارائه‌شده توسط ابزارهای کیت توسعه نرم‌افزار امضا شده است و اشکال‌زدایی ازطریق adb را امکان‌پذیر می‌کند.

برای ساختن فایل APK اشکال‌زدایی، خط فرمان را باز کنید و به ریشه دایرکتوری پروژه پیمایش کنید. برای شروع ساخت اشکال‌زدایی، تکلیف assembleDebug را فراخوانی کنید:

gradlew assembleDebug

با این کار، فایل APK به‌نام module_name-debug.apk در project_name/module_name/build/outputs/apk/ ایجاد می‌شود. فایل ازقبل با کلید اشکال‌زدایی امضا شده است و با zipalign تراز شده است، بنابراین می‌توانید آن را بلافاصله در دستگاه نصب کنید.

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

gradlew installDebug

بخش «Debug» در نام‌های تکلیف بالا فقط نسخه حروف‌شتر نام گونه ساخت است، بنابراین می‌توانید آن را با هر نوع ساخت یا گونه‌ای که می‌خواهید مونتاژ یا نصب کنید جایگزین کنید. برای مثال، اگر طعم محصول «نسخه نمایشی» دارید، می‌توانید نسخه اشکال‌زدایی را با تکلیف assembleDemoDebug بسازید.

برای دیدن همه تکالیف ساخت و نصب دردسترس برای هر گونه (ازجمله تکالیف حذف نصب)، تکلیف tasks را اجرا کنید.

همچنین بخش مربوط به نحوه اجرای برنامه در شبیه‌ساز و اجرای برنامه در دستگاه را ببینید.

ساختن دسته برنامه یا فایل APK نسخه پخش

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

استقرار برنامه در شبیه‌ساز

برای استفاده از «شبیه‌ساز Android»، باید بااستفاده از «استودیو Android» دستگاه مجازی Android (AVD) ایجاد کنید.

پس‌از اینکه AVD را داشتید، «شبیه‌ساز Android» را شروع کنید و برنامه خود را به‌صورت زیر نصب کنید:

1. در خط فرمان، به android_sdk/tools/ پیمایش کنید و شبیه‌ساز را با مشخص کردن AVD شروع کنید:

   emulator -avd avd_name

   اگر از نام AVD مطمئن نیستید، emulator -list-avds را اجرا کنید.

2. اکنون می‌توانید برنامه‌تان را بااستفاده از یکی از وظایف نصب Gradle که در بخش مربوط به نحوه ساختن APK اشکال‌زدایی یا ابزار adb ذکر شده است نصب کنید.

   اگر فایل APK بااستفاده از کیت توسعه نرم‌افزار پیش‌نمایش توسعه‌دهنده ساخته شده باشد (اگر targetSdkVersion به‌جای عدد حرف باشد)، باید گزینه -t را با فرمان install برای نصب فایل APK آزمایشی اضافه کنید.

   adb install path/to/your_app.apk
   

   همه فایل‌های APK که می‌سازید در project_name/module_name/build/outputs/apk/ ذخیره می‌شود.

برای اطلاعات بیشتر، اجرای برنامه‌ها در شبیه‌ساز Android را ببینید.

استقرار برنامه در دستگاه فیزیکی

قبل‌از اینکه بتوانید برنامه‌تان را در دستگاه اجرا کنید، باید عیب‌یابی USB را در دستگاهتان فعال کنید. می‌توانید این گزینه را در تنظیمات > گزینه‌های توسعه‌دهندگان پیدا کنید.

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

پس‌از راه‌اندازی و اتصال دستگاه ازطریق USB، می‌توانید برنامه‌تان را بااستفاده از وظایف نصب Gradle که در بخش مربوط به نحوه ساختن APK اشکال‌زدایی ذکر شده است یا بااستفاده از ابزار adb نصب کنید:

adb -d install path/to/your_app.apk

همه فایل‌های APK که می‌سازید در project_name/module_name/build/outputs/apk/ ذخیره می‌شود.

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

ساختن بسته برنامه

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

آسان‌ترین راه برای ساختن بسته برنامه استفاده از «استودیو Android» است. بااین‌حال، اگر نیاز دارید بسته برنامه را از خط فرمان بسازید، می‌توانید بااستفاده از Gradle یا bundletool، همان‌طور که در بخش‌های زیر توضیح داده شده است، این کار را انجام دهید.

ساختن بسته برنامه با Gradle

اگر ترجیح می‌دهید دسته برنامه را از خط فرمان تولید کنید، bundleVariant تکلیف Gradle را در واحد پایه برنامه‌تان اجرا کنید. برای مثال، فرمان زیر بسته برنامه را برای نسخه اشکال‌زدایی واحد پایه می‌سازد:

./gradlew :base:bundleDebug

اگر می‌خواهید دسته‌ای امضاشده برای بارگذاری در «کنسول Play» بسازید، باید ابتدا فایل build.gradle.kts واحد پایه را با اطلاعات امضای برنامه‌تان پیکربندی کنید. برای کسب اطلاعات بیشتر، به بخش مربوط به نحوه پیکربندی Gradle برای امضای برنامه بروید. سپس می‌توانید، برای مثال، نسخه انتشار برنامه خود را بسازید و Gradle به‌طور خودکار دسته برنامه ایجاد می‌کند و آن را با اطلاعات امضایی که در فایل build.gradle.kts ارائه می‌دهید امضا می‌کند.

اگر می‌خواهید بسته برنامه را به‌عنوان یک مرحله جداگانه امضا کنید، می‌توانید از jarsigner برای امضا کردن بسته برنامه از خط فرمان استفاده کنید. فرمان ساختن بسته برنامه این است:

jarsigner -keystore pathToKeystore app-release.aab keyAlias

ساختن بسته برنامه بااستفاده از بسته‌ابزار

‫bundletool ابزار خط فرمانی است که Android Studio، افزایه Android Gradle، و Google Play از آن برای تبدیل کد و منابع کامپایل‌شده برنامه به دسته‌های برنامه و تولید فایل‌های APK قابل‌توزیع از آن دسته‌ها استفاده می‌کنند.

بنابراین، اگرچه آزمایش دسته‌های برنامه با bundletool و بازآفرینی محلی نحوه تولید فایل‌های APK توسط Google Play مفید است، معمولاً نیازی به فراخوانی bundletool برای ساختن خود دسته برنامه ندارید—درعوض باید از Android Studio یا وظایف Gradle استفاده کنید، همان‌طور که در بخش‌های قبلی توضیح داده شد.

بااین‌حال، اگر نمی‌خواهید از Android Studio یا وظایف Gradle برای ساختن دسته‌ها استفاده کنید—برای مثال، اگر از زنجیره ابزار ساخت سفارشی استفاده می‌کنید—می‌توانید از bundletool در خط فرمان برای ساختن بسته برنامه از کد و منابع ازپیش‌کامپایل‌شده استفاده کنید. اگر قبلاً این کار را نکرده‌اید، bundletool را از مخزن GitHub بارگیری کنید.

این بخش توضیح می‌دهد که چگونه کد و منابع کامپایل‌شده برنامه‌تان را بسته‌بندی کنید و چگونه از bundletool در خط فرمان برای تبدیل آن‌ها به Android App Bundle استفاده کنید.

تولید مانیفست و منابع در قالب proto

‫bundletool برای پروژه برنامه‌تان به اطلاعات خاصی نیاز دارد، مثلاً بیانیه و منابع برنامه باید در قالب «بافر پروتکل Google» باشد—که به‌عنوان «protobuf» نیز شناخته می‌شود و از پسوند فایل *.pb استفاده می‌کند. Protobufs سازوکاری زبان‌مستقل، پلاتفرم‌مستقل، و توسعه‌پذیر برای سریال‌سازی داده‌های ساختاریافته ارائه می‌دهد—شبیه به XML است، اما کوچک‌تر، سریع‌تر، و ساده‌تر است.

بارگیری AAPT2

می‌توانید فایل مانیفست و جدول منبع برنامه‌تان را در قالب protobuf بااستفاده از جدیدترین نسخه AAPT2 از مخزن Google Maven تولید کنید.

برای بارگیری AAPT2 از مخزن Maven متعلق به Google، به این ترتیب عمل کنید:

1. در نمایه مخزن به com.android.tools.build > aapt2 پیمایش کنید.
2. نام جدیدترین نسخه AAPT2 را کپی کنید.

3. نام نسخه‌ای را که کپی کرده‌اید در نشانی وب زیر درج کنید و سیستم عامل هدف خود را مشخص کنید: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

   برای مثال، برای بارگیری نسخه 3.2.0-alpha18-4804415 برای Windows، از این نشانی استفاده می‌کنید: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

4. در مرورگر به نشانی وب پیمایش کنید—AAPT2 باید به‌زودی بارگیری را شروع کند.

5. فایل JAR را که همین حالا بارگیری کردید از بسته‌بندی خارج کنید.

منابع برنامه را گردآوری و پیوند دهید

از AAPT2 برای گردآوری منابع برنامه با فرمان زیر استفاده کنید:

aapt2 compile \
project_root/module_root/src/main/res/drawable/Image1.png \
project_root/module_root/src/main/res/drawable/Image2.png \
-o compiled_resources/

در مرحله پیوند، که در آن AAPT2 منابع کامپایل‌شده مختلف شما را در یک فایل APK واحد پیوند می‌دهد، به AAPT2 دستور دهید تا مانیفست برنامه و منابع کامپایل‌شده شما را با افزودن پرچم --proto-format به قالب protobuf تبدیل کند، همان‌طور که در زیر نشان داده شده است:

aapt2 link --proto-format -o output.apk \
-I android_sdk/platforms/android_version/android.jar \
--manifest project_root/module_root/src/main/AndroidManifest.xml \
-R compiled_resources/*.flat \
--auto-add-overlay

سپس می‌توانید محتوا را از APK برونداد استخراج کنید، مثلاً AndroidManifest.xml برنامه، resources.pb، و دیگر فایل‌های منبع—اکنون در قالب protobuf. هنگام آماده کردن ورودی به این فایل‌ها نیاز دارید bundletool برای ساختن بسته برنامه شما لازم است، همان‌طور که در بخش زیر توضیح داده شده است.

بسته کردن کد و منابع ازپیش‌کامپایل‌شده

قبل‌از اینکه از bundletool برای تولید بسته برنامه برای برنامه‌تان استفاده کنید، باید ابتدا فایل‌های ZIP ارائه دهید که هرکدام حاوی کد و منابع گردآوری‌شده برای واحد برنامه معینی باشد. محتوا و سازماندهی فایل ZIP هر واحد بسیار شبیه به قالب «بسته برنامه Android» است. برای مثال، باید فایل base.zip را برای واحد پایه برنامه‌تان ایجاد کنید و محتوای آن را به‌صورت زیر سازمان‌دهی کنید:

پس‌از آماده کردن فایل ZIP برای هریک از واحدهای برنامه، می‌توانید آن‌ها را به bundletool بدهید تا بسته برنامه‌تان را بسازد، همان‌طور که در بخش زیر توضیح داده شده است.

ساختن بسته برنامه بااستفاده از بسته‌ابزار

برای ساختن بسته برنامه، از فرمان bundletool build-bundle، همان‌طور که در زیر نشان داده شده است، استفاده می‌کنید:

bundletool build-bundle --modules=base.zip --output=mybundle.aab

جدول زیر پرچم‌های فرمان build-bundle را با جزئیات بیشتر شرح می‌دهد:

سفارشی‌سازی تولید APK پایین‌دست

دسته‌های برنامه شامل فایل BundleConfig.pb است که فراداده‌هایی را ارائه می‌دهد که فروشگاه‌های برنامه، مثل Google Play، هنگام تولید فایل‌های APK از دسته برنامه به آن‌ها نیاز دارند. اگرچه bundletool این فایل را برای شما ایجاد می‌کند، می‌توانید برخی‌از جنبه‌های فراداده را در فایل BundleConfig.json پیکربندی کنید و آن را به دستور bundletool build-bundle ارسال کنید—bundletool بعداً این فایل را تبدیل می‌کند و با نسخه protobuf موجود در هر بسته برنامه ادغام می‌کند.

برای مثال، می‌توانید کنترل کنید کدام دسته‌های پیکربندی APK فعال یا غیرفعال شوند. مثال زیر از فایل BundleConfig.json فایل‌های پیکربندی APK را که هرکدام زبان متفاوتی را هدف‌یابی می‌کنند غیرفعال می‌کند (یعنی، منابع همه زبان‌ها در فایل‌های APK پایه یا ویژگی مربوطه گنجانده شده است):

{
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [{
        "value": "LANGUAGE",
        "negate": true
      }]
    }
  }
}

در فایل BundleConfig.json، همچنین می‌توانید مشخص کنید که هنگام بسته‌بندی فایل‌های APK بااستفاده از الگوهای glob، کدام نوع فایل‌ها فشرده نشوند، به این صورت:

{
  "compression": {
    "uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
  }
}

به‌خاطر داشته باشید که به‌طور پیش‌فرض، bundletool کتابخانه‌های بومی برنامه شما (در Android نسخه ۶.۰ یا بالاتر) و جدول منبع (resources.arsc) را فشرده نمی‌کند. برای شرح کامل آنچه می‌توانید در BundleConfig.json پیکربندی کنید، فایل bundletool config.proto را که بااستفاده از دستورگان Proto3 نوشته شده است بازرسی کنید.

استقرار برنامه از بسته برنامه

اگر دسته برنامه‌ای ساخته و امضا کرده‌اید، از bundletool برای تولید فایل‌های APK و استقرار آن‌ها در دستگاه استفاده کنید.

امضای برنامه از خط فرمان

برای امضای برنامه به Android Studio نیاز ندارید. می‌توانید برنامه را از خط فرمان بااستفاده از apksigner برای فایل‌های APK یا jarsigner برای دسته‌های برنامه امضا کنید، یا Gradle را پیکربندی کنید تا برنامه را درطول ساخت برایتان امضا کند. در هرصورت، ابتدا باید بااستفاده از keytool کلید خصوصی تولید کنید، همان‌طور که در زیر نشان داده شده است:

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias

مثال بالا از شما گذرواژه‌های keystore و کلید را می‌خواهد و همچنین فیلدهای «نام متمایز» را برای کلیدتان می‌خواهد. سپس آن را به‌عنوان فایل my-release-key.jks تولید می‌کند و در دایرکتوری فعلی ذخیره می‌کند (می‌توانید آن را به هر جایی که می‌خواهید منتقل کنید). انبار کلید حاوی یک کلید است که برای ۱۰٬۰۰۰ روز معتبر است.

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

امضای دستی برنامه از خط فرمان

اگر می‌خواهید بسته برنامه‌ای را از خط فرمان امضا کنید، می‌توانید از jarsigner استفاده کنید. اگر درعوض می‌خواهید فایل APK را امضا کنید، باید از zipalign و apksigner به‌شرح زیر استفاده کنید.

1. خط فرمان را باز کنید—از Android Studio، View (نما) > Tool Windows (پنجره‌های ابزار) > Terminal (پایانه) را انتخاب کنید—و به دایرکتوری که فایل APK بدون امضای شما در آن قرار دارد بروید.

2. فایل APK امضانشده را بااستفاده از zipalign تراز کنید:

   zipalign -v -p 4 my-app-unsigned.apk my-app-unsigned-aligned.apk
   

   ‫zipalign تضمین می‌کند که همه داده‌های فشرده‌نشده با تراز بایت خاصی نسبت‌به ابتدای فایل شروع شود، که ممکن است مقدار RAM مصرف‌شده توسط برنامه را کاهش دهد.

3. ‫APK را با کلید خصوصی‌تان بااستفاده از apksigner امضا کنید:

   apksigner sign --ks my-release-key.jks --out my-app-release.apk my-app-unsigned-aligned.apk
   

   این مثال فایل APK امضاشده را در my-app-release.apk پس‌از امضا کردن آن با کلید خصوصی و گواهینامه‌ای که در یک فایل «حافظه کلید» ذخیره شده است برون‌برد می‌کند: my-release-key.jks.

   ابزار apksigner از گزینه‌های امضای دیگر، ازجمله امضای فایل APK بااستفاده از کلید خصوصی و فایل‌های گواهینامه جداگانه، و امضای APK بااستفاده از چند امضاکننده پشتیبانی می‌کند. برای جزئیات بیشتر، به apksigner مرجع مراجعه کنید.

   توجه: برای استفاده از ابزار apksigner، باید نسخه ۲۴.۰.۳ یا بالاتر از «ابزارهای ساخت کیت توسعه نرم‌افزار Android» را نصب کرده باشید. می‌توانید این بسته را بااستفاده از مدیر کیت توسعه نرم‌افزار به‌روز کنید.

4. تأیید کنید که APK شما امضا شده است:

   apksigner verify my-app-release.apk
   

پیکربندی Gradle برای امضا کردن برنامه

فایل build.gradle.kts سطح واحد را باز کنید و بلوک signingConfigs {} را با ورودی‌های storeFile، storePassword، keyAlias، و keyPassword اضافه کنید، سپس آن شیء را به signingConfig دارایی در نوع ساخت خود منتقل کنید. برای مثال:

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        create("release") {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile = file("my-release-key.jks")
            storePassword = "password"
            keyAlias = "my-alias"
            keyPassword = "password"
        }
    }
    buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            ...
        }
    }
}

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        release {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile file("my-release-key.jks")
            storePassword "password"
            keyAlias "my-alias"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            ...
        }
    }
}

اکنون، وقتی با فراخوانی وظیفه Gradle برنامه خود را می‌سازید، Gradle برنامه شما را امضا می‌کند (و zipalign را اجرا می‌کند).

علاوه‌براین، چون ساختار نسخه پخش را با کلید امضای خودتان پیکربندی کرده‌اید، وظیفه «نصب» برای آن نوع ساختار دردسترس است. بنابراین می‌توانید APK نسخه پخش را در شبیه‌ساز یا دستگاه بسازید، تراز کنید، امضا کنید، و نصب کنید، همه با installRelease تکلیف.

برنامه‌ای که با کلید خصوصی‌تان امضا شده است برای توزیع آماده است، اما ابتدا باید درباره نحوه انتشار برنامه بیشتر بخوانید و فهرست وارسی راه‌اندازی Google Play را مرور کنید.