تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إنشاء فيديوهات Shorts

يدعم Android NDK استخدام CMake من أجل تجميع رموز C وC++ لتطبيقك. تناقش هذه الصفحة كيفية استخدام أنشئ تنسيقًا باستخدام NDK من خلال ExternalNativeBuild المكوّن الإضافي لنظام Gradle المتوافق مع Android أو عند استدعاء CMake مباشرةً.

ملف سلسلة أدوات CMake

يتوافق NDK مع أداة CMake عبر ملف سلسلة أدوات. ملفات سلسلة الأدوات هي ملفات CMake التي تخصص سلوك سلسلة الأدوات من أجل التجميع المتبادل. سلسلة الأدوات ويقع الملف المستخدم في NDK في <NDK>/build/cmake/android.toolchain.cmake

يتم عرض معلمات إنشاء مثل ABI وminSdkVersion وغيرها في الأمر السطر عند استدعاء cmake. للحصول على قائمة بالوسيطات المتوافقة، يمكنك الاطّلاع على وسيطات سلسلة الأدوات.

الإصدار الجديد ملف سلسلة الأدوات

جرب أعضاء NDK سابقًا استخدامًا جديدًا لملف سلسلة الأدوات إلى تقليل الاختلافات السلوكية بين استخدام ملف سلسلة أدوات NDK باستخدام دعم CMake المُدمَج. وانتهى الأمر بما استلزم مبلغًا كبيرًا من العمل (والذي لم يكتمل)، ولكنه لم يحسن السلوك في الواقع، لذلك لم نعد نسعى لتحقيق هذا الهدف.

الإصدار الجديد يتضمن ملف سلسلة الأدوات تراجعًا في السلوك مقارنةً بالملفات "القديمة" ملف toolchain. السلوك التلقائي هو سير العمل المقترَح. إذا كنت باستخدام -DANDROID_USE_LEGACY_TOOLCHAIN_FILE=OFF، نقترح إزالة تلك العلامة من التصميم. لم يصل ملف سلسلة الأدوات الجديد إلى مستوى التكافؤ مع الملف القديم ملف سلسلة الأدوات، لذلك من المحتمل حدوث تراجعات في السلوك.

وعلى الرغم من أننا نوصي بعدم استخدام ملف سلسلة الأدوات الجديد، إلا أنه لا يوجد حاليًا تخطط لإزالتها من NDK. وهذا من شأنه أن يؤدي إلى إيقاف البناء الذي يعتمد على الاختلافات في السلوك بين ملفات سلسلة الأدوات الجديدة والقديمة، وللأسف، إعادة تسمية الخيار لتوضيح أن "قديمًا" هو في الواقع الموصى به من شأنه أيضًا تعطيل مستخدمي هذا الخيار. إذا كنت سعيدًا باستخدام ملف toolchain الجديد الذي لا تحتاج إلى ترحيله، ولكن عليك أن تعرف أن أي أخطاء قد تم الإبلاغ عنها ضد سلوك ملف سلسلة الأدوات الجديد، وبدلاً من ستحتاج إلى نقلها

الاستخدام

قاعدة مخروطية

يكون استخدام ملف سلسلة الأدوات CMake تلقائيًا عند استخدام externalNativeBuild يمكنك الاطّلاع على مقالة إضافة رمز C وC++ إلى حسابك في "استوديو Android" المشروع لمزيد من المعلومات.

سطر الأوامر

عند الإنشاء باستخدام CMake خارج Gradle، فإن ملف Toolchain نفسه يجب تمرير وسيطاته إلى CMake. مثلاً:

$ cmake \
    -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \
    -DANDROID_ABI=$ABI \
    -DANDROID_PLATFORM=android-$MINSDKVERSION \
    $OTHER_ARGS

وسيطات سلسلة الأدوات

يمكن تمرير الوسيطات التالية إلى ملف سلسلة أدوات CMake. في حال إنشاء باستخدام Gradle، وأضف الوسائط إلى android.defaultConfig.externalNativeBuild.cmake.arguments كما هو موضّح في القسم مستندات ExternalNativeBuild: في حالة الإنشاء من سطر الأوامر، مرر الوسيطات إلى إنشاء فيديو باستخدام "-D" على سبيل المثال، لفرض عدم استخدام armeabi-v7a في تصميم النيون الدعم، تجاوز -DANDROID_ARM_NEON=FALSE.

`ANDROID_ABI`

واجهة التطبيق الثنائية (ABI) المستهدَفة. للحصول على معلومات عن واجهات التطبيق الثنائية (ABI) المتوافقة، يُرجى الاطّلاع على واجهات التطبيق الثنائية (ABI) في Android.

