ربط Gradle بمكتبتك الأصلية

لتضمين مشروع المكتبة الأصلية كاعتماد على إصدار Gradle، يجب أن تحتاج إلى لتزويد Gradle بالمسار إلى ملف البرنامج النصي CMake أو ndk-build. فعندما إنشاء تطبيقك، وتشغيل Gradle CMake أو ndk-build، والحزم المشتركة والمكتبات مع تطبيقك. يستخدم Gradle أيضًا النص البرمجي للإصدار لمعرفة الملفات إلى مشروع Android Studio، لتتمكّن من الوصول إليها من نافذة المشروع: إذا لم يكن لديك نص برمجي للإصدار الأصلي مصادر مختلفة، عليك إنشاء يجب إنشاء نص برمجي للإصدار في CMake قبل المتابعة.

يمكن ربط كل وحدة في مشروع Android بنموذج CMake أو ndk-build واحد فقط. ملف البرنامج النصي. لذلك، على سبيل المثال، إذا كنت تريد إنشاء وتجميع المخرجات من عدة مشاريع في CMake، عليك استخدام ملف CMakeLists.txt واحد. كنص برمجي عالي المستوى لإنشاء CMake (الذي يمكنك ربط Gradle به) إضافة مشاريع CMake الأخرى كـ فيما يتعلق بتبعيات النص البرمجي للتصميم. وبالمثل، إذا كنت تستخدم ndk-build، يمكنك يمكن أن تتضمّن ملفات Makefiles أخرى في المستوى الأعلى ملف النص البرمجي Android.mk.

بعد ربط Gradle بمشروع أصلي، يعدِّل "استوديو Android" لوحة المشروع لعرض الملفات المصدر والمكتبات الأصلية في مجموعة التكلفة لكل نقطة، والنصوص البرمجية الخارجية للإنشاء في خارجية ملفات الإصدار.

ملاحظة: عند إجراء تغييرات على تهيئة Gradle، تأكد من تطبيق التغييرات من خلال النقر على مزامنة المشروع في شريط الأدوات. بالإضافة إلى ذلك، عند إجراء تغييرات على CMake أو ndk-build البرنامج النصي بعد ربطه بأداة Gradle، يجب مزامنة يحتوي "استوديو Android" على التغييرات التي أجريتها من خلال النقر على إنشاء > إعادة تحميل ملف C++ المرتبط المشاريع من شريط القوائم.

يمكنك ربط Gradle بمشروع CMake أو ndk-build خارجي باستخدام طريقة واجهة مستخدم "استوديو Android":

  1. افتح جزء المشروع من الجانب الأيمن من بيئة التطوير المتكاملة (IDE). حدد طريقة عرض Android.
  2. انقر بزر الماوس الأيمن على الوحدة التي تريد ربطها بمكتبتك الأصلية. مثل وحدة التطبيق واختيار ربط مشروع C++ Project باستخدام Gradle من القائمة. من المفترض أن يظهر لك مربع حوار مشابه واحد كما هو موضح في الشكل 4.
  3. من القائمة المنسدلة، اختَر CMake أو . ndk-build
    1. إذا اخترت CMake، استخدِم الحقل بجانب مسار المشروع لتحديد النص البرمجي CMakeLists.txt لمشروع CMake الخارجي.
    2. إذا اخترت ndk-build، استخدِم الحقل بجانب مسار المشروع لتحديد ملف النص البرمجي Android.mk مشروعك الخارجي لنظام ndk-build. يتضمن "استوديو Android" أيضًا Application.mk إذا كان موجودًا في نفس الدليل الذي يحتوي على ملف Android.mk.

    الشكل 4. ربط مشروع C++ خارجي باستخدام مربّع حوار "استوديو Android"

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

إعداد Gradle يدويًا

لضبط Gradle يدويًا على الربط بمكتبتك الأصلية، يجب إضافة externalNativeBuild على مستوى الوحدة build.gradle وإعداده باستخدام إما cmake أو حظر المحتوى ndkBuild:

Groovy

android {
  ...
  defaultConfig {...}
  buildTypes {...}

  // Encapsulates your external native build configurations.
  externalNativeBuild {

    // Encapsulates your CMake build configurations.
    cmake {

      // Provides a relative path to your CMake build script.
      path "CMakeLists.txt"
    }
  }
}

Kotlin

android {
  ...
  defaultConfig {...}
  buildTypes {...}

  // Encapsulates your external native build configurations.
  externalNativeBuild {

    // Encapsulates your CMake build configurations.
    cmake {

      // Provides a relative path to your CMake build script.
      path = file("CMakeLists.txt")
    }
  }
}

ملاحظة: إذا كنت تريد ربط Gradle بإصدار ndk-حالي مشروعك، استخدم حظر ndkBuild بدلاً من cmake محظورة وقدِّم مسارًا نسبيًا إلى ملف Android.mk. Gradle أيضًا ملف Application.mk إذا كان في الدليل نفسه الذي يتضمّن ملف Android.mk.

