إنشاء تطبيقك من سطر الأوامر

يمكنك تنفيذ جميع مهام الإنشاء المتاحة لمشروع Android باستخدام أداة سطر الأوامر Gradle wrapper. وهو متاح كملف دفعي لنظام التشغيل Windows (gradlew.bat) وملف برمجي لنظام التشغيل Linux وMac (gradlew.sh)، ويمكن الوصول إليه من جذر كل مشروع تنشئه باستخدام استوديو Android.

لتشغيل مهمة باستخدام الغلاف، استخدِم أحد الأوامر التالية من نافذة Terminal (من "استوديو Android"، اختَر عرض > نوافذ الأدوات > Terminal):

• في "قشرة الأوامر" في نظام التشغيل Windows:

  gradlew task-name

• على نظام التشغيل Mac أو Linux أو Windows PowerShell:

  ./gradlew task-name

للاطّلاع على قائمة بجميع مهام الإنشاء المتاحة لمشروعك، نفِّذ tasks:

gradlew tasks

توضّح بقية هذه الصفحة الأساسيات اللازمة لإنشاء تطبيقك وتشغيله باستخدام حزمة Gradle. لمزيد من المعلومات حول كيفية إعداد إصدار Android، يُرجى الاطّلاع على مقالة ضبط إصدارك.

إذا كنت تفضّل استخدام أدوات "استوديو Android" بدلاً من أدوات سطر الأوامر، يمكنك الاطّلاع على مقالة إنشاء تطبيقك وتشغيله.

لمحة عن أنواع الإصدارات

يتوفّر تلقائيًا نوعان من الإصدارات لكل تطبيق Android: أحدهما لإصلاح أخطاء تطبيقك، وهو الإصدار debug، والآخر لإصدار تطبيقك للمستخدمين، وهو الإصدار release. يجب توقيع النتيجة الناتجة من كل إصدار باستخدام شهادة قبل أن تتمكّن من نشر تطبيقك على جهاز. يتم توقيع إصدار تصحيح الأخطاء تلقائيًا باستخدام مفتاح تصحيح أخطاء تقدّمه أدوات IDE (وهو غير آمن ولا يمكنك نشره على "متجر Google Play")، ويجب توقيع إصدار الإصدار باستخدام مفتاحك الخاص.

إذا أردت إنشاء تطبيقك لإصداره، من المهم أيضًا توقيع تطبيقك باستخدام مفتاح التوقيع المناسب. إذا كنت مبتدئًا، يمكنك تشغيل تطبيقاتك بسرعة على أحد المحاكيات أو على جهاز متصل من خلال إنشاء حزمة APK لفحص الأخطاء.

يمكنك أيضًا تحديد نوع إصدار مخصّص في ملف build.gradle.kts وضبطه ليتم توقيعه كإصدار تصحيح أخطاء من خلال تضمين debuggable true. لمزيد من المعلومات، اطّلِع على ضبط خيارات الإصدار.

إنشاء حِزمة APK ونشرها

على الرغم من أنّ إنشاء حِزمة تطبيق هو أفضل طريقة لشدَّد حزمة تطبيقك وتحميلها إلى Play Console، إلا أنّ إنشاء حِزمة APK هو الخيار الأنسب لاختبار إصدار تصحيح أخطاء بسرعة أو مشاركة تطبيقك مع الآخرين كعنصر قابل للنشر.

إنشاء حزمة APK مخصّصة لتصحيح الأخطاء

لاختبار التطبيق وتصحيح الأخطاء فيه على الفور، يمكنك إنشاء حزمة APK مخصّصة لتصحيح الأخطاء. يتم توقيع حزمة APK المخصّصة لتصحيح الأخطاء باستخدام مفتاح تصحيح أخطاء تقدّمه أدوات حزمة SDK، ويسمح بتصحيح الأخطاء من خلال adb.

لإنشاء حزمة APK لإصدار تجريبي، افتح سطر أوامر وانتقِل إلى جذر directory المشروع. لبدء عملية إنشاء إصدار لتصحيح الأخطاء، يمكنك استدعاء مهمة assembleDebug:

gradlew assembleDebug

يؤدي ذلك إلى إنشاء حزمة APK باسم module_name-debug.apk في project_name/module_name/build/outputs/apk/. سبق توقيع الملف باستخدام مفتاح تصحيح الأخطاء ومواءمته مع zipalign، لذا يمكنك تثبيته على الفور على جهاز.

أو لإنشاء حزمة APK وتثبيتها على الفور على جهاز محاكاة أو جهاز متصل، يمكنك بدلاً من ذلك استخدام installDebug:

gradlew installDebug

الجزء "تصحيح الأخطاء" في أسماء المهام أعلاه هو مجرد نسخة بتنسيق camel-case من اسم صيغة الإصدار، لذا يمكن استبداله بأي نوع أو صيغة إصدار تريد تجميعها أو تثبيتها. على سبيل المثال، إذا كان لديك ملف APK لإصدار "تجريبي" من المنتج، يمكنك إنشاء إصدار تصحيح الأخطاء باستخدام مهمة assembleDemoDebug.

