注意：本文中的 原生源代码（native Code） 均指代 C\C++源代码文件
注意：预构建库 指代 已经预先构建好（已有）的 原生库；

CMake常用命令

命令	含义
cmake_minimum_required	指定需要CMAKE的最小版本
include_directories	指定 原生代码 或 so库 的头文件路径
add_library	添加 源文件或库
set_target_properties	指定 导入库的路径
find_library	添加NDK API
target_link_libraries	将预构建库关联到原生库

---

向Android项目添加 C \C++ 代码

使用 Android Studio 2.2 或更高版本，搭配 Android Plugin for Gradle 版本 2.2.0 或更高版本时，您可以使用 Gradle 将 C \ C++ 代码 编译到原生库中，然后将这些代码打包到您的应用中， Java 代码随后可以通过 Java 原生接口 ( JNI ) 调用 您原生库中的函数。

Android Studio 用于构建原生库的默认工具是 CMake。由于现有很多项目都使用 构建工具包编译其原生代码，因此 Android Studio 还支持 ndk-build。不过，如果我们在创建新的原生库，则应该使用 CMake。

这篇文章可以帮助您使用 构建工具 设置 Android Studio、创建或配置项目以支持 Android 上的原生代码，以及构建和运行应用。

下载 NDK 和构建工具

---

要想使您的应用编译和调试原生代码，您需要准备以下组件：

• Android 原生开发工具包 (NDK)：这套工具集允许您 开发 Android 使用 C 和 C++ 代码，并提供众多平台库，让您可以管理原生 Activity 和访问物理设备组件，例如传感器和触摸输入。
• CMake：一款外部构建工具，可与 Gradle 搭配使用来构建原生库。如果您只计划使用 ndk-build，则不需要此组件。
• LLDB：一种调试程序，Android Studio 使用它来调试原生代码。

您可以使用 SDK Manager 安装这些组件：

1. 在打开的项目中，从菜单栏选择 Tools > Android > SDK Manager。
2. 点击 SDK Tools 标签。

3. 选中 LLDB、CMake 和 NDK 旁的复选框，如下图所示。
   

4. 点击 Apply，然后在弹出式对话框中点击 OK。

5. 安装完成后，点击 Finish，然后点击 OK

创建支持 C/C++ 的新项目

---

创建支持 原生代码 的项目与创建任何其他 Android Studio 项目类似，不过支持原生代码的项目还需要额外几个步骤：

1. 在向导的 Configure your new project 部分，选中 Include C++ Support 复选框。
2. 点击 Next。
3. 正常填写所有其他字段并完成向导接下来的几个部分。

4. 在向导的 Customize C++ Support 部分，您可以使用下列选项自定义项目：

   • C++ Standard：使用下拉列表选择您希望使用哪种 C++ 标准。选择 Toolchain Default 会使用默认的CMake 设置。
   • Exceptions Support：如果您希望启用对 C++ 异常处理的支持，请选中此复选框。如果启用此复选框，Android Studio 会将 -fexceptions 标志添加到模块级 build.gradle 文件的 cppFlags 中，Gradle 会将其传递到 CMake。
   • Runtime Type Information Support：如果您希望支持 RTTI，请选中此复选框。如果启用此复选框，Android Studio 会将 -frtti 标志添加到模块级 build.gradle 文件的 cppFlags 中，Gradle 会将其传递到 CMake。
5. 点击 Finish。

在 Android Studio 完成新项目的创建后，请从 IDE 左侧打开 Project 窗格并选择 Android 视图。如下图中所示，Android Studio 将添加 cpp 和 External Build Files 组：

1. 在 cpp 组中，您可以找到属于项目的所有原生源文件、头文件和预构建库。对于新项目，Android Studio 会创建一个示例 C++ 源文件 native-lib.cpp，并将其置于应用模块的 src/main/cpp/ 目录中。本示例代码提供了一个简单的 C++ 函数 stringFromJNI()，此函数可以返回字符串“Hello from C++”。
2. 在 External Build Files 组中，您可以找到 CMake 或 ndk-build 的构建脚本。与 build.gradle 文件指示 Gradle 如何构建应用一样，CMake 和 ndk-build 需要一个构建脚本来了解如何构建您的原生库。对于新项目，Android Studio 会创建一个 CMake 构建脚本 CMakeLists.txt，并将其置于模块的根目录中。

