تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
قبل البدء
يفترض هذا الدليل أنك على دراية بالمفاهيم الكامنة في
البرمجة الأصلية وفي تطوير Android.
مقدّمة
يقدم هذا القسم شرحًا عالي المستوى لكيفية عمل NDK. إن Android NDK هو مجموعة من
أدوات تسمح لك بتضمين لغة C أو C++ ("رموز برمجية أصلية") في تطبيقات Android. ستساعدك القدرة على استخدام
يمكن أن تكون الرموز البرمجية الأصلية في تطبيقات Android مفيدة بشكل خاص للمطوّرين الذين يريدون تنفيذ واحدة أو أكثر من
ما يلي:
نقل تطبيقاتهم بين الأنظمة الأساسية
إعادة استخدام المكتبات الحالية أو تقديم مكتبات خاصة بها لإعادة استخدامها.
تحسين الأداء في بعض الحالات، خاصةً من الناحية الحسابية
مثل الألعاب.
آلية العمل
يتناول هذا القسم المكونات الأساسية المستخدمة في إنشاء إعلان
تطبيقات Android، وتتابع وصف عملية إنشاء
العبوة.
المكوّنات الرئيسية
يجب أن تكون على دراية بالمكونات التالية أثناء إنشاء
التطبيق:
المكتبات المشتركة الأصلية: ينشئ NDK هذه المكتبات، أو الملفات .so، من
رمز مصدر C/C++.
المكتبات الثابتة الأصلية: بإمكان NDK أيضًا إنشاء مكتبات ثابتة، أو .a
من الملفات، والتي يمكنك ربطها بمكتبات أخرى.
واجهة Java الأصلية (JNI): إنّ JNI هي الواجهة التي يتم من خلالها تشغيل ملفات Java
تتحدث مكونات C++ مع بعضها البعض. يفترِض هذا الدليل معلومات عن مبادرة JNI.
للحصول على معلومات حول الترميز، يمكنك الاطّلاع على مواصفات واجهة Java الأصلية.
واجهة التطبيق الثنائية (ABI): تحدِّد واجهة التطبيق الثنائية (ABI) بدقة كيفية
يُتوقع أن يتفاعل الرمز البرمجي للجهاز مع النظام في وقت التشغيل. مؤسسة NDK
تنشئ .so ملف بالاستناد إلى هذه التعريفات. تتوافق واجهات التطبيق الثنائية (ABI) المختلفة مع
بُنى مختلفة: يشمل NDK دعم واجهة التطبيق الثنائية (ABI) لـ ARM 32 بت، وAArch64،
وx86 وx86-64. لمزيد من المعلومات، راجع Android
واجهات التطبيق الثنائية (ABI).
البيان: إذا كنت تكتب تطبيقًا لا يتضمن مكون Java، فيجب عليك
أفصح عن الفئة NativeActivity في
. راجع استخدام
الأصلية. لمزيد من التفاصيل حول كيفية إجراء ذلك.
تدفق
في ما يلي الخطوات العامة لتطوير تطبيق محلي لنظام Android:
تصميم تطبيقك، وتحديد الأجزاء المطلوب تنفيذها في Java، وأجزاء التطبيق
تنفيذه كرمز برمجي أصلي.
أنشِئ مشروعًا لتطبيق Android كما تفعل مع أي مشروع Android آخر.
إنشاء ملف Android.mk يصف المكتبة الأصلية، بما في ذلك الاسم
والمكتبات المرتبطة وملفات المصدر المطلوب تجميعها في "JNI"
الدليل.
اختياريًا، يمكنك إنشاء ملف Application.mk لضبط الهدف.
واجهات التطبيق الثنائية (ABI) وسلسلة الأدوات ووضع الإصدار/تصحيح الأخطاء وSTL بالنسبة إلى أي من هذه الطرق
عدم التحديد، يتم استخدام القيم التلقائية التالية، على التوالي:
واجهة التطبيق الثنائية (ABI): جميع واجهات التطبيق الثنائية (ABI) التي لم يتم إيقافها نهائيًا
الوضع: إصدار
STL: النظام
ضع المصدر الأصلي ضمن دليل jni للمشروع.
يمكنك استخدام ndk-build لتجميع المكتبات الأصلية (.so و.a).
أنشِئ مكوّن Java، وأنشِئ ملف .dex القابل للتنفيذ.
تجميع كل المحتوى في ملف APK يتضمّن .so و.dex وغير ذلك
الملفات اللازمة لتشغيل تطبيقك.
الأنشطة والتطبيقات المحلية
وتوفر حزمة تطوير البرامج (SDK) لنظام التشغيل Android فئة مساعد، NativeActivity، التي تتيح لك
لكتابة نشاط أصلي تمامًا. تتولى NativeActivity معالجة الاتصال.
بين إطار عمل Android والرمز البرمجي الأصلي، وبذلك لن تكون هناك حاجة إلى
وفئاتها الفرعية أو استدعاء طرقها. ما عليك سوى الإفصاح عن طلبك.
الأصلية في ملف AndroidManifest.xml، والبدء في إنشاء
التطبيق.
لا يزال تطبيق Android الذي يستخدم NativeActivity يعمل في نشاطه الافتراضي الخاص
الجهاز، في وضع الحماية من التطبيقات الأخرى. وبالتالي، لا يزال بإمكانك الوصول إلى
واجهات برمجة التطبيقات لإطار عمل Android من خلال JNI. في بعض الحالات، مثل أدوات الاستشعار،
وأحداث الإدخال ومواد العرض، فإن NDK توفر واجهات أصلية يمكنك استخدامها
بدلاً من الاضطرار
إلى الاتصال عبر JNI. لمزيد من المعلومات حول
يمكنك الاطّلاع على واجهات برمجة التطبيقات الأصلية.
بغض النظر عما إذا كنت تطوّر نشاطًا أصليًا أم لا، ننصحك
في إنشاء المشاريع باستخدام أدوات التصميم التقليدية من Android. إجراء ذلك
في ضمان إنشاء تطبيقات Android وتغليفها بالتوافق مع
البنية.
يوفّر لك Android NDK خيارين لتنفيذ نشاطك المحلي:
العنوان Native_activity.h
الإصدار الأصلي من فئة NativeActivity. وهي تحتوي على
وواجهة معاودة الاتصال وهياكل البيانات التي تحتاج إليها لإنشاء
الأخرى. ونظرًا لأن سلسلة التعليمات الرئيسية لتطبيقك تتعامل مع عمليات الاستدعاء،
عدم حظر عمليات تنفيذ معاودة الاتصال. إذا حظروا، يمكنك
ظهور أخطاء ANR (التطبيق لا يستجيب) لأنّ سلسلة المحادثات الرئيسية
لا يستجيب حتى يعود رد الاتصال.
يحدّد ملف android_native_app_glue.h مكتبة مساعدة ثابتة تم إنشاؤها استنادًا إلى
أعلى واجهة native_activity.h. يؤدي إلى نشر سلسلة محادثات أخرى
يتعامل مع أشياء مثل عمليات الاستدعاء أو أحداث الإدخال في تكرار حدث. انتقال
بسلسلة محادثات منفصلة إلى منع أي عمليات استدعاء من حظر
السلسلة الرئيسية.
<ndk_root>/sources/android/native_app_glue/android_native_app_glue.c
المصدر أيضًا، ما يسمح لك بتعديل عملية التنفيذ.
لمزيد من المعلومات حول كيفية استخدام هذه المكتبة الثابتة، يمكنك مراجعة
نموذج التطبيق الخاص بالنشاط الأصلي ومستنداته تُعد القراءة الإضافية
متاحًا أيضًا في التعليقات في
<ndk_root>/sources/android/native_app_glue/android_native_app_glue.h
الملف.
تحدّد السمة android:value للعلامة meta-data اسم
المكتبة المشتركة التي تحتوي على نقطة الدخول إلى التطبيق (مثل
C/C++ main)، مع حذف البادئة lib واللاحقة .so من المكتبة
الاسم.
أنشئ ملفًا لنشاطك الأصلي، ونفِّذ الدالة المذكورة في
المتغير ANativeActivity_onCreate. يستدعي التطبيق هذه الوظيفة عند
بدء نشاط مدمج مع المحتوى. هذه الدالة، المشابهة لـ main في لغة C/C++، تتلقى
مؤشر يؤدي إلى بنية ANativeActivity التي تحتوي على مؤشرات للوظائف
إلى عمليات تنفيذ معاودة الاتصال المختلفة التي تحتاج إلى كتابتها. ضبط
مؤشرات دالة رد الاتصال القابلة للتطبيق في ANativeActivity->callbacks
عمليات تنفيذ عمليات معاودة الاتصال.
قم بتعيين الحقل ANativeActivity->instance إلى عنوان أي مثيل
البيانات المحددة التي تريد استخدامها.
نفِّذ أي شيء آخر تريد أن يفعله نشاطك عند البدء.
نفِّذ بقية عمليات الاستدعاء التي حددتها في
ANativeActivity->callbacks لمزيد من المعلومات عن أوقات معاودة الاتصال
راجع إدارة دورة حياة النشاط.
قم بتطوير بقية التطبيق.
أنشِئ Android.mk file في الدليل jni/ الخاص بمشروعك من أجل
وصف الوحدة الأصلية لنظام التصميم. لمزيد من المعلومات، يُرجى مراجعة
Android.mk
بعد أن يصبح لديك ملف Android.mk، اجمع الرمز الأصلي باستخدام
الأمر ndk-build.
cd<path>/<to>/<project>
$NDK/ndk-build
إنشاء مشروع Android وتثبيته كالمعتاد إذا كان الرمز الأصلي بلغة
دليل jni/، سيجمع النص البرمجي للإصدار .so تلقائيًا
الملفات التي تم إنشاؤها منه في حزمة APK.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Concepts\n\nBefore you begin\n----------------\n\nThis guide assumes that you are already familiar with concepts inherent in\nnative programming and in [Android development](/develop).\n\nIntroduction\n------------\n\nThis section provides a high-level explanation of how the NDK works. The Android NDK is a set of\ntools allowing you to embed C or C++ (\"native code\") into your Android apps. The ability to use\nnative code in Android apps can be particularly useful to developers who wish to do one or more of\nthe following:\n\n- Port their apps between platforms.\n- Reuse existing libraries, or provide their own libraries for reuse.\n- Increase performance in certain cases, particularly computationally intensive ones like games.\n\nHow it works\n------------\n\nThis section introduces the main components used in building a native\napplication for Android, and goes on to describe the process of building and\npackaging.\n\n### Main components\n\nYou should have an understanding of the following components as you build your\napp:\n\n- Native shared libraries: The NDK builds these libraries, or `.so` files, from\n your C/C++ source code.\n\n- Native static libraries: The NDK can also build static libraries, or `.a`\n files, which you can link into other libraries.\n\n- Java Native Interface (JNI): The JNI is the interface via which the Java and\n C++ components talk to one another. This guide assumes knowledge of the JNI;\n for information about it, consult the [Java Native Interface Specification](http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html).\n\n- Application Binary Interface (ABI): The ABI defines exactly how your app's\n machine code is expected to interact with the system at runtime. The NDK\n builds `.so` files against these definitions. Different ABIs correspond to\n different architectures: The NDK includes ABI support for 32-bit ARM, AArch64,\n x86, and x86-64. For more information, see [Android\n ABIs](/ndk/guides/abis).\n\n- Manifest: If you are writing an app with no Java component to it, you must\n declare the [NativeActivity](/reference/android/app/NativeActivity) class in the\n [manifest](/guide/topics/manifest/manifest-intro). See [Use the\n native_activity.h interface](#na) for more detail on how to do this.\n\n### Flow\n\nThe general flow for developing a native app for Android is as follows:\n\n1. Design your app, deciding which parts to implement in Java, and which parts\n to implement as native code.\n\n | **Note:** While it is possible to completely avoid Java, you are likely to find the Android Java framework useful for tasks including controlling the display and UI.\n2. Create an Android app Project as you would for any other Android project.\n\n3. If you are writing a native-only app, declare the [NativeActivity](/reference/android/app/NativeActivity) class in\n `AndroidManifest.xml`. For more information, see the [Native activities and\n applications](#naa).\n\n4. Create an `Android.mk` file describing the native library, including name,\n flags, linked libraries, and source files to be compiled in the \"JNI\"\n directory.\n\n5. Optionally, you can create an `Application.mk` file configuring the target\n ABIs, toolchain, release/debug mode, and STL. For any of these that you do\n not specify, the following default values are used, respectively:\n\n - ABI: all non-deprecated ABIs\n - Mode: Release\n - STL: system\n6. Place your native source under the project's `jni` directory.\n\n7. Use ndk-build to compile the native (`.so`, `.a`) libraries.\n\n8. Build the Java component, producing the executable `.dex` file.\n\n9. Package everything into an APK file, containing `.so`, `.dex`, and other\n files needed for your app to run.\n\nNative activities and applications\n----------------------------------\n\nThe Android SDK provides a helper class, [NativeActivity](/reference/android/app/NativeActivity), that allows you to\nwrite a completely native activity. [NativeActivity](/reference/android/app/NativeActivity) handles the communication\nbetween the Android framework and your native code, so you do not have to\nsubclass it or call its methods. All you need to do is declare your application\nto be native in your `AndroidManifest.xml` file, and begin creating your native\napplication.\n\nAn Android application using [NativeActivity](/reference/android/app/NativeActivity) still runs in its own virtual\nmachine, sandboxed from other applications. You can therefore still access\nAndroid framework APIs through the JNI. In certain cases, such as for sensors,\ninput events, and assets, the NDK provides native interfaces that you can use\ninstead of having to call across the JNI. For more information about such\nsupport, see [Native APIs](/ndk/guides/stable_apis).\n\nRegardless of whether or not you are developing a native activity, we recommend\nthat you create your projects with the traditional Android build tools. Doing so\nhelps ensure building and packaging of Android applications with the correct\nstructure.\n\nThe Android NDK provides you with two choices to implement your native activity:\n\n- The [native_activity.h](/ndk/reference/native__activity_8h) header defines the native version of the [NativeActivity](/reference/android/app/NativeActivity) class. It contains the callback interface and data structures that you need to create your native activity. Because the main thread of your application handles the callbacks, your callback implementations must not be blocking. If they block, you might receive ANR (Application Not Responding) errors because your main thread is unresponsive until the callback returns.\n- The `android_native_app_glue.h` file defines a static helper library built on top of the [native_activity.h](/ndk/reference/native__activity_8h) interface. It spawns another thread, which handles things such as callbacks or input events in an event loop. Moving these events to a separate thread prevents any callbacks from blocking your main thread.\n\nThe `\u003cndk_root\u003e/sources/android/native_app_glue/android_native_app_glue.c`\nsource is also available, allowing you to modify the implementation.\n\nFor more information on how to use this static library, examine the\nnative-activity sample application and its documentation. Further reading is\nalso available in the comments in the\n`\u003cndk_root\u003e/sources/android/native_app_glue/android_native_app_glue.h`\nfile.\n\n### Use the native_activity.h interface\n\nTo implement a native activity with the [native_activity.h](/ndk/reference/native__activity_8h) interface:\n\n1. Create a `jni/` directory in your project's root directory. This directory\n stores all of your native code.\n\n2. Declare your native activity in the `AndroidManifest.xml` file.\n\n Because your application has no Java code, set `android:hasCode` to `false`. \n\n \u003capplication android:label=\"@string/app_name\" android:hasCode=\"false\"\u003e\n\n You must set the `android:name` attribute of the activity tag to\n [NativeActivity](/reference/android/app/NativeActivity). \n\n \u003cactivity android:name=\"android.app.NativeActivity\"\n android:label=\"@string/app_name\"\u003e\n\n | **Note:** You can subclass [NativeActivity](/reference/android/app/NativeActivity). If you do, use the name of the subclass instead of [NativeActivity](/reference/android/app/NativeActivity).\n\n The `android:value` attribute of the `meta-data` tag specifies the name of\n the shared library containing the entry point to the application (such as\n C/C++ `main`), omitting the `lib` prefix and `.so` suffix from the library\n name. \n\n \u003cmanifest\u003e\n \u003capplication\u003e\n \u003cactivity\u003e\n \u003cmeta-data android:name=\"android.app.lib_name\"\n android:value=\"native-activity\" /\u003e\n \u003cintent-filter\u003e\n \u003caction android:name=\"android.intent.action.MAIN\" /\u003e\n \u003ccategory android:name=\"android.intent.category.LAUNCHER\" /\u003e\n \u003c/intent-filter\u003e\n \u003c/activity\u003e\n \u003c/application\u003e\n \u003c/manifest\u003e\n\n3. Create a file for your native activity, and implement the function named in\n the [ANativeActivity_onCreate](/ndk/reference/group___native_activity#ga02791d0d490839055169f39fdc905c5e) variable. The app calls this function when the\n native activity starts. This function, analogous to `main` in C/C++, receives\n a pointer to an [ANativeActivity](/ndk/reference/struct_a_native_activity) structure, which contains function pointers\n to the various callback implementations that you need to write. Set the\n applicable callback function pointers in `ANativeActivity-\u003ecallbacks` to\n the implementations of your callbacks.\n\n4. Set the `ANativeActivity-\u003einstance` field to the address of any instance of\n specific data that you want to use.\n\n5. Implement anything else that you want your activity to do upon starting.\n\n6. Implement the rest of the callbacks that you set in\n `ANativeActivity-\u003ecallbacks`. For more information on when the callbacks are\n called, see [Managing the Activity Lifecycle](/training/basics/activity-lifecycle).\n\n7. Develop the rest of your application.\n\n8. Create an `Android.mk file` in the `jni/` directory of your project to\n describe your native module to the build system. For more information, see\n [Android.mk](/ndk/guides/android_mk).\n\n9. Once you have an [Android.mk](/ndk/guides/android_mk) file, compile your native code using the\n `ndk-build` command.\n\n cd \u003cpath\u003e/\u003cto\u003e/\u003cproject\u003e\n $NDK/ndk-build\n\n10. Build and install your Android project as usual. If your native code is in\n the `jni/` directory, the build script automatically packages the `.so`\n file(s) built from it into the APK.\n\nAdditional sample code\n----------------------\n\nTo download NDK samples, see [NDK Samples](https://github.com/android/ndk-samples)."]]
