The Android Developer Challenge is back! Submit your idea before December 2.

向您的项目添加 C 和 C++ 代码

您可以向 Android 项目添加 C 和 C++ 代码,只需将相应的代码添加到项目模块的 cpp 目录中即可。在您编译项目时,这些代码会编译到一个可由 Gradle 与您的 APK 打包在一起的原生库中。然后,Java 或 Kotlin 代码即可通过 Java 原生接口 (JNI) 调用原生库中的函数。要详细了解如何使用 JNI 框架,请参阅 Android JNI 提示

Android Studio 支持适用于跨平台项目的 CMake,以及速度比 CMake 更快,但仅支持 Android 的 ndk-build。目前不支持在同一模块中同时使用 CMake 和 ndk-build。

如果您想要将现有的 ndk-build 库导入到 Android Studio 项目,请了解如何将 Gradle 关联到原生库项目

本页将向您介绍如何使用必要的编译工具设置 Android Studio、如何创建新项目并让其支持 C/C++,以及如何向您的项目添加新的 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 或 Kotlin 代码中访问原生函数。要编译和运行应用,只需点击运行图标 从菜单栏运行应用 即可。

注意:如果现有项目使用的是已弃用的 ndkCompile 工具,您应该迁移到 CMake 或 ndk-build。要了解详情,请转到介绍如何从 ndkCompile 迁移的部分。

实验性 Gradle 版本的用户注意事项:如果您符合以下任意一种情况,请考虑迁移到插件版本 2.2.0 或更高版本,并使用 CMake 或 ndk-build 编译原生库:您的原生项目已经使用 CMake 或者 ndk-build;您想要使用稳定版本的 Gradle 编译系统;或者您希望支持插件工具,例如 CCache。否则,您可以继续使用实验性版本的 Gradle 和 Android 插件

下载 NDK 和编译工具

要为您的应用编译和调试原生代码,您需要以下组件:

  • Android 原生开发套件 (NDK):一个工具集,让您能够在 Android 应用中使用 C 和 C++ 代码;它提供了各种平台库,让您能够管理原生 Activity 并访问实际设备组件,例如传感器和轻触输入。
  • CMake:一款外部编译工具,可与 Gradle 搭配使用来编译原生库。如果您只计划使用 ndk-build,则不需要此组件。
  • LLDB:Android Studio 用于调试原生代码的调试程序。

您可以使用 SDK 管理器安装这些组件:

  1. 在打开的项目中,从菜单栏依次选择 Tools > SDK Manager
  2. 点击 SDK Tools 标签。
  3. 选中 LLDBCMakeNDK 旁的复选框,如图 1 所示。

    图 1. 从 SDK 管理器中安装 LLDB、CMake 和 NDK。

  4. 点击 Apply,然后在弹出式对话框中点击 OK
  5. 安装完成后,点击 Finish,然后点击 OK

使用 CMake 3.6.0 或 3.10.2

SDK 管理器包含 CMake 的 3.6.0 派生版本和版本 3.10.2。未在 build.gradle 中设置特定 CMake 版本的项目均使用 CMake 3.6.0 进行编译。要使用后来包含的版本,请在模块的 build.gradle 文件中指定 CMake 版本 3.10.2:

    android {
        ...
        externalNativeBuild {
            cmake {
                ...
                version "3.10.2"
            }
        }
    }
    
您可以指定此 CMake 版本作为最低版本,只需在 build.gradle 条目的末尾添加一个“+”即可,例如 3.10+3+。不过,这并非最佳做法。

使用自定义 CMake 版本

如果您想使用 SDK 管理器中未包含的 CMake 版本 3.7 或更高版本,请按以下步骤操作:

  1. 从官方 CMake 网站下载并安装 CMake 3.7 或更高版本
  2. 指定您想要让 Gradle 在模块的 build.gradle 文件中使用的 CMake 版本:
        android {
            ...
            externalNativeBuild {
                cmake {
                    ...
                    version "cmake-version"
                }
            }
        }
        
  3. 将 CMake 的安装路径添加到 PATH 环境变量,或将其添加到项目的 local.properties 文件中,具体步骤如下所示。如果 Gradle 找不到您在 build.gradle 文件中指定的 CMake 版本,您便会遇到编译错误。
        # If you set this property, Gradle no longer uses PATH to find CMake.
        cmake.dir="path-to-cmake"
        
  4. 如果您尚未在工作站上安装 Ninja 编译系统,请访问 Ninja 官方网站,然后下载并安装适用于您的操作系统的最新版本的 Ninja。此外,请务必将 Ninja 的安装路径也添加到 PATH 环境变量。

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

