CMake

Android NDK 支持使用 CMake 编译应用的 C 和 C++ 代码。本页讨论如何通过 Android Gradle Plugin 的 ExternalNativeBuild 或直接调用 CMake 来将 CMake 与 NDK 配合使用。

CMake 工具链文件

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

构建参数（例如 ABI、minSdkVersion 等）在调用 cmake 时通过命令行给出。有关受支持参数的列表，请参阅工具链参数部分。

“新”工具链文件

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

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

尽管我们不建议使用新工具链文件，但目前没有计划将其从 NDK 中移除。这样做会破坏依赖于新旧工具链文件之间行为差异的构建，而且不幸的是，即使重命名选项以明确说明“旧版”实际上是推荐的，也会破坏该选项的用户。如果您满意地使用新工具链文件，则无需迁移，但请注意，针对新工具链文件行为提交的任何 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。

`ANDROID_ABI`

目标 ABI。有关支持的 ABI 的信息，请参阅Android ABI。

Gradle

Gradle 会自动提供此参数。请勿在 build.gradle 文件中明确设置此参数。要控制 Gradle 定位的 ABI，请使用 abiFilters，如Android ABI 中所述。

命令行

CMake 针对每次构建仅构建单个目标。要定位多个 Android ABI，必须为每个 ABI 构建一次。建议为每个 ABI 使用不同的构建目录，以避免构建之间发生冲突。

值	备注
`armeabi-v7a`
`支持 NEON 的 armeabi-v7a`	与 `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 Plugin 时，此值会自动设置为与应用的 minSdkVersion 匹配，不应手动设置。

命令行

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

此参数接受多种格式

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。

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

管理编译器标志

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

通常，最佳实践是在可用的最窄范围内应用编译器标志。您想要应用于所有目标（例如 -Werror）的标志重复起来很不方便，但仍然很少应该全局应用（CMAKE_CXX_FLAGS），因为这可能会对项目中的第三方依赖项产生不良影响。对于此类情况，可以在目录范围内应用标志（add_compile_options）。

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

在 CMake 中处理 AGP 构建类型

如果您需要根据自定义 Gradle buildType 调整 CMake 行为，请使用该构建类型传递一个额外的 CMake 标志（非编译器标志），您的 CMake 构建脚本可以读取该标志。例如，如果您的构建变体（“free”和“premium”）由 build.gradle.kts 控制，并且需要将这些数据传递给 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 Plugin 会将用于执行 CMake 构建的构建参数保存到 build_command.txt 文件中，每个 ABI 和构建类型对都对应一个文件。这些文件位于以下目录中

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

以下代码段展示了构建 hello-jni 示例的可调试版本的 CMake 参数示例，该版本面向 armeabi-v7a 架构。

                    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://ggdocs.cn/prefab/example-workflow.html，但迁移到 AGP 可能更容易得多。

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

构建第三方代码

有几种方法可以将第三方代码作为 CMake 项目的一部分进行构建，哪种选项效果最好取决于您的情况。最好的选择通常是完全不这样做。相反，为库构建一个 AAR，并在应用中消费它。您不一定需要发布该 AAR。它可以是您的 Gradle 项目内部的。

如果这不是一个选项

将第三方源文件供应商（即复制）到您的仓库中，并使用 add_subdirectory 进行构建。这仅在其他库也使用 CMake 构建时才有效。
定义一个 ExternalProject。
将库与项目分开构建，并按照使用预构建库将其作为预构建库导入。

CMake 中的 YASM 支持

NDK 为使用 YASM 编写的汇编代码提供了 CMake 支持，使其能够在 x86 和 x86-64 架构上运行。YASM 是一种基于 NASM 汇编器的开源汇编器，适用于 x86 和 x86-64 架构。

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

调用 enable_language，并将值设置为 ASM_NASM。
根据您是构建共享库还是可执行二进制文件，调用 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 test。

报告问题

如果您在使用 NDK 或其 CMake 工具链文件时遇到任何问题，请通过 GitHub 上的 android-ndk/ndk 问题跟踪器进行报告。对于 Gradle 或 Android Gradle Plugin 问题，请改为报告 Studio Bug。

CMake 使用收藏夹保持井井有条 根据您的偏好保存内容并进行分类。

CMake 工具链文件

“新”工具链文件

用法

Gradle

命令行

工具链参数

ANDROID_ABI

Gradle

命令行

ANDROID_ARM_MODE

ANDROID_NATIVE_API_LEVEL

ANDROID_PLATFORM

Gradle

命令行

ANDROID_STL

管理编译器标志

在 CMake 中处理 AGP 构建类型

理解 CMake 构建命令

使用预构建库

构建第三方代码

CMake 中的 YASM 支持

报告问题

CMake

`ANDROID_ABI`

`ANDROID_ARM_MODE`

`ANDROID_NATIVE_API_LEVEL`

`ANDROID_PLATFORM`

`ANDROID_STL`