构建和运行示例应用

---

在创建完项目后，点击 Run 按钮， Android Studio 将在您的 Android 设备上 安装并启动一个显示文字“Hello from C++”的应用。下面将介绍构建和运行示例应用时会发生的事：

1. Gradle 调用您的外部构建脚本 CMakeLists.txt。
2. CMake 按照构建脚本中的命令将 C++ 源文件 native-lib.cpp 编译到共享的对象库中，并命名为 libnative-lib.so，Gradle 随后会将其打包到 APK 中。
3. 运行时，应用的 MainActivity 会使用 System.loadLibrary() 加载原生库。现在，应用可以调用库的原生函数 stringFromJNI()。
4. MainActivity.onCreate() 调用 stringFromJNI()，这将返回“Hello from C++”并使用这些文字更新 TextView。

注意：Instant Run 与 使用原生代码的项目不兼容。Android Studio 会自动停用此功能。

如果您想要验证 Gradle 是否已将原生库打包到 APK 中，可以使用 APK 分析器：

1. 选择 Build > Analyze APK。
2. 从 app/build/outputs/apk/ 目录中选择 APK 并点击 OK。
3. 如图 3 中所示，您会在 APK 分析器窗口的 lib// 下看到 libnative-lib.so。
   

提示：如果您想要试验使用原生代码的其他 Android 应用，请点击 File > New > Import Sample 并从 Ndk 列表中选择示例项目。

向已有项目添加 C/C++ 代码

---

如果您希望向 已有项目 添加 原生代码，请执行以下步骤：

1. 创建新的 原生源文件 并将其添加到您的 Android Studio 项目中。

   如果您已经拥有原生代码或想要导入预构建的原生库，则可以跳过此步骤。

2. 创建 CMake 构建脚本，将您的原生源代码构建到库中。如果导入和关联预构建库或平台库，您也需要此构建脚本。

   如果您的现有原生库已经拥有 CMakeLists.txt 构建脚本或者使用 ndk-build 并包含 Android.mk 构建脚本，则可以跳过此步骤。

3. 提供一个指向您的 CMake 或 ndk-build 脚本文件的路径，将 Gradle 关联到您的原生库。Gradle 使用构建脚本将源代码导入您的 Android Studio 项目并将原生库（SO 文件）打包到 APK 中。

配置完项目后，您可以使用 JNI 框架从 Java 代码中访问您的原生函数。要构建和运行应用，只需点击 Run 从菜单栏运行应用。Gradle 会以依赖项的形式添加您的外部原生构建流程，用于编译、构建原生库并将其随 APK 一起打包。

创建新的原生源文件

---

要想在 AndroidStudio工程模块的源代码中创建一个包含 native code 源文件的 cpp/ 目录，请按以下步骤操作：

1. 从 IDE 的左侧打开 Project 窗格并从下拉菜单中选择 Project 视图 。
   
2. 导航到 您的 模块(组件) > src，右键点击 main 目录，然后选择 New > Directory。
3. 为目录输入一个名称（例如 cpp）并点击 OK。
4. 右键点击您刚刚创建的目录，然后选择 New > C/C++ Source File。
5. 为您的源文件输入一个名称，例如 native-lib。

6. 从 Type 下拉菜单中，为您的源文件选择文件扩展名，例如 .cpp。

   点击 Edit File Types ，您可以向下拉菜单中添加其他文件类型，例如 .cxx 或 .hxx。在弹出的 C/C++ 对话框中，从 Source Extension 和 Header Extension 下拉菜单中选择另一个文件扩展名，然后点击 OK。

7. 如果您还希望为这个文件创建一个 头文件（header），请选中 Create an associated header 复选框。

8. 点击 OK。

创建 CMake 构建脚本

---