قاعدة مخروطية

يوفر Gradle هذه الوسيطة تلقائيًا. عدم ضبط هذا الإعداد صراحةً الوسيطة في ملف build.gradle. للتحكّم في ما تستهدفه واجهات ABI، استخدام abiFilters كما هو موضّح في واجهات التطبيق الثنائية (ABI) في Android

سطر الأوامر

يمكنك إنشاء إصدارات لهدف واحد لكل إصدار. لاستهداف أكثر من نظام Android واحد واجهة التطبيق الثنائية (ABI)، عليك إنشاؤها مرة واحدة لكل واجهة تطبيق ثنائية (ABI). لذا يوصى باستخدام بنية مختلفة دلائل لكل واجهة تطبيق ثنائية (ABI) لتفادي حدوث تعارضات بين الإصدارات.

القيمة	ملاحظات
`armeabi-v7a`
`armeabi-v7a with NEON`	الأسعار نفسها في فندق `armeabi-v7a`.
`arm64-v8a`
`x86`
`x86_64`

`ANDROID_ARM_MODE`

تحدِّد هذه السياسة ما إذا كان سيتم إنشاء تعليمات الذراع أو الإبهام لـ armeabi-v7a. لا يتضمّن تأثير على واجهات التطبيق الثنائية (ABI) الأخرى. لمزيد من المعلومات، يُرجى الاطّلاع على واجهات التطبيق الثنائية (ABI) في Android التوثيق.

القيمة	ملاحظات
ذراع
إبهام	السلوك التلقائي:

`ANDROID_NATIVE_API_LEVEL`

الاسم المستعار لـ ANDROID_PLATFORM.

`ANDROID_PLATFORM`

تحدّد هذه السياسة الحد الأدنى لمستوى واجهة برمجة التطبيقات الذي يتيحه التطبيق أو المكتبة. هذا النمط مع minSdkVersion للتطبيق.

قاعدة مخروطية

عند استخدام المكوّن الإضافي لنظام Gradle المتوافق مع Android، يتم ضبط هذه القيمة تلقائيًا على تتطابق مع minSdkVersion للتطبيق ويجب ألا يتم ضبطها يدويًا.

سطر الأوامر

عند استدعاء CMake مباشرةً، يتم ضبط هذه القيمة تلقائيًا على أدنى مستوى لواجهة برمجة التطبيقات التي تدعمها NDK المستخدمة. على سبيل المثال، مع NDK r20، يتم تعيين هذه القيمة تلقائيًا إلى المستوى 16 من واجهة برمجة التطبيقات.

يتم قبول تنسيقات متعددة لهذه المعلمة:

android-$API_LEVEL
$API_LEVEL
android-$API_LETTER

يسمح لك تنسيق $API_LETTER بتحديد android-N بدون الحاجة إلى لتحديد الرقم المرتبط بهذا الإصدار. يُرجى العِلم أنّ بعض الإصدارات زيادة في واجهة برمجة التطبيقات بدون زيادة حرف. يمكن تحديد واجهات برمجة التطبيقات هذه من خلال إلحاق اللاحقة -MR1. على سبيل المثال، المستوى 25 من واجهة برمجة التطبيقات هو android-N-MR1.

`ANDROID_STL`

تحدِّد هذه السياسة نوع STL الذي يجب استخدامه لهذا التطبيق. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة C++ المكتبة. وسيتم استخدام c++_static تلقائيًا.

القيمة	ملاحظات
c++_shared	صيغة المكتبة المشتركة libc++
c++_static	تمثّل هذه السمة نسخة المكتبة الثابتة من libc++.
لا شيء	ليس هناك دعم مكتبة C++ القياسية.
النظامية	نظام STL

إدارة علامات برنامج التجميع

إذا كنت بحاجة إلى تمرير علامات محددة إلى المحول البرمجي أو الرابط لإنشاءك، يمكنك الرجوع إلى وثائق CMake بخصوص set_target_compile_options مجموعة من الخيارات ذات صلة. زر "راجع أيضًا" القسم الموجود في الجزء السفلي من تلك الصفحة بعض الأدلة المفيدة.

تنبيه: عند استخدام متغيرات علامة التجميع العمومي في CMake، مثل CMAKE_CXX_FLAGS، يجب أن يتبيّن لك أنّ واجهة برمجة التطبيقات CMake متوافقة مع كل نوع إصدار. (CMAKE_BUILD_TYPE) من هذه المتغيرات واستخدم المتغير المناسب. يشير هذا المصطلح إلى شكل المتغيّر الخاص بنوع الإصدار (مثل CMAKE_CXX_FLAGS_RELEASE). عادةً ما تلغي العلامات المتشابهة التي تظهر في النموذج العام. من الشائع هو إضافة علامات تحسين (مثل -O3) إلى CMAKE_CXX_FLAGS. هذا النمط لن يكون لذلك أي تأثير، لأنّ علامات التحسين التلقائية في سيلغي CMAKE_CXX_FLAGS_RELEASE العلامة في CMAKE_CXX_FLAGS.

