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

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

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

لاستيراد مكتبة ndk-build مجمّعة من رموز برمجية أصلية حالية إلى مشروعك في "استوديو Android"، تعرَّف على كيفية ربط 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" وتعبئة المكتبة المجمّعة من رموز برمجية أصلية في التطبيق.

بعد إعداد مشروعك، يمكنك الوصول إلى الدوال الأصلية من رمز 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" نص برمجيًا للتصميم باستخدام CMake،CMakeLists.txt، ويضعه في الدليل الجذري للوحدة. لمزيد من المعلومات حول محتوى هذا النص البرمجي، يُرجى قراءة مقالة ضبط CMake.

إنشاء نموذج تطبيق وتشغيله

عند النقر على تشغيل تشغيل ثم تشغيل التطبيق من شريط القوائم، ينشئ استوديو Android تطبيقًا يعرض النص "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 أخرى تستخدم الرمز البرمجي الأصلي، انقر على ملف (File) > جديد (New) > استيراد نموذج (Import Sample) واختَر نموذج مشروع من قائمة Ndk.

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

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

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

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

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

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

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

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

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

مراجع إضافية

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

اختبارات الرموز