跳到主要内容

应用结构与构建

先建立一个周期打印计数的程序。之后用同一份代码学习 Kconfig 和设备树，不在每一章换一个大工程。完整文件在 examples/learning-app/，尚未烧录实板，编译结果见本页末尾。

文件结构​

learning-app/
├── CMakeLists.txt          # 把 main.c 加入 app 目标
├── Kconfig                 # 定义自己的配置符号
├── prj.conf                # 选择本应用的配置值
├── backlight.conf          # 后续 GPIO 实验的额外配置
├── boards/waveshare.overlay
└── src/main.c

最小应用只需要 CMakeLists、prj.conf 与 main.c。本例多加了 Kconfig，目的是让打印周期成为可配置参数。

CMake 构建配置​

cmake_minimum_required(VERSION 3.28.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(learning_app)
target_sources(app PRIVATE src/main.c)

find_package 载入 Zephyr 的构建逻辑，放在 project 前。target_sources 把自己的 C 文件加入 app 目标；Zephyr 内核、驱动和模块按构建规则另行加入。不需要把上游全部源码逐一写在这里。

增加 src/ui.c 后必须让 CMake 知道它，例如在 target_sources 中再加一项。只把文件放进 src 目录不会自动参与编译。

应用入口​

核心逻辑是：

while (1) {
    printk("count=%u\n", count++);
    k_sleep(K_MSEC(CONFIG_APP_PERIOD_MS));
}

CONFIG_APP_PERIOD_MS 在编译时成为常量，不是运行时读取 prj.conf。k_sleep 让 main 线程进入等待状态，其他可运行线程能获得 CPU；main 不会因为休眠而重新开始执行。

完整程序同时打印 uptime，后面可对比配置周期与实际时间差。打印、调度也消耗时间，所以两个时间戳之差并不保证严格等于配置值。

构建应用​

source ~/Projects/zephyr-main-workspace/.venv-py312-main/bin/activate
export ZEPHYR_SDK_INSTALL_DIR=~/.local/opt/zephyr-sdk-1.0.1
cd ~/Projects/zephyr-main-workspace/zephyr
west build -p always -b esp32s3_touch_lcd_1_28/esp32s3/procpu \
  ~/Projects/zephyr-docs/examples/learning-app \
  -d build/learning-app
参数含义
应用绝对路径哪份 CMakeLists、prj.conf 和 main.c
-b选择板卡、SoC 和 CPU 核
-d生成构建文件和固件的位置
-p always清理这个输出目录后重新配置，避免旧缓存影响

应用在哪里和板卡是什么是两个独立选择。源码目录可以位于单独 Git 仓库，不必移入 zephyr/boards。

构建产物​

rg 'CONFIG_APP_PERIOD_MS|CONFIG_APP_BACKLIGHT' build/learning-app/zephyr/.config
rg 'APPLICATION_SOURCE_DIR|ZEPHYR_BASE|BOARD:' build/learning-app/CMakeCache.txt

应看到周期为 1000，背光功能未开启。产物包括：

文件用途
zephyr/.configKconfig 的最终结果
zephyr/zephyr.dts设备树合并结果
zephyr/zephyr.elf带地址、符号等信息，供调试工具使用
zephyr/zephyr.bin本板烧录镜像之一，由 runner 选择
zephyr/runners.yaml构建记录的烧录工具与参数

不直接修改输出目录里的配置，重新构建会覆盖它们。保存修改应回到源码的 prj.conf、Kconfig 或 overlay。

烧录和练习​

端口按实际枚举结果替换，先退出占用串口的软件：

west flash -d build/learning-app --esp-device /dev/ttyACM0
cd build/learning-app
west espressif monitor -p /dev/ttyACM0 -b 115200

预期启动日志写出 period=1000 ms，计数逐次增加。这是预期，不是已采集实板日志。

练习：只修改打印文字，用同一构建目录执行 west build -d build/learning-app（回到 zephyr 根目录）。观察增量构建不会重新编译所有文件。然后修改 prj.conf 中周期为 200，重新构建，观察最终 .config 和实际输出变化。

2026-09-22：本机 Fedora、Zephyr 52b48529aec、SDK 1.0.1 下，默认打印和额外配置加 overlay 的背光版本均编译通过；最终配置分别为 1000 ms/背光关闭、500 ms/背光开启。尚未烧录实板。

下一章：Kconfig 如何定义和选择参数。来源：应用开发及本仓库完整示例。