بشكل عام، أفضل الممارسات هي تطبيق علامات التجميع والنطاق المتاح. العلامات التي ترغب في تطبيقها على جميع استهدافاتك (مثل -Werror) غير ملائمة للتكرار لكل وحدة، ولكن من النادر حدوثها يتم تطبيقها على مستوى العالم (CMAKE_CXX_FLAGS)، حيث قد يكون لها تأثيرات غير مرغوب فيها وتبعيات الطرف الثالث في مشروعك. في مثل هذه الحالات، يمكن أن تكون البلاغات تم تطبيقه على نطاق الدليل (add_compile_options).

بالنسبة إلى مجموعة فرعية محدودة من علامات المحول البرمجي، يمكن أيضًا ضبطها في Build.gradle ملف باستخدام cppFlags أو سمات مشابهة. يجب عدم تنفيذ هذا الإجراء. أعلام التي تم تمريرها إلى CMake من Gradle، سيكون لها سلوكيات أسبقية مدهشة، في بعض الحالات التي تتجاهل العلامات التي تم تمريرها ضمنيًا من خلال التنفيذ والتي المطلوبة لإنشاء رمز Android. أفضّل دائمًا التعامل مع سلوك CMake مباشرةً في CMake. إذا كنت بحاجة إلى التحكم في علامات برنامج التجميع حسب AGP buildType، راجِع العمل مع أنواع إصدارات AGP في CMake.

استخدام أنواع إصدارات AGP في CMake

إذا كنت بحاجة إلى ضبط سلوك CMake على buildType مخصص، استخدم ذلك لتمرير علامة CMake إضافية (وليس علامة برنامج تجميع) يمكن قراءة النصوص البرمجية للإصدار في CMake. على سبيل المثال، إذا كانت لديك كلمة "مجانًا" و"مميّز" وتنشئ متغيرات يتم التحكم فيها من خلال إنشاء.gradle.kts وعليك اجتياز هذه البيانات إلى CMake:

android {
    buildTypes {
        free {
            externalNativeBuild {
                cmake {
                    arguments.add("-DPRODUCT_VARIANT_PREMIUM=OFF")
                }
            }
        }
        premium {
            externalNativeBuild {
                cmake {
                    arguments.add("-DPRODUCT_VARIANT_PREMIUM=ON")
                }
            }
        }
    }
}

بعد ذلك، في CMakeLists.txt:

if (DPRODUCT_VARIANT_PREMIUM)
  # Do stuff for the premium build.
else()
  # Do stuff for the free build.
endif()

اسم المتغير متروك لك، ولكن تأكد من تجنب أي شيء يحتوي على البادئة ANDROID_ أو APP_ أو CMAKE_ لتجنب الاصطدام أو الالتباس مع العلامات الحالية.

يُرجى الاطّلاع على نموذج NDK من Sanitizers كمثال.

فهم أمر إنشاء CMake

عند تصحيح أخطاء إصدار CMake، من المفيد معرفة الإصدار المحدد الوسيطات التي تستخدمها Gradle عند التجميع المتبادل لنظام Android.

يحفظ المكوّن الإضافي لنظام Gradle المتوافق مع Android وسيطات التصميم التي يستخدمها لتنفيذ إنشاء إصدارات لكل واجهة تطبيق ثنائية (ABI) ونوع إصدار الإقران مع build_command.txt. تتوفّر هذه الملفات في ما يلي: الدليل:

<project-root>/<module-root>/.cxx/cmake/<build-type>/<ABI>/

يوضح المقتطف التالي مثالاً على وسيطات CMake لإنشاء إصدار قابل لتصحيح الأخطاء من نموذج hello-jni الذي يستهدف armeabi-v7a الهندسة المعمارية.

                    Executable : ${HOME}/Android/Sdk/cmake/3.10.2.4988404/bin/cmake
