Google 致力于为黑人社区推动种族平等。查看具体举措

将 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 界面将 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 列表。