2、CMake基础入门：CMake核心概念与最小示例

在TinyML项目的实际开发中，我们面对的往往不是单一源码文件的编译问题，而是涉及交叉编译工具链、第三方库（如TensorFlow Lite for Microcontrollers）、硬件抽象层、测试代码等多模块协同构建的复杂场景。CMake作为一套跨平台的构建系统生成器，能够帮助我们摆脱手写Makefile的繁琐与平台差异，用一种声明式的方式描述“构建什么”和“如何构建”。本章将聚焦CMake最核心的概念——CMakeLists.txt、目标（Target）与生成器（Generator），并通过一个最小示例串联常用命令，为后续搭建TinyML跨平台项目打下坚实基础。

上图展示了CMake构建系统的核心链路：CMakeLists.txt是构建脚本的载体，它描述了项目结构、编译选项和依赖关系；目标（Target）是CMake对可执行文件、库等构建产物的抽象，所有依赖关系都围绕目标展开；生成器（Generator）则负责将CMake的抽象描述转换为具体构建系统（如Makefile、Ninja文件）所需的输入。理解这三者的关系，是掌握CMake的关键。

2.1 CMake核心概念：CMakeLists.txt、目标与生成器

2.1.1 CMakeLists.txt：构建的“源代码”

CMakeLists.txt是CMake构建系统的入口文件，它采用纯文本形式，由一系列CMake命令、变量定义和控制结构组成。每个包含CMakeLists.txt的目录都被视为一个“CMake项目”或“子项目”。当执行cmake命令时，CMake会解析当前目录下的CMakeLists.txt，并根据其中的指令生成对应的构建系统文件。

CMakeLists.txt的核心职责包括：

• 声明项目信息：通过project()命令指定项目名称、版本、支持的编程语言。
• 定义构建目标：使用add_executable()或add_library()创建可执行文件或库目标。
• 配置编译参数：通过target_compile_options()、target_compile_definitions()等命令设置编译选项和宏定义。
• 管理依赖关系：使用target_link_libraries()将目标与库目标关联，实现依赖传递。
• 处理平台差异：通过if()/else()条件判断，针对不同操作系统、编译器或硬件平台执行不同的配置逻辑。

在TinyML项目中，CMakeLists.txt通常采用分层结构：顶层CMakeLists.txt负责全局配置（如交叉编译工具链、全局编译选项），子目录中的CMakeLists.txt则负责各自模块的构建逻辑。这种分层设计使得项目结构清晰，便于维护和扩展。

2.1.2 目标（Target）：构建产物的抽象

目标是CMake 3.0之后引入的核心抽象概念。一个目标代表一个构建产物，可以是可执行文件、静态库、动态库或接口库。目标具有名称、类型、源文件列表、编译选项、链接库等属性。CMake通过目标来管理构建过程中的依赖关系和属性传递。

目标的主要类型包括：

目标类型	创建命令	典型用途	示例
可执行文件	add_executable()	生成最终运行的应用程序	主程序、测试程序
静态库	add_library(... STATIC)	打包源码为.a文件，链接时静态合并	算法库、驱动库
动态库	add_library(... SHARED)	生成.so/.dll，运行时动态加载	插件、共享模块
接口库	add_library(... INTERFACE)	仅传递编译选项/头文件路径，无实际编译产物	头文件库、纯模板库

目标之间通过target_link_libraries()建立依赖关系。例如，可执行目标app链接静态库目标core，则app会自动继承core的公共头文件路径、编译定义和链接库。这种传递性大大简化了依赖管理。

2.1.3 生成器（Generator）：连接CMake与底层构建工具

生成器是CMake的“后端”，负责将CMakeLists.txt中的抽象描述转换为特定构建系统所需的输入文件。常见的生成器包括：

• Unix Makefiles：Linux/macOS默认生成器，生成Makefile文件，使用make命令构建。
• Ninja：生成build.ninja文件，构建速度更快，适合大型项目。
• Visual Studio：生成.sln解决方案文件，集成于Windows IDE。
• Xcode：生成.xcodeproj项目文件，用于Apple平台开发。
• MinGW Makefiles：Windows下配合MinGW工具链使用。

