با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
قبل از شروع
این راهنما فرض می کند که شما قبلاً با مفاهیم ذاتی برنامه نویسی بومی و توسعه اندروید آشنا هستید.
مقدمه
این بخش توضیحی در سطح بالایی از نحوه عملکرد NDK ارائه می دهد. Android NDK مجموعه ای از ابزارها است که به شما امکان می دهد C یا C++ ("کد بومی") را در برنامه های اندروید خود جاسازی کنید. توانایی استفاده از کد بومی در برنامه های اندروید می تواند به ویژه برای توسعه دهندگانی که مایل به انجام یک یا چند مورد از موارد زیر هستند مفید باشد:
برنامه های آنها را بین پلتفرم ها منتقل کنید.
استفاده مجدد از کتابخانه های موجود، یا ارائه کتابخانه های خود برای استفاده مجدد.
افزایش عملکرد در موارد خاص، به ویژه موارد فشرده محاسباتی مانند بازی ها.
چگونه کار می کند
در این قسمت اجزای اصلی مورد استفاده در ساخت اپلیکیشن بومی اندروید معرفی شده و در ادامه مراحل ساخت و بسته بندی توضیح داده می شود.
اجزای اصلی
هنگام ساختن برنامه خود باید درک درستی از اجزای زیر داشته باشید:
کتابخانه های مشترک بومی: NDK این کتابخانه ها یا فایل های .so را از کد منبع C/C++ شما می سازد.
کتابخانه‌های استاتیک بومی: NDK همچنین می‌تواند کتابخانه‌های استاتیک یا فایل‌های .a بسازد که می‌توانید آنها را به کتابخانه‌های دیگر پیوند دهید.
رابط بومی جاوا (JNI): JNI رابطی است که از طریق آن اجزای Java و C++ با یکدیگر صحبت می کنند. این راهنما دانش JNI را فرض می کند. برای اطلاعات در مورد آن، به مشخصات رابط بومی جاوا مراجعه کنید.
رابط باینری برنامه (ABI): ABI دقیقاً نحوه تعامل کد ماشین برنامه شما با سیستم را در زمان اجرا تعریف می کند. NDK فایل های .so را برخلاف این تعاریف می سازد. ABI های مختلف با معماری های مختلف مطابقت دارند: NDK شامل پشتیبانی ABI برای ARM 32 بیتی، AArch64، x86 و x86-64 است. برای اطلاعات بیشتر، Android ABIs را ببینید.
Manifest: اگر در حال نوشتن برنامه ای هستید که جز جاوا در آن وجود ندارد، باید کلاس NativeActivity را در مانیفست اعلام کنید. برای جزئیات بیشتر در مورد نحوه انجام این کار، به استفاده از رابط native_activity.h مراجعه کنید.
جریان
جریان کلی برای توسعه یک برنامه بومی برای اندروید به شرح زیر است:
برنامه خود را طراحی کنید، تصمیم بگیرید که کدام بخش ها را در جاوا پیاده سازی کنید، و کدام قسمت ها را به عنوان کد اصلی پیاده سازی کنید.
مانند هر پروژه اندرویدی دیگری، یک پروژه برنامه اندروید ایجاد کنید.
اگر در حال نوشتن یک برنامه فقط بومی هستید، کلاس NativeActivity را در AndroidManifest.xml اعلام کنید. برای اطلاعات بیشتر، به فعالیت ها و برنامه های بومی مراجعه کنید.
یک فایل Android.mk ایجاد کنید که کتابخانه بومی را توصیف می کند، از جمله نام، پرچم ها، کتابخانه های پیوند شده، و فایل های منبع برای کامپایل شدن در فهرست "JNI".
به صورت اختیاری، می توانید یک فایل Application.mk ایجاد کنید که ABI های هدف، زنجیره ابزار، حالت انتشار/اشکال زدایی و STL را پیکربندی می کند. برای هر یک از این موارد که مشخص نکرده اید، به ترتیب از مقادیر پیش فرض زیر استفاده می شود:
ABI: همه ABI های منسوخ نشده
حالت: انتشار
STL: سیستم
منبع اصلی خود را در فهرست jni پروژه قرار دهید.
از ndk-build برای کامپایل کتابخانه های بومی ( .so ، .a ) استفاده کنید.
کامپوننت جاوا را بسازید و فایل اجرایی .dex را تولید کنید.
همه چیز را در یک فایل APK بسته بندی کنید، حاوی .so ، .dex و سایر فایل های مورد نیاز برای اجرای برنامه شما.
فعالیت ها و برنامه های بومی
Android SDK یک کلاس کمکی به نام NativeActivity ارائه می دهد که به شما امکان می دهد یک فعالیت کاملاً بومی بنویسید. NativeActivity ارتباط بین فریم ورک اندروید و کد بومی شما را مدیریت می کند، بنابراین مجبور نیستید آن را زیر کلاس بندی کنید یا متدهای آن را فراخوانی کنید. تنها کاری که باید انجام دهید این است که در فایل AndroidManifest.xml برنامه خود را بومی اعلام کنید و شروع به ایجاد برنامه بومی خود کنید.
یک برنامه اندرویدی با استفاده از NativeActivity هنوز در ماشین مجازی خودش اجرا می‌شود که از سایر برنامه‌ها جعبه‌بندی شده است. بنابراین همچنان می‌توانید از طریق JNI به APIهای فریمورک اندروید دسترسی داشته باشید. در موارد خاص، مانند حسگرها، رویدادهای ورودی و دارایی‌ها، NDK رابط‌های بومی را ارائه می‌کند که می‌توانید به جای تماس با JNI از آنها استفاده کنید. برای اطلاعات بیشتر در مورد چنین پشتیبانی، API های بومی را ببینید.
صرف نظر از اینکه در حال توسعه یک فعالیت بومی هستید یا خیر، توصیه می کنیم پروژه های خود را با ابزارهای سنتی ساخت اندروید ایجاد کنید. انجام این کار به ساخت و بسته بندی برنامه های اندروید با ساختار صحیح کمک می کند.
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 نیز موجود است که به شما امکان می‌دهد پیاده‌سازی را تغییر دهید.
برای اطلاعات بیشتر در مورد نحوه استفاده از این کتابخانه استاتیک، نمونه برنامه کاربردی Native-activity و مستندات آن را بررسی کنید. مطالعه بیشتر نیز در نظرات در فایل <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 دریافت می‌کند که شامل نشانگرهای تابع به پیاده‌سازی‌های مختلف پاسخ به تماس است که باید بنویسید. نشانگرهای تابع callback قابل اجرا در ANativeActivity->callbacks را برای پیاده سازی تماس های خود تنظیم کنید.
فیلد ANativeActivity->instance را روی آدرس هر نمونه ای از داده های خاص که می خواهید استفاده کنید، تنظیم کنید.
هر چیز دیگری را که می‌خواهید فعالیتتان در شروع کار انجام دهد، اجرا کنید.
بقیه تماس‌هایی را که در ANativeActivity->callbacks تنظیم کرده‌اید، پیاده‌سازی کنید. برای اطلاعات بیشتر درباره زمان فراخوانی تماس‌های برگشتی، به مدیریت چرخه حیات فعالیت مراجعه کنید.
بقیه برنامه خود را توسعه دهید.
یک Android.mk file در دایرکتوری jni/ پروژه خود ایجاد کنید تا ماژول بومی خود را برای سیستم ساخت توصیف کنید. برای اطلاعات بیشتر به Android.mk مراجعه کنید.
هنگامی که یک فایل Android.mk دارید، کد بومی خود را با استفاده از دستور ndk-build کامپایل کنید.
cd<path>/<to>/<project>
$NDK/ndk-build
پروژه اندروید خود را طبق معمول بسازید و نصب کنید. اگر کد اصلی شما در دایرکتوری jni/ است، اسکریپت ساخت به طور خودکار فایل(های) .so ساخته شده از آن را در APK بسته بندی می کند.
کد نمونه اضافی
برای دانلود نمونه های NDK، به نمونه های NDK مراجعه کنید.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","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-29 بهوقت ساعت هماهنگ جهانی."],[],[],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)."]]