arguments :
-H${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/src/main/cpp
-DCMAKE_FIND_ROOT_PATH=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/.cxx/cmake/universalDebug/prefab/armeabi-v7a/prefab
-DCMAKE_BUILD_TYPE=Debug
-DCMAKE_TOOLCHAIN_FILE=${HOME}/Android/Sdk/ndk/22.1.7171670/build/cmake/android.toolchain.cmake
-DANDROID_ABI=armeabi-v7a
-DANDROID_NDK=${HOME}/Android/Sdk/ndk/22.1.7171670
-DANDROID_PLATFORM=android-23
-DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a
-DCMAKE_ANDROID_NDK=${HOME}/Android/Sdk/ndk/22.1.7171670
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/build/intermediates/cmake/universalDebug/obj/armeabi-v7a
-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/build/intermediates/cmake/universalDebug/obj/armeabi-v7a
-DCMAKE_MAKE_PROGRAM=${HOME}/Android/Sdk/cmake/3.10.2.4988404/bin/ninja
-DCMAKE_SYSTEM_NAME=Android
-DCMAKE_SYSTEM_VERSION=23
-B${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/.cxx/cmake/universalDebug/armeabi-v7a
-GNinja
jvmArgs :


                    Build command args: []
                    Version: 1

استخدام مكتبات تم إنشاؤها مسبقًا

إذا كانت المكتبة المُعدة مسبقًا التي تحتاج إلى استيرادها يتم توزيعها كملفات AAR، اتّبِع الخطوات التالية: مستندات الاعتمادية في "استوديو YouTube" لاستيرادها واستخدامها. إذا كنت لا تستخدم AGP، يمكنك متابعة https://google.github.io/prefab/example-workflow.html، ولكن من المحتمل أكثر أسهل في الترحيل إلى AGP.

بالنسبة إلى المكتبات التي لم يتم توزيعها باعتبارها ملفات AAR، تتوفر إرشادات حول استخدام مكتبات CMake، راجع مستندات add_library المتعلقة بـ IMPORTED المستهدفة في دليل CMake.

إنشاء رمز برمجي تابع لجهة خارجية

هناك بضع طرق لإنشاء رمز برمجي تابع لجهة خارجية كجزء من عملية CMake مشروعك والخيار الأفضل سيعتمد على موقفك. الأفضل هو عدم القيام بذلك على الإطلاق. بدلاً من ذلك، يجب إنشاء AAR المكتبة والاستفادة منها في تطبيقك. لا تحتاج بالضرورة إلى نشر ميزة "الاقتراحات المطبّقة تلقائيًا" يمكن أن تكون داخلية في مشروع Gradle الخاص بك.

إذا لم يكن هذا متاحًا:

المورّد (أي نسخ) المصدر الخارجي إلى مستودعك واستخدامه add_subdirectory لإنشاء هذا الدليل. لا يعمل هذا الإجراء إلا إذا تم أيضًا تحميل المكتبة الأخرى التي تم إنشاؤها باستخدام CMake.
حدِّد مشروعًا خارجيًا.
قم بإنشاء المكتبة بشكل منفصل عن مشروعك واتبع استخدام مكتبات مُنشأة مسبقًا لاستيرادها من خلال مكتبات منشأة مسبقًا

دعم YASM في CMake

يوفر NDK دعم CMake لإنشاء رمز تجميع مكتوب بلغة YASM للعمل على x86 وx86-64 البُنى الهندسية. YASM هو برنامج تجميع مفتوح المصدر لأجهزة x86 وx86-64 والهندسة المعمارية، بناءً على مجمع NASM.

لإنشاء رمز تجميع باستخدام CMake، أجرِ التغييرات التالية في جدول مشروعك CMakeLists.txt:

اطلب enable_language مع ضبط القيمة على ASM_NASM.
اعتمادًا على ما إذا كنت تنشئ مكتبة مشتركة أو ملف تنفيذي ثنائي الأبعاد، يمكنك طلب add_library أو add_executable. ضِمن الوسيطات، ثم الانتقال إلى قائمة ملفات المصدر التي تتألف من ملفات .asm لبرنامج التجميع في YASM وملفات .c للغة C المرتبطة المكتبات أو الدوال.

يوضح المقتطف التالي كيفية ضبط CMakeLists.txt على إنشاء برنامج YASM كمكتبة مشتركة.

cmake_minimum_required(VERSION 3.6.0)

enable_language(ASM_NASM)

add_library(test-yasm SHARED jni/test-yasm.c jni/print_hello.asm)

للاطّلاع على مثال حول كيفية إنشاء برنامج YASM كملف قابل للتنفيذ، راجع yasm. اختبار في مستودع NDK git.

الإبلاغ عن المشاكل

إذا واجهت أي مشاكل في NDK أو ملف سلسلة أدوات CMake، يُرجى الإبلاغ عنها. من خلال أداة تتبُّع المشاكل android-ndk/ndk على GitHub. بالنسبة إلى Gradle أو يُرجى الإبلاغ عن خطأ في المكوِّن الإضافي لنظام Gradle المتوافق مع Android بدلاً من ذلك.