CMake

Android NDK 支持使用 CMake 编译应用的 C 和 C++ 代码。本页介绍了如何通过 Android Gradle 插件的 ExternalNativeBuild 或通过直接调用 CMake 将 CMake 与 NDK 搭配使用。

注意：如果您使用的是 Android Studio，请参阅向您的项目添加 C 和 C++ 代码，了解以下方面的基础知识：向项目中添加原生源代码，创建 CMake 构建脚本，将 CMake 项目添加为 Gradle 依赖项，以及使用比 SDK 中的 CMake 版本更高的 CMake。

CMake 工具链文件

NDK 通过工具链文件支持 CMake。工具链文件是用于自定义交叉编译工具链行为的 CMake 文件。用于 NDK 的工具链文件位于 NDK 中以下位置：<NDK>/build/cmake/android.toolchain.cmake。

注意：如果安装了 Android SDK，则 NDK 安装在 SDK 目录的以下位置：ndk/version/ 或 ndk-bundle/。

在调用 cmake 时，命令行会提供 ABI 和 minSdkVersion 等构建参数。如需查看支持的参数的列表，请参阅工具链参数部分。

注意 ：CMake 拥有自己的内置 NDK 支持，其行为与 NDK 的 CMake 工具链文件有所不同。Android 不支持或测试内置工作流。我们建议您使用我们的工具链文件。externalNativeBuild（属于 Android Gradle 插件的 NDK 工作流）用户将自动获得此界面。如果您不使用 externalNativeBuild，请参阅下文，了解如何直接使用我们的工具链文件。

“新”工具链文件

警告 ：我们建议不要使用 -DANDROID_USE_LEGACY_TOOLCHAIN_FILE=OFF。旧版工具链是默认工具链，尽管名称如此，但我们仍建议使用。

早期的 NDK 尝试了一种工具链文件的新实现，该实现可减少使用 NDK 的工具链文件与使用内置 CMake 支持之间的行为差异。这最终需要进行大量工作（尚未完成），但实际上并未改善行为，因此我们不再继续进行这项工作。

与“旧版”工具链文件相比，“新版”工具链文件存在行为回归问题。默认行为是推荐的工作流程。如果您使用的是 -DANDROID_USE_LEGACY_TOOLCHAIN_FILE=OFF，我们建议您从 build 中移除该标志。新工具链文件从未与旧版工具链文件达到同等水平，因此可能会出现行为回归。

虽然我们建议不要使用新的工具链文件，但目前尚无将其从 NDK 中移除的计划。这样做会破坏依赖于新工具链文件与旧版工具链文件之间行为差异的 build，并且不幸地是重命名选项，从而明确指出实际上推荐使用“legacy”也会破坏该选项的用户。如果您满意地使用新工具链文件，则无需迁移，但请注意，针对新工具链文件行为提交的任何 bug 可能都不会得到修复，您需要改为迁移。

用法

Gradle命令行

使用 externalNativeBuild 时，系统会自动使用 CMake 工具链文件。详情请参阅 Android Studio 的向您的项目添加 C 和 C++ 代码指南。

在 Gradle 之外使用 CMake 进行构建时，工具链文件本身及其参数必须传递给 CMake。例如：

$ cmake \
    -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \
    -DANDROID_ABI=$ABI \
    -DANDROID_PLATFORM=android-$MINSDKVERSION \
    $OTHER_ARGS

工具链参数

以下参数可以传递给 CMake 工具链文件。如果使用 Gradle 进行构建，请按照 ExternalNativeBuild 文档中所述向 android.defaultConfig.externalNativeBuild.cmake.arguments 添加参数。如果通过命令行进行构建，请使用 -D 将参数传递给 CMake。例如，要强制 armeabi-v7a 不使用 Neon 支持进行构建，请传递 -DANDROID_ARM_NEON=FALSE。

注意：任何必需参数均由 Gradle 自动传递，只有在通过命令行构建时才需明确传递。

ANDROID_ABI

注意：这是必需参数。

目标 ABI。如需了解支持的 ABI，请参阅 Android ABI。

Gradle命令行

Gradle 会自动提供此参数。请勿在您的 build.gradle 文件中明确设置此参数。如需控制 ABI Gradle 的目标，请按照 Android ABI 中所述使用 abiFilters。

对于每个 build，CMake 都只针对一个目标进行构建。如需以多个 Android ABI 为目标，您必须为每个 ABI 构建一次。建议对每个 ABI 使用不同的构建目录，以避免 build 之间发生冲突。

值	备注
armeabi-v7a
armeabi-v7a with NEON	与 armeabi-v7a 相同。
arm64-v8a
x86
x86_64

