It's happening now, watch the livestream.

将 Gradle 关联到您的原生库

要添加您的原生库项目作为 Gradle 编译依赖项,您需要向 Gradle 提供 CMake 或 ndk-build 脚本文件的路径。当您编译应用时,Gradle 会运行 CMake 或 ndk-build,并将共享的库打包到您的 APK 中。Gradle 还会使用编译脚本来了解要将哪些文件添加到您的 Android Studio 项目中,以便您可以从 Project 窗口访问这些文件。如果您没有原生源代码文件的编译脚本,则需要先创建 CMake 编译脚本,然后再继续。

Android 项目中的每个模块只能链接到一个 CMake 或 ndk-build 脚本文件。例如,如果您想要编译并打包来自多个 CMake 项目的输出,就需要使用一个 CMakeLists.txt 文件作为顶级 CMake 编译脚本(然后将 Gradle 链接到该脚本),并添加其他 CMake 项目作为该编译脚本的依赖项。同样,如果您使用的是 ndk-build,则可以在顶级 Android.mk 脚本文件中包含其他 Makefile

将 Gradle 链接到原生项目后,Android Studio 会更新 Project 窗格,以在 cpp 组中显示源代码文件和原生库,并在 External Build Files 组中显示外部编译脚本。

注意:更改 Gradle 配置后,请务必点击工具栏中的 Sync Project 图标 ,以便让所做的更改生效。此外,如果要在将 CMake 或 ndk-build 脚本文件链接到 Gradle 之后再对文件进行更改,您应当从菜单栏中选择 Build > Refresh Linked C++ Projects,将 Android Studio 与您的更改进行同步。

您可以使用 Android Studio UI 将 Gradle 链接到外部 CMake 或 ndk-build 项目:

  1. 从 IDE 左侧打开 Project 窗格并选择 Android 视图。
  2. 右键点击您想要链接到原生库的模块(例如 app 模块),并从菜单中选择 Link C++ Project with Gradle。您会看到一个类似于图 4 所示的对话框。
  3. 从下拉菜单中,选择 CMakendk-build
    1. 如果您选择 CMake,请使用 Project Path 旁的字段为您的外部 CMake 项目指定 CMakeLists.txt 脚本文件。
    2. 如果您选择 ndk-build,请使用 Project Path 旁的字段为您的外部 ndk-build 项目指定 Android.mk 脚本文件。如果 Application.mk 文件与您的 Android.mk 文件位于相同目录下,Android Studio 也会包含此文件。

    图 4. 使用 Android Studio 对话框链接外部 C ++ 项目。

  4. 点击 OK

手动配置 Gradle

要手动配置 Gradle 以链接到您的原生库,您需要将 externalNativeBuild 块添加到模块级 build.gradle 文件中,并使用 cmakendkBuild 块对其进行配置:

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

注意:如果要将 Gradle 链接到现有的 ndk-build 项目,请使用 ndkBuild 块(而不是 cmake 块),并提供指向 Android.mk 文件的相对路径。如果 Application.mk 文件与您的 Android.mk 文件位于相同目录下,Gradle 也会包含此文件。

指定可选配置

您可以在模块级 build.gradle 文件的 defaultConfig 块中配置另一个 externalNativeBuild 块,为 CMake 或 ndk-build 指定可选参数和标记。与 defaultConfig 块中的其他属性类似,您也可以在编译配置中为每种产品特性重写这些属性。

例如,如果您的 CMake 或 ndk-build 项目定义多个原生库和可执行文件,则可以使用 targets 属性为指定产品特性编译和打包其中的部分工件。以下示例代码展示了您可以配置的部分属性:

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

要详细了解如何配置产品特性和编译变体,请参阅配置编译变体。如需了解您可以使用 arguments 属性为 CMake 配置的变量列表,请参阅使用 CMake 变量

添加预编译的原生库

如果您希望 Gradle 将预编译的原生库打包到您的 APK 中,请修改默认的源代码文件集配置,以添加预编译 .so 文件所在的目录,如下所示。请注意,若要添加链接到 Gradle 的 CMake 编译脚本的工件,则无需执行此操作。

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

指定 ABI

默认情况下,Gradle 会针对 NDK 支持的应用二进制接口 (ABI) 将您的原生库编译到单独的 .so 文件中,并将这些文件全部打包到您的 APK 中。如果您希望 Gradle 仅编译和打包原生库的部分 ABI 配置,您可以在模块级文件 build.gradle 中使用 ndk.abiFilters 标记指定这些配置,如下所示:

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

在大多数情况下,您只需要在 ndk 块中指定 abiFilters(如上所示),因为它会指示 Gradle 编译和打包原生库的这些版本。但是,如果您想控制 Gradle 应当编译的配置,而不依赖于您希望其打包到 APK 中的配置,请在 defaultConfig.externalNativeBuild.cmake 块(或 defaultConfig.externalNativeBuild.ndkBuild 块中)配置另一个 abiFilters 标记。Gradle 会编译这些 ABI 配置,并且只会打包您在 defaultConfig.ndk 块中指定的配置。

为了进一步降低 APK 的大小,请考虑基于 ABI 配置多个 APK,而不是使用原生库的所有版本创建一个大型 APK。Gradle 会为您想要支持的每个 ABI 单独创建一个 APK,并且仅打包每个 ABI 需要的文件。如果您为每个 ABI 配置多个 APK,而不像上面的代码示例中所示的那样指定 abiFilters 标志,则 Gradle 会为您的原生库编译所有受支持的 ABI 版本,但是仅打包您在多 APK 配置中指定的版本。为避免编译不想要的原生库版本,请为 abiFilters 标记和“一个 ABI 多个 APK”配置提供相同的 ABI 列表。