在TinyML场景中，我们通常需要交叉编译，即为嵌入式目标平台（如ARM Cortex-M）生成构建文件。此时需要指定工具链文件（toolchain file），并通过-DCMAKE_TOOLCHAIN_FILE参数传递给CMake。生成器的选择直接影响构建效率和调试体验，例如在嵌入式开发中，Ninja因其并行构建能力和清晰的错误输出而备受青睐。

2.2 常用CMake命令详解

2.2.1 add_executable：创建可执行目标

add_executable()命令用于定义一个可执行文件目标。其基本语法为：

add_executable(<name> [WIN32] [MACOSX_BUNDLE]
               [EXCLUDE_FROM_ALL]
               [source1 [source2 ...]])

其中，<name>是目标的逻辑名称，对应生成的可执行文件名（在Windows下会自动添加.exe后缀）。源文件列表可以包含相对路径或路径，也可以使用变量或通配符（不推荐使用通配符，因为CMake无法自动追踪新增文件）。

示例：

add_executable(main
    src/main.cpp
    src/neural_net.cpp
    src/tensor_ops.cpp
)

在TinyML项目中，可执行目标通常是主程序入口，它链接了模型推理库、硬件抽象层和驱动库。需要注意的是，对于嵌入式平台，生成的可执行文件可能是ELF格式，需要后续通过objcopy转换为二进制镜像。

2.2.2 add_library：创建库目标

add_library()命令用于创建库目标，支持静态库、动态库和接口库三种类型。语法如下：

add_library(<name> [STATIC | SHARED | MODULE | INTERFACE]
            [EXCLUDE_FROM_ALL]
            [source1 [source2 ...]])

如果不指定类型，CMake会根据BUILD_SHARED_LIBS变量的值决定默认类型（默认静态库）。在TinyML项目中，静态库是最常用的类型，因为嵌入式设备通常不支持动态链接，且静态库便于将代码直接合并到最终固件中。

示例：

add_library(tflite-micro STATIC
    src/tensorflow/lite/micro/all_ops_resolver.cc
    src/tensorflow/lite/micro/micro_interpreter.cc
    src/tensorflow/lite/micro/micro_mutable_op_resolver.cc
)

接口库（INTERFACE）在TinyML项目中也有重要应用。例如，当我们需要为多个目标共享同一组头文件路径和编译选项时，可以创建一个接口库：

add_library(common_defs INTERFACE)
target_include_directories(common_defs INTERFACE
    ${CMAKE_CURRENT_SOURCE_DIR}/include
    ${CMAKE_CURRENT_SOURCE_DIR}/third_party
)
target_compile_definitions(common_defs INTERFACE
    TF_LITE_STATIC_MEMORY
    TF_LITE_DISABLE_X86_NEON
)

这样，任何链接了common_defs的目标都会自动获得这些头文件路径和编译定义，无需重复配置。

2.2.3 target_link_libraries：管理目标依赖

target_link_libraries()命令用于指定目标链接的库，并建立目标间的依赖关系。其语法为：