如果您的原生源文件（指代C\C++文件）还没有 CMake 构建脚本，则您需要自行创建一个并包含合适的 CMake 命令。CMake 构建脚本是一个纯文本文件，您必须将其命名为 CMakeLists.txt。这部分介绍了 包含到构建脚本中的一些基本命令，用于在创建原生库时指示 CMake 应使用哪些源文件。

注：如果您的项目使用 ndk-build，则不需要创建 CMake 构建脚本。您应该提供一个指向您的 Android.mk 文件的路径，将 Gradle 关联到您的原生库。

要创建一个可以用作 CMake 构建脚本的纯文本文件，请按以下步骤操作：

1. 从 IDE 的左侧打开 Project 窗格并从下拉菜单中选择 Project 视图。

2. 右键点击 您的 模块(组件) 的 根目录 并选择 New > File。

   注：您可以在所需的任意位置创建构建脚本。不过，在配置构建脚本时，原生源文件和库的路径将与构建脚本的位置相关（这里的意思是原生源文件和库的路径是相对于构建脚本的路径的）。

3. 输入“CMakeLists.txt”作为文件名并点击 OK。

现在，您可以添加 CMake 命令，进行配置您的构建脚本。要指示 CMake 从原生源代码创建一个原生库，请将 cmake_minimum_required() 和 add_library() 命令添加到您的构建脚本中：

# 设置构建原生库所需的 CMake 的最小版本；
# 这样可以确保您的构建可以使用 CMake 的一些特定功能；

cmake_minimum_required(VERSION 3.4.1)

# 依次 指定原生库的名称, 指定库是 STATIC （静态类型）或者 SHARED （共享类型）, 指定源代码的相对路径（相对CMakeLists.txt 的路径） ；
# 您可以通过添加多个  add_library()命令  来定义多个库，CMake将为您构建它们；
# 当您构建您的APP时，Gradle 将自动打包 shared libraries 到你的APK 中；

add_library( # 指定库的名称.
             native-lib

             # 设置 native-lib 为 shared library.
             SHARED

             # 指定源代码的相对路径（相对CMakeLists.txt 的路径）.
             src/main/cpp/native-lib.cpp )

使用 add_library() 向您的 CMake 构建脚本 中添加 源文件或库时，Android Studio 还会在您同步项目后在 Project 视图下显示关联的 头文件。不过，为了确保 CMake 可以在编译时定位 您的 头文件，您需要将 include_directories() 命令添加到 CMake 构建脚本中并指定 头文件 的路径：

add_library(...)

# 指定 原生代码 或 so库 的头文件路径（相对路径）.
include_directories(src/main/cpp/include/)

CMake 使用以下规范来为 库文件 命名：

lib 库名称.so

例如，如果您在构建脚本中指定“native-lib”作为 share library (叫共享库 或 动态库都可以) 的名称，CMake 将创建一个名称为 libnative-lib.so 的文件。不过，在 Java 代码中加载此库时，请使用您在 CMake 构建脚本中指定的名称：

static {
    System.loadLibrary(“native-lib”);
}

注：如果您在 CMake 构建脚本中重命名或移除某个库，您需要先 Clean Project，Gradle 随后才会应用更改或者从 APK 中移除旧版本的库。要清理项目，请从菜单栏中选择 Build > Clean Project。

Android Studio 会自动将源文件和 头文件 添加到 Project 窗格 的 cpp 组中。使用多个 add_library() 命令， 可以为 CMake 定义 从 其他源文件 构建的更多的库。

添加 NDK 中的API

---

Android NDK 提供了一套实用的 原生 API 和库。通过将 NDK 库包含到项目的 CMakeLists.txt 脚本文件中，您可以使用这些 API 中的任意一种。

预构建的 NDK 库已经存在于 Android 平台上，因此，您无需再构建或将其打包到 APK 中。由于 NDK 库已经是 CMake 搜索路径的一部分，您甚至不需要在您的本地 NDK 安装中指定库的位置， 只需要向 CMake 提供您希望使用的库的名称，并将其关联到您自己的原生库。

将 find_library() 命令添加到您的 CMake 构建脚本中以定位 NDK 库，并将其路径 保存为一个变量。您可以使用此变量在构建脚本的其他部分引用 NDK 库。以下示例可以定位 Android 特定的日志支持库并将其路径存储在 log-lib 中：

