第三章 工程结构解析：Zephyr项目目录结构、CMakeLists.txt与Kconfig体系、应用与内核分离设计

好，我们进入第三章。这一章我打算聊聊Zephyr的工程结构。说实话，我第一次接触Zephyr时，被它的目录结构搞得有点懵。跟FreeRTOS那种「一个文件夹搞定」的风格完全不同，Zephyr的工程组织方式更像一个成熟的Linux发行版。你想想看，一个支持几百种芯片、上千种板子的RTOS，它的工程结构必然要足够灵活。

3.1 Zephyr项目目录结构：从顶层到底层

我们先从最宏观的角度看。一个标准的Zephyr项目，通常包含三个主要区域：Zephyr内核本身、应用代码、以及构建输出。我个人习惯把这三者严格分开，避免混在一起。

典型的目录结构长这样：

my_zephyr_project/
├── zephyr/                 # Zephyr内核源码（通常作为子模块）
│   ├── arch/               # 架构相关代码（ARM, RISC-V, x86等）
│   ├── boards/             # 板级支持包
│   ├── drivers/            # 驱动框架与实现
│   ├── kernel/             # 内核核心代码
│   ├── lib/                # 库函数
│   ├── subsys/             # 子系统（蓝牙、网络、USB等）
│   ├── cmake/              # CMake模块与工具链
│   └── Kconfig             # 顶层Kconfig入口
├── app/                    # 你的应用代码
│   ├── src/                # 源文件
│   ├── include/            # 头文件
│   ├── CMakeLists.txt      # 应用构建文件
│   └── prj.conf            # 应用配置
└── build/                  # 构建输出目录（自动生成）

这里有个关键点：应用代码和内核代码是分离的。这不是巧合，而是Zephyr刻意设计的结果。我在做第一个Zephyr项目时，曾试图把应用代码直接塞进内核目录里，结果被同事狠狠批评了一顿。后来我才明白，这种分离设计是为了让多个项目共享同一个内核，同时保持各自的应用独立性。

核心原则：Zephyr内核是平台，你的应用是乘客。平台可以换，但乘客的行李（代码）应该打包好。

再深入一点，看看boards/目录。这里存放着所有支持的开发板定义。每个板子一个文件夹，里面包含：

  • 板级DTS文件（.dts）：描述硬件连接，比如GPIO分配、UART引脚等
  • 板级Kconfig：定义该板子特有的配置选项
  • CMakeLists.txt：板级构建规则
  • 文档和图片：方便开发者识别板子

举个例子，如果你用STM32F4 Discovery板，它的定义就在boards/arm/stm32f4_disco/下。我曾经踩过一个坑：自己画了一块板子，但忘了在DTS里正确描述SPI引脚，结果调试了整整两天才发现是引脚映射错了。嗯，从那以后我每次画板子都会先仔细核对DTS文件。

3.2 CMakeLists.txt与Kconfig体系：构建系统的双引擎

Zephyr的构建系统由两个核心组件驱动：CMake和Kconfig。它们分工明确：CMake负责「怎么编译」，Kconfig负责「编译什么」。

3.2.1 CMakeLists.txt：构建的骨架

一个典型的应用层CMakeLists.txt长这样：

cmake_minimum_required(VERSION 3.20)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)

target_sources(app PRIVATE src/main.c src/sensor.c)
target_include_directories(app PRIVATE include)

这里有几个关键点：

  • find_package(Zephyr REQUIRED)：这行命令会加载Zephyr的构建系统。说白了，它告诉CMake：「我要用Zephyr，请把它的编译规则、链接脚本、工具链都准备好」。
  • target_sources：添加你的源文件。我建议把所有源文件显式列出来，不要用file(GLOB ...)。为什么？因为GLOB不会自动检测新文件，你加了一个.c文件后必须重新运行cmake，否则它不会被编译。这个坑我踩过好几次。
  • target_include_directories：指定头文件路径。注意用PRIVATE关键字，避免污染其他模块。

如果你有多个模块，可以用add_subdirectory()组织：

# 顶层CMakeLists.txt
cmake_minimum_required(VERSION 3.20)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_app)

add_subdirectory(drivers)
add_subdirectory(components)

target_sources(app PRIVATE src/main.c)

每个子目录里也有自己的CMakeLists.txt，这样代码结构就清晰多了。

3.2.2 Kconfig：配置的魔法

Kconfig是Zephyr最强大的特性之一。它源自Linux内核，用于管理成百上千的配置选项。你想想看，一个RTOS要支持那么多芯片、协议栈、驱动，如果全靠手动定义宏，那简直是灾难。Kconfig就是来解决这个问题的。

应用层的配置通常放在prj.conf文件里：

# prj.conf
CONFIG_STACK_SIZE=4096
CONFIG_SERIAL=y
CONFIG_GPIO=y
CONFIG_I2C=y
CONFIG_LOG=y
CONFIG_LOG_BACKEND_UART=y

每一行都是一个配置选项。=y表示启用，=n表示禁用，=数值用于设置参数。这些配置最终会生成一个autoconf.h文件，被C代码包含。

