إضافة رمز 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 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 في نافذة "أداة تحليل حِزم APK" ضمن 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/ واختَر جديد > ملف مصدر C/C++‎.
3. أدخِل اسمًا لملف المصدر، مثل native-lib.
4. من قائمة النوع، اختَر لاحقة اسم الملف لملف المصدر، مثل .cpp.
   • انقر على تعديل أنواع الملفات لإضافة أنواع ملفات أخرى إلى القائمة، مثل .cxx أو .hxx. في مربّع الحوار امتدادات الملفات الجديدة الذي يظهر، اختَر امتداد ملف آخر من القائمتَين امتداد المصدر وامتداد العنوان، ثم انقر على حسنًا.
5. لإنشاء ملف رأس، ضَع علامة في مربّع الاختيار إنشاء ملف رأس مرتبط.
6. انقر على موافق.

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

مراجع إضافية

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

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

• إنشاء Hello-CMake باستخدام "استوديو Android" يوضّح لك هذا الدرس التطبيقي حول الترميز كيفية استخدام نموذج CMake في "استوديو Android" لبدء تطوير مشروع Android NDK.