3. Gecko SDK工程架构与构建系统

Gecko SDK（GSDK）从 v3.x 起全面转向以 CMake 为核心的构建体系，Simplicity Studio 5 只是这套体系的一层图形外壳。理解 CMake 构建流程、组件依赖管理、配置文件与自动生成代码这四者的关系，是排查“为什么某个源文件没被编译”“为什么改了 .slcp 后代码没更新”这类问题的前提。本节以 EFM32/EFR32 系列（如 EFR32MG24）的蓝牙或 Zigbee 工程为例，说明这套机制如何协同工作。

一、工程目录结构与四类关键文件

一个典型的 GSDK 工程在磁盘上分为“用户可编辑区”和“生成区”两部分。用户区包括 .slcp 工程描述文件、app.c/app.h 等应用代码、*.slcp 引用的配置文件；生成区位于 autogen/ 目录，由构建系统在配置阶段自动产生，不应手工修改。核心文件类型如下：

• *.slcp（Simplicity Config Project）：工程清单，声明目标芯片、SDK 版本、组件列表、配置项覆盖值，是构建系统的唯一事实来源。
• *.slcc：组件定义文件，描述某个组件依赖哪些其他组件、需要哪些源文件、暴露哪些配置选项。
• *.slcw：工作区文件，用于多工程组合。
• autogen/：自动生成的 sl_component_catalog.h、sl_event_handler.c、sl_gatt_service_*.c、sl_bluetooth_config.h 等。

二、CMake 构建流程

GSDK 的构建分为配置（configure）与生成（build）两个阶段。配置阶段由 slc（Simplicity Studio CLI 工具）驱动，它读取 .slcp，解析组件依赖树，展开所有 .slcc，最终生成一份完整的 CMake 工程到 autogen/ 下，包括 CMakeLists.txt、slc_args.cmake 和各类头文件。构建阶段则由 CMake + Ninja/Make 完成，编译生成区与用户区的源文件并链接成 .out/.hex。

命令行下最常用的两条命令是：

# 配置阶段：解析 .slcp，生成 autogen 与 CMake 工程
slc generate my_project.slcp -o build -d build -np

# 构建阶段：调用 CMake 编译
cmake -G Ninja -S build -B build/out
ninja -C build/out

其中 -np 表示不生成项目文件（仅生成 CMake），-d 指定输出目录。若在 Simplicity Studio 中点击 Build，本质上是执行了同样的两步，只是把中间产物放在 autogen/ 下。

三、组件依赖管理

组件是 GSDK 的最小复用单元，例如 bluetooth_stack、freertos、sleep_timer、board_init。每个组件在 .slcc 中声明 requires（强依赖）、recommends（推荐依赖）和 provides（对外提供的接口）。当你在 .slcp 中勾选一个组件时，slc 会递归解析依赖树，自动把被依赖的组件一并加入，并检测版本冲突。

依赖解析的结果会写入 autogen/sl_component_catalog.h，其中每个已启用组件对应一个 #define SL_COMPONENT_CATALOG_PRESENT_xxx 宏。应用代码通过 #ifdef 判断某组件是否存在，从而避免编译不存在的接口。例如：

#include "sl_component_catalog.h"
#ifdef SL_COMPONENT_CATALOG_PRESENT_SLEEP_TIMER
#include "sl_sleeptimer.h"
#endif

依赖冲突的典型表现是 slc 报 Component dependency resolution failed，此时应检查两个组件是否要求了互斥的 SDK 版本或同一外设的不同实例。

四、配置文件与自动生成代码

组件暴露的配置项（如蓝牙最大连接数、GATT 服务表、时钟源）在 .slcp 中以 config 段保存。slc 在配置阶段把这些值展开为 C 头文件，例如 sl_bluetooth_config.h 中的 SL_BT_CONFIG_MAX_CONNECTIONS。同时，sl_event_handler.c 会按组件初始化顺序生成 sl_system_init() 的调用序列，sl_gatt_service_*.c 则根据 GATT 配置生成服务注册代码。

关键原则是：生成区代码不要手改。一旦重新执行 slc generate，所有手工修改都会被覆盖。需要定制时，应通过 .slcp 的 config 覆盖、或在用户区编写回调函数（如 sl_bt_on_event）来实现。

五、实操：从修改配置到验证生成结果

假设需要把蓝牙最大连接数从 1 改为 4。正确做法不是直接改 sl_bluetooth_config.h，而是在 .slcp 的 config 段中覆盖：

config:
  - name: SL_BT_CONFIG_MAX_CONNECTIONS
    value: 4

保存后重新执行 slc generate，再检查 autogen/sl_bluetooth_config.h 中该宏是否变为 4。若未变化，说明 config 名称拼写与组件定义不一致，需回到 .slcc 中核对选项名。确认无误后执行 ninja -C build/out，观察编译日志中是否重新编译了依赖该宏的源文件。

六、构建系统排障要点

当构建失败时，按以下顺序定位：先看 slc 配置阶段是否报依赖解析错误；再看 autogen/CMakeLists.txt 是否包含预期源文件；最后看编译错误是否来自生成区与用户区的接口不匹配（如回调函数签名变更）。掌握“.slcp → slc → autogen/ → CMake → 可执行文件”这条链路，就能把大部分构建问题定位到具体环节，而不是盲目重装 SDK。