find_library( # 定义路径变量的名称 并用这个变量存储 NDK库的位置。
              log-lib

              # 指定 CMake 需要定位的NDK库的名称
              log )

为了确保您的原生库可以调用 log 库中的函数，您需要使用 CMake 构建脚本中的 target_link_libraries() 命令关联库：

find_library(...)

# 将一个或多个 其他本地库 链接到您的本地库上。
target_link_libraries( # 指定目标库（native-lib是我们自己创建的原生库）.
                       native-lib

                       # 将日志库链接到目标库.
                       ${log-lib} )

NDK 还以源代码的形式包含一些库，您在构建和关联到您的原生库时需要使用这些代码。您可以使用 CMake 构建脚本中的 add_library() 命令，将源代码编译到原生库中。要提供本地 NDK 库的路径，您可以使用 ANDROID_NDK 路径变量，Android Studio 会自动为您定义此变量。

以下命令可以指示 CMake 构建 android_native_app_glue.c，后者会将 NativeActivity 生命周期事件和触摸输入置于静态库中并将静态库关联到 native-lib：

add_library( app-glue
             STATIC
             ${ANDROID_NDK}/sources/android/native_app_glue/android_native_app_glue.c )

# 您需要将 静态（STATIC）库 与 共享(SHARED )的本地库链接起来.
target_link_libraries( native-lib 
                        app-glue 
                        ${log-lib} )

添加其他预构建库（已有库）

添加 预构建库 和 为 CMake 指定要构建 一个原生库类似。不过，由于库已经预先构建好，您需要使用 IMPORTED 标志告知 CMake 您只希望将库导入到项目中：

add_library( # 指定目标导入库.
             imported-lib

             # 设置导入库的类型（静态或动态） 为 shared library.
             SHARED

             # 告知 CMake imported-lib 是导入的库
             IMPORTED )

然后，您需要使用 set_target_properties() 命令 指定 导入库的路径，如下所示：

某些库为特定的 CPU 架构（或应用二进制接口 (ABI)）提供了相应的软件包，并将其置于单独的目录中。此方法既有助于库充分利用特定的 CPU 架构，又能让您仅使用所需的库版本。要向 CMake 构建脚本中添加库的多个 ABI 版本，而不必为库的每个版本编写多个命令，您可以使用 ANDROID_ABI 路径变量。此变量使 NDK 支持的一组默认 ABI，或者 手动配置 Gradle 而让其使用的一组经过筛选的 ABI。例如：

add_library(...)
set_target_properties( # 指定目标导入库
                       imported-lib

                       # 指定属性（本地导入的已有库）
                       PROPERTIES IMPORTED_LOCATION

                       # 指定你要导入库的路径.
                       imported-lib/src/${ANDROID_ABI}/libimported-lib.so )

为了确保 CMake 可以在编译时定位您的 头文件，您需要使用 include_directories() 命令，并包含 头文件的路径：

include_directories( imported-lib/include/ )

注：如果您希望打包一个并不是构建时依赖项的预构建库（例如在添加属于 imported-lib 依赖项的预构建库时），则不需要执行以下说明来关联库。

要将预构建库关联到您自己的原生库，请将其添加到 CMake 构建脚本的 target_link_libraries() 命令中：

target_link_libraries(  # 指定了三个库，分别是native-lib、imported-lib和log-lib.
                        native-lib 
                        imported-lib 
                        # log-lib是包含在 NDK 中的一个日志库
                        ${log-lib} )

在您构建应用时，Gradle 会自动将 导入的库打包到 APK 中。您可以使用 APK 分析器验证 Gradle 将哪些库打包到您的 APK 中。

将 Gradle 关联到原生库

---

要将 Gradle 关联到您的原生库，您需要提供一个指向 CMake 或 ndk-build 脚本文件的路径。在您构建应用时，Gradle 会以依赖项的形式运行 CMake 或 ndk-build，并将 共享的库（shared library） 打包到您的 APK 中。Gradle 还使用构建脚本来了解要将哪些文件添加到您的 Android Studio 项目中，以便您可以从 Project 窗口访问这些文件。如果您的原生源文件没有构建脚本，则需要 先创建 CMake 构建脚本(CMakeLists.txt)，然后再继续。