创建支持原生代码的新项目的步骤与创建任何其他 Android Studio 项目的步骤相似,但前者还需要执行一个额外的步骤:

  1. 在向导的 Choose your project 部分中,选择 Native C++ 项目类型。
  2. 点击 Next
  3. 填写向导下一部分中的所有其他字段。
  4. 点击 Next
  5. 在向导的 Customize C++ Support 部分中,您可以使用 C++ Standard 字段来自定义项目。使用下拉列表选择您想要使用哪种 C++ 标准化。选择 Toolchain Default 可使用默认的 CMake 设置。
  6. 点击 Finish

在 Android Studio 完成新项目的创建后,请从 IDE 左侧打开 Project 窗格,然后选择 Android 视图。如图 2 所示,Android Studio 会添加 cpp 组:

图 2. 原生源代码和外部编译脚本的 Android 视图组。

注意:此视图并未反映磁盘上的实际文件层次结构,而是将相似的文件归为一组,以便简化项目导航。

cpp 组中,您可以找到项目中的所有原生源代码文件、头文件、CMake 或 ndk-build 的编译脚本,以及项目中的预编译库。对于新项目,Android Studio 会创建一个示例 C++ 源代码文件 native-lib.cpp,并将其置于应用模块的 src/main/cpp/ 目录中。此示例代码提供了一个简单的 C++ 函数 stringFromJNI(),它可以返回字符串“Hello from C++”。要了解如何向项目添加其他源代码文件,请参阅介绍如何创建新的原生源代码文件的部分。

build.gradle 文件指示 Gradle 如何编译应用一样,CMake 和 ndk-build 需要编译脚本以确定如何编译您的原生库。对于新项目,Android Studio 会创建 CMake 编译脚本 CMakeLists.txt,并将其置于模块的根目录中。要详细了解此编译脚本的内容,请参阅配置 CMake

编译和运行示例应用

点击 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 与使用原生代码编写的项目组件不兼容。

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

  1. 依次选择 Build > Build Bundles(s) / APK(s) > Build APK(s)
  2. 依次选择 Build > Analyze APK
  3. app/build/outputs/apk/ 目录中选择 APK,然后点击 OK
  4. 如图 3 所示,您可以在 lib/<ABI>/ 下的 APK 分析器窗口中看到 libnative-lib.so

    图 3. 使用 APK 分析器查找原生库。

提示:如果您想要利用其他使用了原生代码的 Android 应用进行实验,请依次点击 File > New > Import Sample,然后从 Ndk 列表中选择一个示例项目。

创建新的 C/C++ 源代码文件

要将新的 C/C++ 源代码文件添加到现有项目,请执行以下操作:

  1. 如果您的应用的主源代码文件集内还没有 cpp/ 目录,请按如下所示的方法创建一个:
    1. 从 IDE 的左侧打开 Project 窗格,然后从下拉菜单中选择 Project 视图。
    2. 转到 your-module > src,右键点击 main 目录,然后依次选择 New > Directory
    3. 输入 cpp 作为目录名称,然后点击 OK

  2. 右键点击 cpp/ 目录,然后依次选择 New > C/C++ Source File
  3. 为您的源代码文件输入一个名称,例如 native-lib
  4. Type 下拉菜单中,为您的源代码文件选择文件扩展名,例如 .cpp
    • 您可以向此下拉菜单添加其他文件类型(例如 .cxx.hxx),只需点击 Edit File Types 图标 即可。在弹出的 C/C++ 对话框中,从 Source ExtensionHeader Extension 下拉菜单中选择另一个文件扩展名,然后点击 OK
  5. 如果您还想要创建头文件,请选中 Create an associated header 复选框。
  6. 点击 OK

向项目添加新的 C/C++ 文件后,您仍需要配置 CMake 以将这些文件包含在原生库中。

其他资源

要详细了解如何在应用中支持 C/C++ 代码,请尝试参阅以下资源。

代码实验室