target_link_libraries(<target>
    <PRIVATE|PUBLIC|INTERFACE> <item>...
    [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)

关键字PRIVATE、PUBLIC、INTERFACE控制依赖的传递范围：

• PRIVATE：仅当前目标使用该依赖，不传递给链接当前目标的其他目标。
• PUBLIC：当前目标使用该依赖，且传递给链接当前目标的其他目标。
• INTERFACE：当前目标不使用该依赖，但传递给链接当前目标的其他目标。

示例：

add_executable(main src/main.cpp)
target_link_libraries(main
    PRIVATE tflite-micro
    PUBLIC common_defs
)

在这个例子中，main链接了tflite-micro库（仅自身使用），同时链接了common_defs接口库（其头文件路径和编译定义会传递给任何链接main的目标）。这种精细的依赖控制有助于保持构建系统的清晰性和可维护性。

2.3 最小示例：从零构建一个TinyML风格项目

下面我们通过一个最小但完整的示例，演示如何使用CMake构建一个简单的TinyML风格项目。该项目包含一个主程序、一个静态库（模拟模型推理库）和一个接口库（共享编译选项）。

2.3.1 项目结构

tiny_ml_demo/
├── CMakeLists.txt          # 顶层CMake配置
├── src/
│   ├── main.cpp            # 主程序入口
│   └── model.cpp           # 模型推理实现
├── include/
│   └── model.h             # 模型接口头文件
└── third_party/
    └── common.h            # 公共定义

2.3.2 顶层CMakeLists.txt

cmake_minimum_required(VERSION 3.16)
project(tiny_ml_demo CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 创建接口库，共享编译选项和头文件路径
add_library(common_defs INTERFACE)
target_include_directories(common_defs INTERFACE
    ${CMAKE_CURRENT_SOURCE_DIR}/include
    ${CMAKE_CURRENT_SOURCE_DIR}/third_party
)
target_compile_definitions(common_defs INTERFACE
    TINY_ML_DEMO
)

# 创建静态库，模拟模型推理核心
add_library(model_core STATIC
    src/model.cpp
)
target_link_libraries(model_core
    PUBLIC common_defs
)

# 创建可执行文件
add_executable(main
    src/main.cpp
)
target_link_libraries(main
    PRIVATE model_core
)

2.3.3 源码文件

src/model.h：

#pragma once
int run_inference(const float* input, float* output, int size);

src/model.cpp：

#include "model.h"
#include "common.h"

int run_inference(const float* input, float* output, int size) {
    // 模拟简单的模型推理：逐元素加1
    for (int i = 0; i < size; ++i) {
        output[i] = input[i] + 1.0f;
    }
    return 0;
}

src/main.cpp：

#include <iostream>
#include "model.h"

int main() {
    constexpr int kSize = 4;
    float input[kSize] = {1.0f, 2.0f, 3.0f, 4.0f};
    float output[kSize] = {0.0f};

    run_inference(input, output, kSize);

    for (int i = 0; i < kSize; ++i) {
        std::cout << "output[" << i << "] = " << output[i] << std::endl;
    }
    return 0;
}

2.3.4 构建与运行

mkdir build && cd build
cmake ..
make
./main

输出结果：

output[0] = 2
output[1] = 3
output[2] = 4
output[3] = 5

这个最小示例展示了CMake的核心工作流程：通过add_library(INTERFACE)共享配置，通过add_library(STATIC)封装实现，通过add_executable()生成最终程序，并通过target_link_libraries()建立依赖关系。在实际TinyML项目中，这个结构可以扩展到包含TensorFlow Lite Micro、CMSIS-NN、硬件驱动等多个模块。

2.4 常见误区与总结复盘

2.4.1 常见误区

• 误区一：在CMakeLists.txt中使用路径。路径会破坏项目的可移植性。应使用${CMAKE_CURRENT_SOURCE_DIR}、${CMAKE_CURRENT_BINARY_DIR}等CMake内置变量，或使用相对路径。
• 误区二：滥用file(GLOB ...)收集源文件。虽然GLOB可以自动匹配文件，但CMake不会自动检测新增文件，需要重新运行cmake。在TinyML项目中，建议显式列出源文件，确保构建的可预测性。
• 误区三：忽略PRIVATE/PUBLIC/INTERFACE关键字。不指定关键字时，CMake默认使用PUBLIC，可能导致不必要的依赖传递，增加编译时间和耦合度。
• 误区四：在顶层CMakeLists.txt中堆砌所有配置。对于TinyML项目，应使用add_subdirectory()将不同模块（如模型推理、驱动、测试）拆分为独立的子目录，每个子目录有自己的CMakeLists.txt，便于维护和复用。
• 误区五：忘记设置CMAKE_CXX_STANDARD。TinyML项目通常需要C++14或C++17支持，应在顶层明确设置标准，避免编译器默认标准不一致导致的问题。

2.4.2 总结复盘

本章我们系统学习了CMake的三大核心概念：CMakeLists.txt作为构建脚本，目标作为构建产物的抽象，生成器作为连接CMake与底层构建工具的桥梁。通过最小示例，我们实践了add_executable()、add_library()和target_link_libraries()三个最常用的命令，并理解了PRIVATE/PUBLIC/INTERFACE依赖传递机制。

在TinyML项目实践中，CMake的价值不仅在于跨平台构建，更在于它能够优雅地管理复杂的依赖关系——从第三方库（如TensorFlow Lite Micro）到硬件抽象层，再到具体的驱动实现。掌握CMake的核心概念，是搭建可维护、可扩展的TinyML项目的第一步。

下一阶段，我们将深入探讨如何为TinyML项目配置交叉编译工具链，包括工具链文件的编写、架构选项的设置以及如何验证交叉编译环境的正确性。这将为后续在真实嵌入式硬件上部署模型奠定基础。