ANDROID_ARM_MODE

指定是为 armeabi-v7a 生成 arm 还是 thumb 指令。对其他 ABI 没有影响。如需了解详情，请参阅 Android ABI 文档。

值	备注
arm
thumb	默认行为。

ANDROID_NATIVE_API_LEVEL

ANDROID_PLATFORM 的别名。

ANDROID_PLATFORM

指定应用或库所支持的最低 API 级别。此值对应于应用的 minSdkVersion。

Gradle命令行

使用 Android Gradle 插件时，此值会自动设置为与应用的 minSdkVersion 相匹配，因此不应手动设置。

当直接调用 CMake 时，此值默认为所使用的 NDK 支持的最低 API 级别。例如，对于 NDK r20，此值默认为 API 级别 16。

警告：NDK 库无法在 API 级别低于构建代码所用的 ANDROID_PLATFORM 值的设备上运行。

此参数支持多种格式：

• android-$API_LEVEL
• $API_LEVEL
• android-$API_LETTER

$API_LETTER 格式允许您指定 android-N，而无需确定与该版本关联的编号。请注意，对于某些版本，API 只是编号增加了，但字母次序没有增加。您可以通过附加 -MR1 后缀来指定这些 API。例如，API 级别 25 为 android-N-MR1。

ANDROID_STL

指定要为此应用使用的 STL。如需了解详情，请参阅 C++ 库支持。默认情况下将使用 c++_static。

注意：默认行为只适用于部分应用。选择 STL 之前，请务必先阅读 C++ 库支持指南，尤其是有关静态运行时的部分。

值	备注
c++_shared	libc++ 的共享库变体。
c++_static	libc++ 的静态库变体。
无	不支持 C++ 标准库。
system	系统 STL

管理编译器标志

如果您需要将特定标记传递给 build 的编译器或链接器，请参阅 CMake 文档中有关 set_target_compile_options 和相关的选项系列。该页面底部的“另请参阅”部分提供了一些有用的线索。

注意 ：在 CMake 中使用全局编译器标志变量（例如 CMAKE_CXX_FLAGS）时，您需要注意 CMake 针对每个构建类型 (CMAKE_BUILD_TYPE) 都提供了这些变量的变体，并使用适当的变体。特定于 build 类型的变量形式（例如 CMAKE_CXX_FLAGS_RELEASE）通常会替换出现在通用形式的类似标志。一个常见错误是将优化标志（例如 -O3）添加到 CMAKE_CXX_FLAGS。这不会产生任何影响，因为 CMAKE_CXX_FLAGS_RELEASE 中的默认优化标志会替换 CMAKE_CXX_FLAGS 中的标志。

一般来说，最佳实践是将编译器标志作为最小的可用作用域应用。您不希望为每个模块重复应用要应用于所有目标的标志（例如 -Werror），但也应尽量避免全局应用这些标志 (CMAKE_CXX_FLAGS)，因为这可能会对项目中的第三方依赖项产生不良影响。对于此类情况，可以在目录级别 (add_compile_options) 应用标志。

对于一小部分编译器标志，您还可以在 build.gradle 文件中使用 cppFlags 或类似属性进行设置。您不应这样做。从 Gradle 传递给 CMake 的标志会有出乎意料的优先级行为，在某些情况下，会覆盖构建 Android 代码所需的实现隐式传递的标志。请始终优先直接在 CMake 中处理 CMake 行为。如果您需要控制每个 AGP buildType 的编译器标志，请参阅在 CMake 中使用 AGP build 类型。

在 CMake 中使用 AGP build 类型

如果您需要根据自定义 Gradle buildType 调整 CMake 行为，请使用该 build 类型传递 CMake build 脚本可以读取的其他 CMake 标志（而非编译器标志）。例如，如果您有由 build.gradle.kts 控制的“免费”和“付费”build 变体，并且需要将这些数据传递给 CMake：

android {
    buildTypes {
        free {
            externalNativeBuild {
                cmake {
                    arguments.add("-DPRODUCT_VARIANT_PREMIUM=OFF")
                }
            }
        }
        premium {
            externalNativeBuild {
                cmake {
                    arguments.add("-DPRODUCT_VARIANT_PREMIUM=ON")
                }
            }
        }
    }
}

然后，在 CMakeLists.txt 中：

if (DPRODUCT_VARIANT_PREMIUM)
  # Do stuff for the premium build.
else()
  # Do stuff for the free build.
endif()

变量的名称由您决定，但务必要避免使用任何带有 ANDROID_、APP_ 或 CMAKE_ 前缀的内容，以避免与现有标志发生冲突或混淆。

如需查看示例，请参阅 Sanitizers NDK 示例。