للاطّلاع على جميع مهام الإنشاء والتثبيت المتاحة لكل إصدار (بما في ذلك مهام إلغاء التثبيت)، يمكنك تنفيذ مهمة tasks.

اطّلِع أيضًا على القسم المخصص لكيفية تشغيل تطبيقك على المحاكي وتشغيل تطبيقك على جهاز.

إنشاء حِزمة إصدار أو حِزمة APK

عندما تكون مستعدًا لإصدار تطبيقك وتوزيعه، عليك إنشاء حِزمة إصدار أو حِزمة APK موقَّعة بمفتاحك الخاص. لمزيد من المعلومات، انتقِل إلى القسم الذي يتناول كيفية توقيع تطبيقك من سطر الأوامر.

نشر تطبيقك على المحاكي

لاستخدام "محاكي Android"، عليك إنشاء جهاز افتراضي (AVD) على "استوديو Android".

بعد إنشاء جهاز افتراضي Android، ابدأ تشغيل "محاكي 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.

نشر تطبيقك على جهاز فعلي

قبل أن تتمكّن من تشغيل تطبيقك على جهاز، عليك تفعيل تصحيح أخطاء برمجة التطبيقات باستخدام يو إس بي على جهازك. يمكنك العثور على الخيار ضمن الإعدادات > خيارات المطوّرين.

ملاحظة: في الإصدار 4.2 من نظام التشغيل Android والإصدارات الأحدث، خيارات المطوّرين مخفية تلقائيًا. لإتاحة هذه الميزة، انتقِل إلى الإعدادات > لمحة عن الهاتف وانقر على رقم الإصدار سبع مرات. ارجع إلى الشاشة السابقة للعثور على خيارات المطوّرين.

بعد إعداد جهازك وربطه عبر 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 Console، عليك أولاً ضبط ملف build.gradle.kts الخاص بالوحدة الأساسية باستخدام معلومات توقيع تطبيقك. لمزيد من المعلومات، انتقِل إلى القسم الذي يتناول كيفية ضبط Gradle لتوقيع تطبيقك. يمكنك بعد ذلك، على سبيل المثال، إنشاء إصدار التطبيق العلني، ويعمل Gradle على توليد حِزمة تطبيق تلقائيًا ويوقّعها باستخدام معلومات التوقيع التي تقدّمها في ملف build.gradle.kts.

إذا كنت تريد بدلاً من ذلك توقيع حِزمة تطبيق كخطوة منفصلة، يمكنك استخدام jarsigner لتوقيع حِزمة تطبيقك من سطر الأوامر. الأمر لإنشاء حِزمة تطبيق هو:

jarsigner -keystore pathToKeystore app-release.aab keyAlias

إنشاء حِزمة تطبيق باستخدام أداة bundletool

bundletool هي أداة سطر أوامر يستخدمها "استوديو Android" و"مكوّن إضافي" Gradle لنظام Android وGoogle Play لتحويل الرموز المُجمَّعة وموارد تطبيقك إلى حِزم تطبيقات، وإنشاء حِزم APK قابلة للنشر من هذه الحِزم.

على الرغم من أنّه من المفيد اختبار حزم التطبيقات باستخدام bundletool وإعادة إنشاء طريقة Google Play في إنشاء حِزم APK على الجهاز، لن تحتاج عادةً إلى استدعاء bundletool لإنشاء حِزمة التطبيق نفسها، بل عليك بدلاً من ذلك استخدام Android Studio أو مهام Gradle كما هو موضّح في الأقسام السابقة.

ومع ذلك، إذا كنت لا تريد استخدام "استوديو Android" أو مهام Gradle لإنشاء الحِزم، على سبيل المثال، إذا كنت تستخدم مجموعة أدوات إنشاء مخصّصة، يمكنك استخدام bundletool من سطر الأوامر لإنشاء حِزمة تطبيق من الرموز البرمجية المُجمَّعة مسبقًا والمواد المرجعية. في حال عدم إجراء ذلك من قبل، نزِّل bundletool من مستودع GitHub.

يصف هذا القسم كيفية تجميع الرموز البرمجية والموارد في تطبيقك، وكيفية استخدام bundletool من سطر الأوامر لتحويلها إلى مجموعة حزمات تطبيق Android.

إنشاء البيان والموارد بتنسيق proto

تتطلّب bundletool أن تكون معلومات معيّنة عن مشروع تطبيقك، مثل بيان التطبيق وموارده، بتنسيق Google Protocol Buffer، والذي يُعرَف أيضًا باسم "protobuf" ويستخدم امتداد الملف *.pb. توفّر ملفات Protobuf آلية قابلة للتوسيع وغير محايدة من حيث اللغة والنظام الأساسي لسلسلة البيانات المنظَّمة، وهي مشابهة لـ XML، ولكنها أصغر حجمًا وأسرع و أبسط.

تنزيل أداة AAPT2

يمكنك إنشاء ملف البيان وجدول الموارد لتطبيقك بتنسيق protobuf باستخدام أحدث إصدار من AAPT2 من مستودع Google Maven.

