إضافة رمز C وC++ إلى مشروعك

يمكنك إضافة رمز C وC++ إلى مشروع Android عن طريق وضع الرمز في الدليل cpp ضمن وحدة المشروع. عند إنشاء مشروعك، يتم تجميع هذا الرمز البرمجي في مكتبة مجمّعة من رموز برمجية أصلية يمكن أن تحزّمها Gradle مع تطبيقك. ويمكن لرمز Java أو Kotlin البرمجي بعد ذلك استدعاء الدوال في المكتبة المجمّعة من رموز برمجية أصلية من خلال Java Native Interface (JNI). لمزيد من المعلومات حول استخدام إطار عمل JNI، يُرجى الاطّلاع على نصائح حول JNI لنظام Android.

يتوافق "استوديو Android" مع CMake، وهو أمر مفيد للمشاريع المتوافقة مع عدّة منصات. يتوافق Android Studio أيضًا مع ndk-build، الذي قد يكون أسرع من CMake ولكنّه لا يتوافق إلا مع Android. لا تتوفّر حاليًا إمكانية استخدام كلّ من CMake وndk-build في الوحدة نفسها.

لاستيراد مكتبة ndk-build حالية إلى مشروعك في Android Studio، تعرَّف على كيفية ربط Gradle بمشروع المكتبة الأصلية.

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

إذا كنت تريد بدلاً من ذلك إضافة رمز برمجي أصلي إلى مشروع حالي، اتّبِع الخطوات التالية:

  1. أنشئ ملفات مصدر جديدة بلغة C/C++ وأضِف الملفات إلى مشروعك في "استوديو Android".
    • يمكنك تخطّي هذه الخطوة إذا كان لديك رمز برمجي أصلي أو إذا كنت تريد استيراد مكتبة أصلية مسبقة الإنشاء.
  2. إعداد CMake لإنشاء مكتبة من رمز المصدر الأصلي يجب توفّر نص برمجي للإنشاء في حال استيراد مكتبات مُنشأة مسبقًا أو مكتبات خاصة بالنظام الأساسي والربط بها.
    • إذا كان لديك مكتبة أصلية حالية تتضمّن نص برمجي للإنشاء CMakeLists.txt أو تستخدم ndk-build وتتضمّن نص برمجي للإنشاء Android.mk، يمكنك تخطّي هذه الخطوة.
  3. اضبط إعدادات Gradle من خلال توفير مسار إلى ملف CMake أو ndk-build للبرنامج النصي. يستخدم Gradle نص البرمجة لإنشاء التطبيق من أجل استيراد الرمز المصدري إلى مشروعك على Android Studio وتعبئة المكتبة المجمّعة من رموز برمجية أصلية في التطبيق.

بعد إعداد مشروعك، يمكنك الوصول إلى الدوال الأصلية من رمز Java أو Kotlin باستخدام إطار عمل JNI. لإنشاء تطبيقك وتشغيله، انقر على تشغيل تشغيل ثم تشغيل التطبيق من شريط القوائم.

ملاحظة: إذا كان مشروعك الحالي يستخدم الأداة ndkCompile المتوقّفة نهائيًا، عليك نقل البيانات لاستخدام CMake أو ndk-build.

تنزيل NDK وأدوات الإنشاء

لتجميع الرمز البرمجي الأصلي وتصحيحه في تطبيقك، يجب توفُّر المكوّنات التالية:

  • حزمة تطوير البرامج الأصلية لنظام Android (NDK): مجموعة أدوات تتيح لك استخدام رموز C وC++ مع نظام Android. يوفر NDK مكتبات النظام الأساسي التي تتيح لك إدارة الأنشطة الأصلية والوصول إلى مكونات الجهاز المادية، مثل أجهزة الاستشعار وإدخال اللمس.
  • CMake: أداة إنشاء خارجية تعمل جنبًا إلى جنب مع Gradle لإنشاء المكتبة المجمّعة من رموز برمجية أصلية. لن تحتاج إلى هذا المكوّن إذا كنت تخطّط لاستخدام ndk-build فقط.
  • ‏LLDB: هو مصحّح الأخطاء في "استوديو Android" الذي يصحّح أخطاء الرمز البرمجي الأصلي.

للحصول على معلومات حول تثبيت هذه المكوّنات، يُرجى الاطّلاع على تثبيت NDK وCMake وإعدادهما.

إنشاء مشروع جديد يتوافق مع C/C++

لإنشاء مشروع جديد يتوافق مع الرموز البرمجية الأصلية، تكون العملية مشابهة لإنشاء أي مشروع آخر في "استوديو Android"، ولكن مع خطوة إضافية:

  1. في قسم اختيار مشروعك ضمن المعالج، اختَر نوع المشروع Native C++‎.
  2. انقر على التالي.
  3. أكمِل جميع الحقول الأخرى في القسم التالي من المعالج.
  4. انقر على التالي.
  5. في قسم تخصيص دعم C++‎ ضمن المعالج، يمكنك تخصيص مشروعك باستخدام حقل معيار C++‎.
    • استخدِم القائمة المنسدلة لاختيار معيار C++ الذي تريد استخدامه. يؤدي اختيار سلسلة الأدوات التلقائية إلى استخدام إعدادات CMake التلقائية.
  6. انقر على إنهاء.

بعد أن ينتهي "استوديو Android" من إنشاء مشروعك الجديد، افتح اللوحة المشروع من الجانب الأيمن من بيئة التطوير المتكاملة (IDE) واختَر طريقة العرض Android من القائمة. كما هو موضّح في الشكل 1، يضيف "استوديو Android" المجموعة cpp:

الشكل 1. مجموعات عرض Android للمصادر الأصلية ونصوص البرامج الخارجية.