将 Gradle 关联到原生项目后，Android Studio 会更新 Project 窗格以在 cpp 组中显示您的源文件和原生库，在 External Build Files 组中显示您的外部构建脚本。

注：更改 Gradle 配置时，请确保通过点击工具栏中的 Sync Project 使更改生效。此外，如果在将 CMake 或 ndk-build 脚本文件关联到 Gradle 后再对其进行更改，您应当从菜单栏中选择 Build > Refresh Linked C++ Projects，将 Android Studio 与您的更改同步。

手动配置 Gradle

---

要手动配置 Gradle 以关联到您的原生库，您需要将 externalNativeBuild {} 块添加到 模块（组件）级 build.gradle 文件中，并使用 cmake {} 或 ndkBuild {} 对其进行配置：

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

  // 封装您的外部本地构建配置.
  externalNativeBuild {

    // 封装您的 CMake 构建配置.
    cmake {

      // 为CMake 构建脚本提供一个相对路径（这个相对路径是相对于当前build.gradle的路径）.
      path "CMakeLists.txt"
    }
  }
}

注：如果您想要将 Gradle 关联到现有 ndk-build 项目，请使用 ndkBuild {} 块而不是 cmake {}，并提供 Android.mk 文件的相对路径。如果 Application.mk 文件与您的 Android.mk 文件位于相同目录下，Gradle 也要包含此文件。

指定可选配置

---

您可以在 模块(组件)级 build.gradle 文件的 defaultConfig {} 块中配置另一个 externalNativeBuild {} 块，为 CMake 或 ndk-build 指定可选参数和标志。与 defaultConfig {} 块中的其他属性类似，您也可以在构建配置中为每个产品风味（productFlavors ）重写这些属性。

例如，如果您的 CMake 或 ndk-build 项目定义多个原生库，您可以使用 targets 属性仅为给定产品风味（productFlavors ）构建和打包这些库中的一部分。以下代码示例说明了您可以配置的部分属性：

android {
  ...
  defaultConfig {
    ...
    // 这个代码块不同于您关联到Gradle的CMake或ndk构建脚本的那个块.
    externalNativeBuild {

      // For ndk-build, instead use ndkBuild {}
      cmake {

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

        // 为C编译器设置可选标志.
        cFlags "-D_EXAMPLE_C_FLAG1", "-D_EXAMPLE_C_FLAG2"

        // 设置一个标志使C++编译器的format宏常量 生效.
        cppFlags "-D__STDC_FORMAT_MACROS"
      }
    }
  }

  buildTypes {...}

  productFlavors {
    ...
    demo {
      ...
      externalNativeBuild {
        cmake {
          ...
          // 为这个product flavor 指定要构建和打包的本地库，如果您不配置这个属性，
          // Gradle 将构建和打包所有您在CMake 或 ndk-build项目中定义的共享对象库
          targets "native-lib-demo"
        }
      }
    }

    pad {
      ...
      externalNativeBuild {
        cmake {
          ...
          targets "native-lib-pad"
        }
      }
    }
  }

  // 使用下面的代码块链接Gradle到您的CMake或ndk-build脚本
  externalNativeBuild {
    cmake {...}
    // or ndkBuild {...}
  }
}

指定 ABI

---

默认情况下，Gradle 会针对 NDK 支持的 ABI 将您的原生库构建到单独的 .so 文件中，并将其全部打包到您的 APK 中。如果您希望 Gradle 仅构建和打包原生库的特定 ABI 配置，您可以在模块级 build.gradle 文件中使用 ndk.abiFilters 标志指定这些配置，如下所示：

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

    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 拆分，但没有像上面的代码示例一样指定 abiFilters 标志，Gradle 会构建原生库的所有受支持 ABI 版本，不过仅会打包您在 ABI 拆分配置中指定的版本。为了避免构建您不想要的原生库版本，请为 abiFilters 标志和 ABI 拆分配置提供相同的 ABI 列表。