了解 CMake 构建命令

在调试 CMake 构建问题时，了解 Gradle 在为 Android 交叉编译时使用的具体构建参数会很有帮助。

Android Gradle 插件会将用于为每对 ABI 和构建类型执行 CMake 构建的构建参数保存至 build_command.txt。这些文件位于以下目录中：

<project-root>/<module-root>/.cxx/cmake/<build-type>/<ABI>/

以下代码段举例说明了如何使用 CMake 参数构建面向 armeabi-v7a 架构的 hello-jni 示例的可调试版本。

                    Executable : ${HOME}/Android/Sdk/cmake/3.10.2.4988404/bin/cmake
arguments :
-H${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/src/main/cpp
-DCMAKE_FIND_ROOT_PATH=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/.cxx/cmake/universalDebug/prefab/armeabi-v7a/prefab
-DCMAKE_BUILD_TYPE=Debug
-DCMAKE_TOOLCHAIN_FILE=${HOME}/Android/Sdk/ndk/22.1.7171670/build/cmake/android.toolchain.cmake
-DANDROID_ABI=armeabi-v7a
-DANDROID_NDK=${HOME}/Android/Sdk/ndk/22.1.7171670
-DANDROID_PLATFORM=android-23
-DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a
-DCMAKE_ANDROID_NDK=${HOME}/Android/Sdk/ndk/22.1.7171670
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
-DCMAKE_LIBRARY_OUTPUT_DIRECTORY=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/build/intermediates/cmake/universalDebug/obj/armeabi-v7a
-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/build/intermediates/cmake/universalDebug/obj/armeabi-v7a
-DCMAKE_MAKE_PROGRAM=${HOME}/Android/Sdk/cmake/3.10.2.4988404/bin/ninja
-DCMAKE_SYSTEM_NAME=Android
-DCMAKE_SYSTEM_VERSION=23
-B${HOME}/Dev/github-projects/googlesamples/ndk-samples/hello-jni/app/.cxx/cmake/universalDebug/armeabi-v7a
-GNinja
jvmArgs :


                    Build command args: []
                    Version: 1

使用预构建库

如果您需要导入的预构建库是作为 AAR 分发的，请按照 Studio 的依赖项文档进行导入和使用。如果您未使用 AGP，可以按照 https://google.github.io/prefab/example-workflow.html 中的说明操作，但迁移到 AGP 可能要容易得多。

对于未作为 AAR 分发的库，如需了解有关如何将预构建库与 CMake 搭配使用的说明，请参阅 CMake 手册中关于 IMPORTED 目标的 add_library 文档。

构建第三方代码

将第三方代码作为 CMake 项目的一部分进行构建有多种方式，至于哪个方法最适合，则取决于您的具体情况。通常，最好的选择是别这样做。相反，请为相应的库构建 AAR，并在您的应用中使用该 AAR。倒不一定非要发布该 AAR。它可以作为 Gradle 项目的内部资源。

如果不行，请执行以下操作：

• 将第三方源代码提供（即复制）到您的代码库中，然后使用 add_subdirectory 构建相应源代码。只有在另一个库也使用 CMake 构建的情况下，这种方法才有效。
• 定义一个 ExternalProject。
• 独立于您的项目构建该库，然后按照使用预构建库中的说明将其导入为预构建库。

CMake 中的 YASM 支持

NDK 为构建 YASM 汇编代码提供 CMake 支持，以便在 x86 和 x86-64 架构上运行。YASM 是 x86 和 x86-64 架构的开源汇编程序，它基于 NASM 汇编程序。

如需使用 CMake 构建汇编代码，请在项目的 CMakeLists.txt 中进行以下更改：

1. 调用 enable_language，并将值设置为 ASM_NASM。
2. 如果要构建共享库，则调用 add_library；如果要构建可执行的二进制文件，则调用 add_executable。在参数中传入源文件列表，该列表包含用于 YASM 中的汇编程序的 .asm 文件和用于相关 C 库或函数的 .c 文件。

以下代码段展示了如何配置 CMakeLists.txt 来将 YASM 程序构建为共享库。

cmake_minimum_required(VERSION 3.6.0)

enable_language(ASM_NASM)

add_library(test-yasm SHARED jni/test-yasm.c jni/print_hello.asm)

如需查看如何将 YASM 程序构建为可执行文件的示例，请参阅 NDK git 代码库中的 yasm 测试。

报告问题

如果您在 NDK 或其 CMake 工具链文件方面遇到任何问题，请通过 GitHub 上的 android-ndk/ndk 问题跟踪器报告这些问题。对于 Gradle 或 Android Gradle 插件问题，请改为报告 Studio bug。