Menautkan Gradle ke library native Anda

Untuk menyertakan project library native sebagai dependensi build Gradle, Anda harus menyediakan Gradle dengan jalur file skrip CMake atau ndk-build. Ketika Anda mem-build aplikasi, Gradle akan menjalankan CMake atau ndk-build dan mengemas library bersama dengan aplikasi 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 tidak memiliki skrip build untuk sumber 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. Jadi, misalnya Anda ingin mem-build dan mengemas output dari beberapa project CMake, Anda harus menggunakan satu file CMakeLists.txt sebagai skrip build CMake tingkat atas (yang kemudian ditautkan ke Gradle) dan menambahkan project CMake lainnya sebagai dependensi skrip build tersebut. Demikian pula, jika menggunakan ndk-build, Anda dapat menyertakan Makefiles lain dalam file skrip Android.mk tingkat 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 Anda menerapkannya dengan mengklik Sync Project pada toolbar. Selain itu, saat Anda melakukan perubahan pada file skrip CMake atau ndk-build setelah menautkannya ke Gradle, Anda harus menyinkronkan Android Studio dengan perubahan yang dilakukan dengan memilih Build > Refresh Linked C++ Projects dari panel menu.

Anda dapat menautkan Gradle ke project CMake atau ndk-build 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 samping Project Path untuk menentukan file skrip CMakeLists.txt bagi project CMake eksternal Anda.
    2. Jika Anda memilih ndk-build, gunakan kolom di samping Project Path untuk menentukan file skrip Android.mk bagi project ndk-build eksternal Anda. Android Studio juga menyertakan file Application.mk jika file tersebut terletak di direktori yang sama dengan file Android.mk.

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

  4. Klik OK.

Mengonfigurasi Gradle secara manual

Untuk mengonfigurasi Gradle secara manual agar ditautkan ke library native, Anda harus menambahkan blok externalNativeBuild ke file build.gradle tingkat modul dan mengonfigurasinya dengan blok cmake atau 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")
    }
  }
}

Catatan: Jika Anda ingin menautkan Gradle ke project ndk-build yang ada, gunakan blok ndkBuild, bukan blok cmake, lalu berikan jalur relatif ke file Android.mk Anda. Gradle juga menyertakan file Application.mk jika file tersebut terletak di direktori yang sama dengan file Android.mk Anda.

Menetapkan konfigurasi opsional

Anda dapat menentukan argumen dan flag opsional untuk CMake atau ndk-build dengan mengonfigurasi blok externalNativeBuild lainnya dalam blok defaultConfig dari file build.gradle tingkat modul Anda. Seperti properti lain dalam blok defaultConfig, Anda dapat mengganti properti ini untuk setiap ragam produk dalam konfigurasi build Anda.

Misalnya, jika project CMake atau ndk-build Anda menentukan beberapa file yang dapat dieksekusi dan library native, Anda dapat menggunakan properti targets untuk mem-build dan mengemas hanya satu subset artefak tersebut bagi ragam produk tertentu. Contoh kode berikut menjelaskan beberapa properti yang dapat Anda konfigurasikan:

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

Untuk mempelajari konfigurasi ragam produk dan varian build lebih lanjut, buka Mengonfigurasi Varian Build. Untuk melihat daftar variabel yang dapat Anda konfigurasi bagi CMake dengan properti arguments, lihat Menggunakan Variabel CMake.

Menyertakan library native bawaan

Jika Anda ingin Gradle mengemas library native bawaan yang tidak digunakan di build native eksternal mana pun, tambahkan library tersebut ke direktori src/main/jniLibs/ABI di modul Anda.

Versi Plugin Android Gradle sebelum 4.0 perlu menyertakan target IMPORTED CMake di direktori jniLibs agar dapat disertakan di aplikasi Anda. Jika melakukan migrasi dari plugin versi sebelumnya, Anda mungkin menemukan error seperti berikut:

* 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'

Jika Anda menggunakan Plugin Android Gradle 4.0, pindahkan semua library yang digunakan oleh target CMake IMPORTED dari direktori jniLibs agar error ini tidak terjadi.

Menetapkan ABI

Secara default, Gradle mem-build library native Anda menjadi file .so terpisah untuk Antarmuka Biner Aplikasi (ABI) yang didukung NDK dan mengemas semuanya ke dalam aplikasi Anda. Jika ingin Gradle hanya mem-build dan mengemas konfigurasi ABI tertentu dari library native, Anda dapat menentukannya dengan tanda ndk.abiFilters dalam file build.gradle tingkat modul, seperti yang ditunjukkan di bawah:

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

Umumnya, Anda hanya perlu menentukan abiFilters dalam blok ndk, seperti yang ditunjukkan di atas, karena ini akan memberi tahu Gradle untuk mem-build dan mengemas versi tersebut dari library native Anda. Namun, jika Anda ingin mengontrol apa saja yang harus di-build oleh Gradle, terlepas dari apa yang menurut Anda perlu dikemas ke dalam aplikasi, konfigurasikan tanda abiFilters lainnya dalam blok defaultConfig.externalNativeBuild.cmake (atau blok defaultConfig.externalNativeBuild.ndkBuild). Gradle akan mem-build konfigurasi ABI tersebut, tetapi hanya mengemas konfigurasi yang Anda tetapkan dalam blok defaultConfig.ndk.

Sebaiknya publikasikan menggunakan Android App Bundle untuk mengurangi lebih lanjut ukuran aplikasi Anda, karena hanya library native yang cocok dengan ABI perangkat pengguna yang akan dikirim dengan download.

Untuk publikasi aplikasi lama yang menggunakan APK (dibuat sebelum Agustus 2021), pertimbangkan mengonfigurasi beberapa APK berdasarkan ABI, bukan membuat satu APK berukuran besar dengan semua versi library native Anda, Gradle akan membuat APK terpisah untuk setiap ABI yang ingin Anda dukung dan hanya mengemas file yang diperlukan masing-masing ABI. Jika mengonfigurasi beberapa APK per ABI tanpa menentukan tanda abiFilters seperti yang ditunjukkan pada contoh kode di atas, Gradle akan mem-build semua versi ABI yang didukung dari library native Anda, tetapi hanya mengemas yang telah ditetapkan dalam konfigurasi beberapa APK. Agar tidak mem-build versi library native yang tidak diinginkan, berikan daftar ABI yang sama untuk flag abiFilters dan konfigurasi beberapa APK per-ABI.