ملاحظة: لا يعكس هذا العرض التسلسل الهرمي الفعلي للملفات على القرص، بل يجمع الملفات المتشابهة لتسهيل التنقّل في مشروعك.

يمكنك العثور في مجموعة cpp على جميع ملفات المصدر الأصلية والعناوين وبرامج الإنشاء الخاصة بـ CMake أو ndk-build والمكتبات المسبقة الإنشاء التي تشكّل جزءًا من مشروعك. بالنسبة إلى المشاريع الجديدة، ينشئ "استوديو Android" ملف مصدر C++ تجريبيًا، native-lib.cpp، ويضعه في الدليل src/main/cpp/ لوحدة تطبيقك. تقدّم عينة الرمز البرمجي هذه دالة بسيطة بلغة C++‎، وهي stringFromJNI()، تعرض السلسلة "Hello from C++". تعرَّف على كيفية إضافة ملفات مصدر إضافية إلى مشروعك في القسم حول كيفية إنشاء ملفات مصدر جديدة خاصة بالتطبيق.

على غرار الطريقة التي توجّه بها ملفات build.gradle أداة Gradle بشأن كيفية إنشاء تطبيقك، تتطلّب أداتَا CMake وndk-build توفُّر نص برمجي للإنشاء لمعرفة كيفية إنشاء المكتبة الأصلية. بالنسبة إلى المشاريع الجديدة، ينشئ "استوديو Android" نص برمجي لإنشاء CMakeCMakeLists.txt ويضعه في الدليل الجذري للوحدة. لمزيد من المعلومات حول محتوى هذا النص البرمجي، يُرجى قراءة مقالة ضبط CMake.

إنشاء تطبيق العيّنة وتشغيله

عند النقر على تشغيل تشغيل ثم تشغيل التطبيق من شريط القوائم، ينشئ Android Studio تطبيقًا ويشغّله، ويعرض التطبيق النص "Hello from C++" على جهاز Android أو المحاكي. توضّح النظرة العامة التالية الأحداث التي تحدث لإنشاء وتشغيل التطبيق النموذجي:

  1. يستدعي Gradle النص البرمجي الخارجي للإنشاء، CMakeLists.txt.
  2. يتّبع CMake الأوامر الواردة في نص الإنشاء البرمجي لتجميع ملف مصدر C++، وهو native-lib.cpp، في مكتبة كائنات مشتركة وتسميتها libnative-lib.so. بعد ذلك، تحزِّم Gradle هذا الرمز في التطبيق.
  3. أثناء وقت التشغيل، يحمّل MainActivity في التطبيق المكتبة الأصلية باستخدام System.loadLibrary(). أصبح بإمكان التطبيق الآن استخدام الدالة الأصلية للمكتبة، stringFromJNI().
  4. تُجري الدالة MainActivity.onCreate() طلبًا إلى stringFromJNI()، الذي يعرض "Hello from C++" ويستخدمه لتعديل TextView.

للتحقّق من أنّ Gradle يضمِّن المكتبة المجمّعة من رموز برمجية أصلية في التطبيق، استخدِم أداة تحليل حِزم APK باتّباع الخطوات التالية:

  1. انقر على إنشاء > إنشاء حِزم التطبيق أو حِزم APK > إنشاء حِزم APK.
  2. انقر على إنشاء > تحليل حزمة APK.
  3. اختَر حزمة APK أو AAB من الدليل app/build/outputs/ وانقر على حسنًا.
  4. كما هو موضّح في الشكل 2، يمكنك الاطّلاع على libnative-lib.so في نافذة &quot;أداة تحليل حِزم APK&quot; ضمن lib/<ABI>/.

    الشكل 2. تحديد موقع مكتبة مجمّعة من رموز برمجية أصلية باستخدام "أداة تحليل حِزم APK"

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

إنشاء ملفات مصدر C/C++ جديدة

لإضافة ملفات مصدر C/C++ جديدة إلى مشروع حالي، اتّبِع الخطوات التالية:

  1. إذا لم يكن لديك دليل cpp/ في مجموعة المصادر الرئيسية لتطبيقك، أنشئ واحدًا باتّباع الخطوات التالية:
    1. افتح لوحة المشروع في الجانب الأيمن من بيئة التطوير المتكاملة (IDE) واختَر عرض المشروع من القائمة.
    2. انتقِل إلى your-module > src.
    3. انقر بزر الماوس الأيمن على الدليل الرئيسي واختَر جديد > دليل.
    4. أدخِل cpp كاسم للدليل وانقر على حسنًا.

  2. انقر بزر الماوس الأيمن على الدليل cpp/ واختَر جديد > ملف مصدر C/C++‎.

  3. أدخِل اسمًا لملف المصدر، مثل native-lib.

  4. من قائمة النوع، اختَر لاحقة الملف لملف المصدر، مثل .cpp.
    • انقر على تعديل أنواع الملفات لإضافة أنواع ملفات أخرى إلى القائمة، مثل .cxx أو .hxx. في مربّع الحوار امتدادات الملفات الجديدة الذي يظهر، اختَر امتداد ملف آخر من القائمتَين امتداد المصدر وامتداد العنوان، ثم انقر على حسنًا.

  5. لإنشاء ملف رأس، ضَع علامة في مربّع الاختيار إنشاء ملف رأس مرتبط.

  6. انقر على موافق.

بعد إضافة ملفات C/C++ جديدة إلى مشروعك، سيظل عليك ضبط CMake لتضمين الملفات في مكتبتك الأصلية.

مراجع إضافية

لمزيد من المعلومات حول إتاحة استخدام رمز C/C++ في تطبيقك، يمكنك تجربة المرجع التالي.

الدروس التطبيقية حول الترميز