تحديد الإعدادات الاختيارية

يمكنك تحديد وسيطات وعلامات اختيارية لـ CMake أو ndk-build by تهيئة آخر كتلة externalNativeBuild في جزء defaultConfig من مستوى الوحدة ملف build.gradle. على غرار المواقع الأخرى في defaultConfig حظر، يمكنك إلغاء هذه الخصائص لكل لنكهة المنتج في إعدادات تصميمك.

على سبيل المثال، إذا كان مشروعك في CMake أو ndk-build يعرّف العديد من الكلمات الرئيسية الأصلية والمكتبات والملفات التنفيذية، فيمكنك استخدام targets لإنشاء وحزم مجموعة فرعية فقط من تلك المواقع الأدوات الخاصة لنكهة منتج معينة. يصف نموذج التعليمة البرمجية التالي بعض الخصائص التي يمكنك ضبطها:

Groovy

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {

      // For ndk-build, instead use the ndkBuild block.
      cmake {

        // Passes optional arguments to CMake.
        arguments "-DANDROID_ARM_NEON=TRUE", "-DANDROID_TOOLCHAIN=clang"

        // Sets a flag to enable format macro constants for the C compiler.
        cFlags "-D__STDC_FORMAT_MACROS"

        // Sets optional flags for the C++ compiler.
        cppFlags "-fexceptions", "-frtti"
      }
    }
  }

  buildTypes {...}

  productFlavors {
    ...
    demo {
      ...
      externalNativeBuild {
        cmake {
          ...
          // Specifies which native libraries or executables to build and package
          // for this product flavor. The following tells Gradle to build only the
          // "native-lib-demo" and "my-executible-demo" outputs from the linked
          // CMake project. If you don't configure this property, Gradle builds all
          // executables and shared object libraries that you define in your CMake
          // (or ndk-build) project. However, by default, Gradle packages only the
          // shared libraries in your app.
          targets "native-lib-demo",
                  // You need to specify this executable and its sources in your CMakeLists.txt
                  // using the add_executable() command. However, building executables from your
                  // native sources is optional, and building native libraries to package into
                  // your app satisfies most project requirements.
                  "my-executible-demo"
        }
      }
    }

    paid {
      ...
      externalNativeBuild {
        cmake {
          ...
          targets "native-lib-paid",
                  "my-executible-paid"
        }
      }
    }
  }

  // Use this block to link Gradle to your CMake or ndk-build script.
  externalNativeBuild {
    cmake {...}
    // or ndkBuild {...}
  }
}

Kotlin

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {

      // For ndk-build, instead use the ndkBuild block.
      cmake {

        // Passes optional arguments to CMake.
        arguments += listOf("-DANDROID_ARM_NEON=TRUE", "-DANDROID_TOOLCHAIN=clang")

        // Sets a flag to enable format macro constants for the C compiler.
        cFlags += listOf("-D__STDC_FORMAT_MACROS")

        // Sets optional flags for the C++ compiler.
        cppFlags += listOf("-fexceptions", "-frtti")
      }
    }
  }

  buildTypes {...}

  productFlavors {
    ...
    create("demo") {
      ...
      externalNativeBuild {
        cmake {
          ...
          // Specifies which native libraries or executables to build and package
          // for this product flavor. The following tells Gradle to build only the
          // "native-lib-demo" and "my-executible-demo" outputs from the linked
          // CMake project. If you don't configure this property, Gradle builds all
          // executables and shared object libraries that you define in your CMake
          // (or ndk-build) project. However, by default, Gradle packages only the
          // shared libraries in your app.
          targets += listOf("native-lib-demo",
                  // You need to specify this executable and its sources in your CMakeLists.txt
                  // using the add_executable() command. However, building executables from your
                  // native sources is optional, and building native libraries to package into
                  // your app satisfies most project requirements.
                  "my-executible-demo")
        }
      }
    }

    create("paid") {
      ...
      externalNativeBuild {
        cmake {
          ...
          targets += listOf("native-lib-paid",
                  "my-executible-paid")
        }
      }
    }
  }

  // Use this block to link Gradle to your CMake or ndk-build script.
  externalNativeBuild {
    cmake {...}
    // or ndkBuild {...}
  }
}

لمزيد من المعلومات حول ضبط نكهات المنتجات وإنشاء خياراتها، يُرجى الانتقال إلى ضبط صيغ الإصدار: بالنسبة قائمة بالمتغيرات التي يمكنك ضبطها من أجل CMake arguments، اطّلِع على استخدام متغيّرات CMake.

تضمين المكتبات المجمّعة مسبقًا

