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

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

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

• في Windows Command Shell:

  gradlew task-name
  

• على أجهزة Mac أو Linux أو Windows PowerShell:

  ./gradlew task-name
  

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

gradlew tasks

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

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

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

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

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

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

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

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

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

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

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

gradlew assembleDebug

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

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

gradlew installDebug

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

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

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

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

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

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

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

بعد إنشاء جهاز Android افتراضي، ابدأ تشغيل Android Emulator وثبِّت تطبيقك على النحو التالي:

1. في سطر الأوامر، انتقِل إلى android_sdk/tools/ وابدأ تشغيل المحاكي من خلال تحديد جهاز Android الافتراضي (AVD):

   emulator -avd <var>avd_name</var>
   

   إذا لم تكن متأكدًا من اسم جهاز Android الافتراضي، نفِّذ emulator -list-avds.

2. يمكنك الآن تثبيت تطبيقك باستخدام إحدى مهام تثبيت Gradle المذكورة في القسم حول كيفية إنشاء حزمة APK لتصحيح الأخطاء أو أداة adb.

   إذا تم إنشاء حزمة APK باستخدام حزمة تطوير برامج (SDK) لمعاينة المطوّر (إذا كان targetSdkVersion حرفًا بدلاً من رقم)، يجب تضمين الخيار -t مع الأمر install لتثبيت حزمة APK تجريبية.

   adb install <var>path/to/your_app</var>.apk
   

   يتم حفظ جميع حِزم APK التي تنشئها في project_name/module_name/build/outputs/apk/.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تشغيل التطبيقات على Android Emulator.

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

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

بعد إعداد جهازك وتوصيله باستخدام USB، يمكنك تثبيت تطبيقك باستخدام مهام تثبيت Gradle المذكورة في القسم حول كيفية إنشاء حزمة APK لتصحيح الأخطاء أو أداة adb:

adb -d install path/to/your_app.apk

يتم حفظ جميع حِزم APK التي تنشئها في project_name/module_name/build/outputs/apk/.

لمزيد من المعلومات، يُرجى الاطّلاع على تشغيل التطبيقات على جهاز.

إنشاء حزمة تطبيق

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

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

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

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

./gradlew :base:bundleDebug

إذا أردت إنشاء حزمة موقَّعة لتحميلها إلى Play Console، عليك أولاً ضبط ملف build.gradle.kts الخاص بالوحدة الأساسية باستخدام معلومات توقيع تطبيقك. لمزيد من المعلومات، انتقِل إلى القسم حول كيفية ضبط Gradle لتوقيع تطبيقك. يمكنك بعد ذلك، على سبيل المثال، إنشاء نسخة الإصدار من تطبيقك، وسينشئ Gradle تلقائيًا حزمة تطبيق ويوقّعها باستخدام معلومات التوقيع التي تقدّمها في ملف build.gradle.kts.

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

jarsigner -keystore pathToKeystore app-release.aab keyAlias

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

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

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

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

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

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

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

تنزيل أداة AAPT2

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

لتنزيل أداة 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 بمزيد من التفصيل:

تخصيص إنشاء حزم 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 باستخدام أنماط glob، على النحو التالي:

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

يُرجى العِلم أنّ أداة bundletool لا تضغط تلقائيًا المكتبات المجمّعة من رموز برمجية أصلية في تطبيقك (على نظام التشغيل Android 6.0 أو الإصدارات الأحدث) وجدول الموارد (resources.arsc). للحصول على وصف كامل لما يمكنك ضبطه في BundleConfig.json، يمكنك فحص ملف bundletool config.proto، المكتوب باستخدام بنية Proto3.

نشر تطبيقك من حِزمة تطبيق

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

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

لا تحتاج إلى "استوديو Android" لتوقيع تطبيقك. يمكنك توقيع تطبيقك من سطر الأوامر باستخدام 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"، واختَر عرض > نوافذ الأدوات > Terminal، وانتقِل إلى الدليل الذي توجد فيه حزمة APK غير الموقَّعة.

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

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

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

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

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.