小技巧：如果你不确定某个配置选项是否存在，可以用west build -t menuconfig打开图形化配置界面。我个人习惯先用menuconfig探索一遍，再把最终配置写进prj.conf。

Kconfig的依赖关系非常强大。比如，你启用了CONFIG_BLUETOOTH，它会自动启用CONFIG_NETWORKING、CONFIG_RX_STACK_SIZE等依赖项。我曾经遇到一个问题：启用了蓝牙但忘了开CONFIG_BT_HCI_HOST，结果编译通过但运行时蓝牙完全不工作。后来我学会了用west build -t guiconfig查看依赖树，一眼就发现了问题。

3.3 应用与内核分离设计：为什么这么设计？

这是Zephyr区别于很多RTOS的核心设计理念。传统的RTOS（比如FreeRTOS、uC/OS）通常把应用代码和内核代码混在一起，或者至少放在同一个工程目录下。Zephyr则强制要求分离。

为什么？三个原因：

  1. 复用性：同一个内核可以服务于多个应用。你只需要切换app/目录，内核代码完全不用动。
  2. 升级便利：当Zephyr发布新版本时，你只需要更新zephyr/目录，应用代码几乎不需要修改。我在项目中经历过从Zephyr 2.6升级到3.0，应用代码只改了几行配置，内核升级就完成了。
  3. 团队协作：内核团队和应用团队可以独立工作。内核开发者专注于驱动和调度器，应用开发者专注于业务逻辑，互不干扰。

具体到代码层面，应用通过Zephyr的API与内核交互。比如：

#include <zephyr/kernel.h>
#include <zephyr/device.h>
#include <zephyr/drivers/gpio.h>

void main(void)
{
    const struct device *dev;
    int ret;

    // 获取GPIO设备
    dev = DEVICE_DT_GET(DT_NODELABEL(gpio0));
    if (!device_is_ready(dev)) {
        printk("GPIO device not ready\n");
        return;
    }

    // 配置引脚为输出
    ret = gpio_pin_configure(dev, 5, GPIO_OUTPUT_ACTIVE);
    if (ret < 0) {
        printk("Failed to configure pin\n");
        return;
    }

    // 循环闪烁
    while (1) {
        gpio_pin_set(dev, 5, 1);
        k_sleep(K_MSEC(500));
        gpio_pin_set(dev, 5, 0);
        k_sleep(K_MSEC(500));
    }
}

注意看，应用代码里没有直接操作寄存器，也没有包含任何硬件相关的头文件。它通过device.h和gpio.h这些抽象接口来访问硬件。这就是分离设计的好处——你的应用代码可以在不同板子上编译运行，只要板级支持包正确配置。

避坑指南：我曾经在应用代码里直接调用了HAL_GPIO_WritePin()（STM32的HAL库函数），结果换到NXP的板子上就编译不过了。记住，永远不要绕过Zephyr的API直接操作硬件。否则你的代码就失去了可移植性。

3.4 实战：从零搭建一个分离式项目

说了这么多理论，我们来动手做一个。假设我们要创建一个智能灯控项目，结构如下：

smart_light/
├── zephyr/                 # 作为git子模块
├── app/
│   ├── src/
│   │   ├── main.c
│   │   ├── light_control.c
│   │   └── wifi_manager.c
│   ├── include/
│   │   ├── light_control.h
│   │   └── wifi_manager.h
│   ├── CMakeLists.txt
│   └── prj.conf
└── build/

第一步，初始化Zephyr环境：

west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.5.0 smart_light
cd smart_light
west update

第二步，创建应用代码。CMakeLists.txt：

cmake_minimum_required(VERSION 3.20)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(smart_light)

target_sources(app PRIVATE
    src/main.c
    src/light_control.c
    src/wifi_manager.c
)

target_include_directories(app PRIVATE include)

prj.conf：

CONFIG_GPIO=y
CONFIG_PWM=y
CONFIG_WIFI=y
CONFIG_NETWORKING=y
CONFIG_LOG=y
CONFIG_LOG_BACKEND_UART=y
CONFIG_HEAP_MEM_POOL_SIZE=4096

第三步，编译：

west build -b esp32_devkitc_wroom app
west flash

你看，整个过程中，内核代码完全没动。如果你要换到nRF52840 DK，只需要改-b nrf52840dk_nrf52840，应用代码一行都不用改。这就是分离设计的威力。

总结一下：Zephyr的工程结构不是随便设计的。目录分离、CMake+Kconfig双引擎、应用与内核解耦，这些设计都是为了解决嵌入式开发中的实际问题——可移植性、可维护性、团队协作。我做了这么多年嵌入式，见过太多项目因为工程结构混乱而陷入泥潭。Zephyr的这套体系，值得你花时间吃透。

下一章，我们会深入Zephyr的设备驱动模型，看看它是如何实现「一套API驱动所有硬件」的。到时候我会分享一个我调试I2C驱动时遇到的奇葩问题，保证让你印象深刻。

← 上一章 📖 返回目录 下一章 →