إذا كنت تريد أن تحزم Gradle مكتبات أصلية مصممة مسبقًا ولا يتم استخدامها في إصدار خارجي مدمج مع المحتوى، يمكنك إضافته إلى src/main/jniLibs/ABI الخاص بالوحدة.

يجب توفُّر إصدارات مكوّن Android Gradle الإضافي السابقة للإصدار 4.0، بما في ذلك CMake IMPORTED أهداف في دليل jniLibs سيتم تضمينها في التطبيق. إذا كنت ترحّل من إصدار سابق من المكوّن الإضافي، يمكنك خطأً مثل ما يلي:

* What went wrong:
Execution failed for task ':app:mergeDebugNativeLibs'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.Workers$ActionFacade
   > More than one file was found with OS independent path 'lib/x86/libprebuilt.so'

إذا كنت تستخدم الإصدار 4.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android، عليك نقل أي مكتبات تستخدمها IMPORTED يمكنك حذف الأهداف من دليل jniLibs لتجنُّب هذا الخطأ.

تحديد واجهات التطبيق الثنائية (ABI)

تنشئ Gradle تلقائيًا مكتبتك الأصلية في وحدات .so منفصلة. الخاصة بـ الواجهات الثنائية للتطبيق (ABI) يدعم NDK ويجمعها جميعًا في تطبيقك. إذا أردت أداة Gradle لإنشاء وحزم إعدادات ABI معيّنة فقط من الإعدادات الأصلية المكتبات، فيمكنك تحديدها باستخدام ndk.abiFilters في ملف build.gradle على مستوى الوحدة، كما هو موضح أدناه:

Groovy

android {
  ...
  defaultConfig {
    ...
    externalNativeBuild {
      cmake {...}
      // or ndkBuild {...}
    }

    // Similar to other properties in the defaultConfig block,
    // you can configure the ndk block for each product flavor
    // in your build configuration.
    ndk {
      // Specifies the ABI configurations of your native
      // libraries Gradle should build and package with your app.
      abiFilters 'x86', 'x86_64', 'armeabi', 'armeabi-v7a',
                   'arm64-v8a'
    }
  }
  buildTypes {...}
  externalNativeBuild {...}
}

Kotlin

android {
  ...
  defaultConfig {
    ...
    externalNativeBuild {
      cmake {...}
      // or ndkBuild {...}
    }

    // Similar to other properties in the defaultConfig block,
    // you can configure the ndk block for each product flavor
    // in your build configuration.
    ndk {
      // Specifies the ABI configurations of your native
      // libraries Gradle should build and package with your app.
      abiFilters += listOf("x86", "x86_64", "armeabi", "armeabi-v7a",
                   "arm64-v8a")
    }
  }
  buildTypes {...}
  externalNativeBuild {...}
}

في معظم الحالات، عليك فقط تحديد abiFilters في كتلة ndk، كما هو موضح أعلاه، لأنها تخبر Gradle بكلا الإصدارين وحزم هذه الإصدارات من مكتباتك الأصلية. ومع ذلك، إذا كنت تريد للتحكم في ما يجب أن تنشئه أداة Gradle، بشكل مستقل عما تريده حزمة إلى تطبيقك، يُرجى إعداد علامة abiFilters أخرى في حظر defaultConfig.externalNativeBuild.cmake (أو حظر defaultConfig.externalNativeBuild.ndkBuild). قاعدة مخروطية تنشئ عمليات ضبط واجهة التطبيق الثنائية (ABI) ولكن يتم فقط إنشاء حزم تلك التي تحددها في حظر "defaultConfig.ndk"

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

بالنسبة إلى التطبيقات القديمة التي تنشر باستخدام حِزم APK (التي تم إنشاؤها قبل آب/أغسطس 2021)، يُرجى مراعاة ما يلي: تهيئة حِزم APK متعددة استنادًا إلى واجهة التطبيق الثنائية (ABI)، بدلاً من إنشاء حزمة APK واحدة كبيرة تضم جميع نُسخًا من مكتباتك الأصلية، يُنشئ Gradle حِزمة APK منفصلة لكل واجهة ABI. التي تريد دعمها وحزم الملفات التي يحتاجها كل واجهة تطبيق ثنائية (ABI) فقط. إذا كنت إعداد حِزم APK متعددة لكل واجهة تطبيق ثنائية (ABI) بدون تحديد علامة abiFilters كما هو موضّح في نموذج الرمز البرمجي أعلاه، تنشئ Gradle جميع إصدارات واجهة التطبيق الثنائية (ABI) المتوافقة من مكتباتك الأصلية، ولكنها تشمل فقط تلك التي تحددها في تهيئة حِزم APK المتعدّدة. لتجنب إنشاء إصدارات من المكتبات الأصلية التي لا تريدها، قم بتوفير نفس قائمة واجهات التطبيق الثنائية (ABI) كل من علامة abiFilters وحِزم APK المتعدّدة لكل واجهة ABI التكوين.