Menautkan Gradle ke library native Anda

Untuk menyertakan project library native sebagai dependensi build Gradle, Anda harus menyediakan lokasi ke file skrip CMRAM atau ndk-build untuk Gradle. Ketika Anda mem-build aplikasi, Gradle akan menjalankan CMake atau ndk-build dan mengemas library bersama dengan APK Anda. Gradle juga menggunakan skrip build untuk mengetahui file mana yang akan ditarik ke dalam project Android Studio Anda, sehingga Anda dapat mengaksesnya dari jendela Project. Jika Anda tidak memiliki skrip build untuk resource native, Anda perlu membuat skrip build CMake sebelum melanjutkan.

Setiap modul dalam project Android Anda hanya dapat ditautkan ke satu file skrip CMake atau ndk-build. Jika Anda ingin mem-build dan mengemas output ke beberapa project CMake, misalnya, Anda harus menggunakan satu file CMakeLists.txt sebagai skrip build CMake level atas (yang Anda tautkan ke Gradle) dan menambahkan poject CMake tambahan sebagai dependensi skrip build tersebut. Demikian pula, jika Anda menggunakan ndk-build, Anda dapat memasukkan Makefile tambahan dalam file skrip Android.mk level atas.

Setelah Anda menautkan Gradle ke project native, Android Studio akan mengupdate panel Project untuk menampilkan file sumber dan library native dalam grup cpp, serta skrip build eksternal Anda dalam grup External Build Files.

Catatan: Saat melakukan perubahan pada konfigurasi Gradle, pastikan untuk menerapkan perubahan dengan mengklik Sync Project pada toolbar. Selain itu, saat melakukan perubahan pada file skrip CMake atau ndk-build setelah menautkannya ke Gradle, Anda harus menyinkronkan Android Studio dengan perubahan tersebut. Caranya, pilih Build > Refresh Linked C++ Projects dari panel menu.

Anda dapat menautkan Gradle ke project ndk-build atau CMake eksternal menggunakan UI Android Studio:

  1. Buka panel Project dari sisi kiri IDE, lalu pilih tampilan Android.
  2. Klik kanan pada modul yang ingin Anda tautkan ke library native, misalnya modul app, lalu pilih Link C++ Project with Gradle dari menu. Anda akan melihat dialog yang mirip dengan yang ditampilkan dalam gambar 4.
  3. Dari menu drop-down, pilih CMake atau ndk-build.
    1. Jika Anda memilih CMake, gunakan kolom di sebelah Project Path untuk menetapkan file skrip CMakeLists.txt ke project CMake eksternal Anda.
    2. Jika Anda memilih ndk-build, gunakan kolom di sebelah Project Path untuk menetapkan file skrip Android.mk ke project ndk-build eksternal Anda. Android Studio juga menyertakan file Application.mk jika lokasinya sama dengan direktori file Android.mk Anda.

    Gambar 4. Menautkan project C++ eksternal dengan dialog Android Studio

  4. Klik OK.

Mengonfigurasi Gradle secara manual

Untuk mengonfigurasi Gradle secara manual agar dapat menautkannya ke library native, Anda perlu menambahkan blok externalNativeBuild ke file build.gradle level modul, lalu konfigurasikan dengan blok cmake atau ndkBuild:

    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"
        }
      }
    }
    

Catatan: Jika Anda ingin menautkan Gradle ke project ndk-build yang ada, gunakan blok ndkBuild, bukan cmake, dan sediakan lokasi relatif file Android.mk Anda. Gradle juga menyertakan file Application.mk jika berada dalam direktori file yang sama dengan file Android.mk Anda.

Menetapkan konfigurasi opsional

Anda dapat menetapkan argumen opsional dan flag untuk CMake atau ndk-build dengan mengonfigurasi blok externalNativeBuild lain dalam blok defaultConfig dari file build.gradle level modul Anda. Demikian pula dengan properti lain dalam blok defaultConfig, Anda dapat mengganti properti ini untuk setiap varian produk dalam konfigurasi build Anda.

Misalnya, jika project CMake atau ndk-build Anda mendefinisikan banyak file executable dan library native, Anda dapat menggunakan properti targets untuk mem-build dan mengemas subset artefak itu saja bagi ragam produk yang ditentukan. Kode contoh berikut menjelaskan beberapa properti yang dapat Anda konfigurasikan:

    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 APK.
              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 APK 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 {...}
      }
    }
    

Untuk mempelajari konfigurasi ragam produk dan varian versi selengkapnya, buka Konfigurasi Varian Build. Daftar variabel yang dapat Anda konfigurasikan untuk CMake dengan properti arguments bisa dilihat di Menggunakan Variabel CMake.

Menyertakan library native bawaan

Jika Anda ingin Gradle mengemas library native bawaan dengan APK Anda, modifikasi konfigurasi kumpulan sumber default untuk menyertakan direktori file .so bawaan Anda seperti yang ditunjukkan di bawah ini. Harap diingat bahwa Anda tidak perlu melakukan langkah tersebut untuk menyertakan artefak skrip build CMake yang Anda tautkan ke Gradle.

    android {
        ...
        sourceSets {
            main {
                jniLibs.srcDirs 'imported-lib/src/', 'more-imported-libs/src/'
            }
        }
    }
    

Menetapkan ABI

Secara default, Gradle mem-build library native Anda menjadi file .so terpisah untuk Application Binary Interfaces (ABI) yang didukung NDK dan mengemas semuanya ke dalam APK Anda. Jika Anda hanya ingin Gradle mem-build dan mengemas konfigurasi ABI tertentu dari library native, Anda dapat menetapkannya dengan flag ndk.abiFilters pada file build.gradle level modul Anda, seperti yang ditunjukkan di bawah ini:

    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 APK.
          abiFilters 'x86', 'x86_64', 'armeabi', 'armeabi-v7a',
                       'arm64-v8a'
        }
      }
      buildTypes {...}
      externalNativeBuild {...}
    }
    

Umumnya, Anda hanya perlu menetapkan abiFilters dalam blok ndk, seperti yang ditunjukkan di atas, karena kode tersebut akan memberi tahu Gradle mengenai kedua build dan mengemas semua versi library native Anda. Akan tetapi, jika Anda ingin mengontrol apa yang harus di-build Gradle, apa pun yang inginkan dikemas ke dalam APK Anda, konfigurasikan flag abiFilters lain dalam blok defaultConfig.externalNativeBuild.cmake (atau blok defaultConfig.externalNativeBuild.ndkBuild). Gradle akan mem-build semua konfigurasi ABI tersebut, namun hanya mengemas konfigurasi yang Anda tetapkan dalam blok defaultConfig.ndk.

Untuk mengurangi ukuran APK, pertimbangkan untuk mengonfigurasi beberapa APK berdasarkan ABI. Gradle tidak membuat satu APK besar dengan semua versi library native Anda, tetapi Gradle akan membuat APK terpisah untuk setiap ABI yang ingin Anda dukung dan hanya mengemas file yang diperlukan masing-masing ABI. Jika Anda mengonfigurasi beberapa APK per ABI tanpa menentukan flag abiFilters seperti yang ditunjukkan pada contoh kode di atas, Gradle akan mem-build semua versi ABI yang didukung dari library native Anda, namun hanya mengemas yang telah Anda tetapkan dalam beberapa konfigurasi APK. Untuk menghindari build versi library native yang tidak diinginkan, berikan daftar ABI yang sama untuk flag abiFilters dan konfigurasi beberapa APK per-ABI Anda.