لتنزيل AAPT2 من مستودع Maven في Google، اتّبِع الخطوات التالية:

1. انتقِل إلى com.android.tools.build > aapt2 في فهرس المستودع.
2. انسخ اسم أحدث إصدار من AAPT2.

3. أدخِل اسم الإصدار الذي نسخته في عنوان URL التالي وحدِّد نظام التشغيل المستهدَف: 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. انتقِل إلى عنوان URL في متصفّح، ومن المفترض أن يبدأ تنزيل 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 لتحويل بيان تطبيقك ومواردك المجمّعة إلى تنسيق protobuf من خلال تضمين العلامة --proto-format، كما هو موضّح أدناه:

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

لإنشاء حِزمة تطبيقك، استخدِم الأمر bundletool build-bundle كما هو موضح أدناه:

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

يوضّح الجدول التالي أعلام الأمر build-bundle بمزيد من detail:

تخصيص إنشاء حِزم APK للأجهزة الطرفية

تتضمّن حِزم التطبيقات ملف BundleConfig.pb يقدّم البيانات الوصفية التي تتطلّبها متاجر التطبيقات، مثل Google Play، عند إنشاء حِزم APK من الحِزمة. على الرغم من أنّ أداة bundletool تنشئ هذا الملف نيابةً عنك، يمكنك ضبط بعض جوانب البيانات الوصفية في ملف BundleConfig.json ونقله إلى الأمر bundletool build-bundle. وستحوّل أداة bundletool هذا الملف وتدمجه لاحقًا مع إصدار protobuf المضمّن في كل حِزمة تطبيق.

على سبيل المثال، يمكنك التحكّم في فئات حِزم APK الخاصة بالضبط التي تريد تفعيلها أو إيقافها. في المثال التالي لملف BundleConfig.json، يتم إيقاف حِزم APK الخاصة بالضبط التي تستهدف كلٌّ منها لغة مختلفة (أي أنّه يتم تضمين موارد لجميع اللغات في حِزم APK الخاصة بالميزات أو حِزم APK الأساسية الخاصة بكل لغة):

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

في ملف BundleConfig.json، يمكنك أيضًا تحديد أنواع الملفات التي تريد إبقاؤها غير مضغوطة عند تجميع حِزم APK باستخدام نماذج globbing، على النحو التالي:

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

يُرجى العِلم أنّ أداة bundletool لا تُضغط تلقائيًا مكتبات التطبيقات الأصلية (على نظام التشغيل Android 6.0 أو الإصدارات الأحدث) وجدول الموارد (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

يطلب منك المثال أعلاه إدخال كلمات المرور لمستودع المفاتيح والمفتاح، و حقول "الاسم المميّز" لمفتاحك. بعد ذلك، يتم إنشاء ملف ملف تخزين مفاتيح باسم my-release-key.jks، ويتم حفظه في الدليل الحالي (يمكنك نقله إلى أي مكان تريده). يحتوي ملف تخزين المفاتيح على مفتاح واحد صالح لمدة 10,000 يوم.

يمكنك الآن توقيع حِزمة APK أو حِزمة التطبيق يدويًا، أو ضبط Gradle لتوقيع تطبيقك أثناء عملية التصميم، كما هو موضّح في الأقسام أدناه.

توقيع تطبيقك يدويًا من سطر الأوامر

إذا كنت تريد توقيع حِزمة تطبيق من سطر الأوامر، يمكنك استخدام jarsigner. إذا أردت بدلاً من ذلك توقيع حِزمة APK، عليك استخدام zipalign وapksigner كما هو موضّح أدناه.

1. افتح سطر أوامر: من Android Studio، اختَر عرض > نوافذ الأدوات > المحطة الطرفية، وانتقِل إلى الدليل الذي يقع فيه ملف APK غير الموقَّع.

2. يمكنك محاذاة حزمة APK غير الموقَّعة باستخدام zipalign:

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

   تضمن zipalign أن تبدأ جميع البيانات غير المضغوطة بأحد تنسيقات zipalign الخاصة بمحاذاة البايتات بالنسبة إلى بداية الملف، ما قد يؤدي إلى خفض كمية ذاكرة الوصول العشوائي التي يستهلكها التطبيق.

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 بعد توقيعها باستخدام مفتاح خاص وشهادة مخزَّنَين في ملف KeyStore واحد: my-release-key.jks.

   تتيح أداة apksigner خيارات توقيع أخرى، بما في ذلك توقيع ملف APK باستخدام ملفات مفتاح خاص وشهادة منفصلة، و توقيع حزمة APK باستخدام جهات توقيع متعدّدة. لمزيد من التفاصيل، يُرجى الاطّلاع على مرجع apksigner.

   ملاحظة: لاستخدام أداة apksigner، يجب تثبيت الإصدار 24.0.3 أو إصدار أحدث من أدوات إنشاء حزمة تطوير البرامج (SDK) لنظام التشغيل Android. يمكنك تحديث هذه الحزمة باستخدام أداة إدارة حِزم SDK.

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.