第 3 章 工程结构：构建系统如何“知道“要编译什么

本章从底层讲清三件事①CMake/Ninja 是怎么协作完成构建的②#include、REQUIRES、链接分别是什么机制③sdkconfig 和分区表在系统里扮演什么角色读完你就能看懂任何一个 ESP-IDF 工程而不是只会照抄。读法说明本章只读不跑——把工程文件当说明书读懂即可不需要手上有个能编译的工程。l298n 工程的文件会在第 3、8、12 章给全本章 3.2/3.3/3.6 是根 CMakeLists.txt、main/CMakeLists.txt、sdkconfig.defaults 三个第 8 章给 motor_control 两个文件第 12 章给 main.cpp也可以直接用随书源码包。真正动手编译烧录是第 2、4 章的事。3.1 构建系统的两层分工CMake规划和 Ninja执行CMakeLists.txt ──► CMake ──► build.ninja施工图──► Ninja ──► .o / .elf / .bin 规划 执行CMake读所有 CMakeLists.txt搞清楚工程有哪些文件、依赖谁、怎么编译生成一张叫build.ninja的施工图。它自己不动手。Ninja按施工图真正调用编译器干活还负责增量编译只重编改过的文件——靠对比文件时间戳。机制串起来第一次idf.py build或你改过任何一个 CMakeLists.txt 之后CMake 才会跑一遍生成/刷新build/build.ninja此后每次 build 直接由Ninja 读施工图比对时间戳——这就是第二次编译快得多的原因。为什么报错分两种CMake Error→ 规划阶段出错CMakeLists 写错ninja: build stopped: ...→ 执行阶段出错你的代码编译不过。3.2 工程级 CMakeLists.txt总告示牌下面是本书工程根目录CMakeLists.txt的逐字全文一字不改你可以打开自己工程的对照# 下面几行样板必须严格按此顺序出现否则 cmake 无法正确工作 cmake_minimum_required(VERSION 3.22) # 注意这里设置 CMAKE_CXX_STANDARD 是无效的。 # ESP-IDF 会在 project.cmake 里按 gnu26 gnu2b gnu20 ... gnu14 # 的顺序自动探测工具链支持的最高标准并把它追加到全局 CXX_COMPILE_OPTIONS # 后出现的 -std 会覆盖 CMake 自己生成的那个。 # 需要为单个组件固定标准时在组件的 CMakeLists.txt 里用 # target_compile_options(${COMPONENT_LIB} PRIVATE -stdgnu20) include($ENV{IDF_PATH}/tools/cmake/project.cmake) project(l298n)cmake_minimum_required要求 CMake 最低版本3.22用新特性要声明$ENV{IDF_PATH}读取环境变量IDF_PATH第 2 章 export 设置的找到 ESP-IDF 源码位置project.cmake里面定义了怎么扫描组件、怎么调 CMake/Ninja全套规则project(l298n)工程名 → 固件名l298n.bin。中间那段注释先求个眼熟在根 CMakeLists 里手动设 C 标准是无效的IDF 会自动探测工具链支持的最高标准当前是 gnu26。这句话为什么重要、真要给单个组件钉标准怎么办——第 5 章展开。3.3 main/CMakeLists.txt组件清单下面是本书工程main/CMakeLists.txt的逐字全文idf_component_register( SRCS main.cpp motor_control.cpp INCLUDE_DIRS . REQUIRES esp_driver_gpio # driver/gpio.h —— 方向引脚 esp_driver_ledc # driver/ledc.h —— PWM 输出 esp_rom # esp_rom_delay_us() —— 换向死区 ) # 关于 C 标准ESP-IDF 在 project.cmake 中会自动探测工具链支持的最高标准 # 当前 xtensa-esp-elf 15.2 为 gnu26并追加到全局 CXX_COMPILE_OPTIONS。 # 所以组件里写 set(CXX_STANDARD 11) 是无效的不要再加回来。 # 若确实要为单个组件降级/固定标准用下面这句后出现的 -std 才会生效 # target_compile_options(${COMPONENT_LIB} PRIVATE -stdgnu20)SRCS漏写一个文件会怎样每个.cpp都会被单独编译成一个.o。漏写 该文件完全不参与构建那么它里面的函数就没有定义 → 链接时出现undefined reference to DCMotor::init()声明在 .h 里有定义在没编译的 .cpp 里——链接器找不到。REQUIRES组件依赖ESP-IDF 把官方驱动也做成组件。REQUIRES声明我这个组件要用谁。作用把被依赖组件的头文件目录加进编译的 include 路径否则#include driver/gpio.h找不到文件链接时把被依赖组件的库链接进来否则 undefined reference确定构建顺序依赖的组件先编译。┌───── main 组件 ─────┐ │ 需要: gpio、ledc、 │ │ esp_rom │──► esp_driver_gpio / esp_driver_ledc ──► esp_rom └─────────────────────┘依赖是有向图A REQUIRES BB 必须先于 A 构建。卡住时先查依赖。为什么必须有 esp_driver_gpio——反面教材就在这里早期 IDF 有一个大而全的driver组件GPIO、LEDC、定时器……全装在里面REQUIRES driver一行全包。从 v5 后期开始这个大礼包被拆分成esp_driver_gpio、esp_driver_ledc、esp_driver_uart等一小组件到 v6driver只剩一点残余内容driver/gpio.h这个头文件是由esp_driver_gpio提供的。所以在 v6 工程里写笼统的REQUIRES driverdriver只剩 i2c/touch/twai几样残余GPIO 对它是私有依赖不往外传头文件目录#include driver/gpio.h照样报 No such file——这就是本书工程老老实实列esp_driver_gpio的原因正确姿势是用到什么补什么用了 GPIO 就esp_driver_gpio用了 LEDC 就esp_driver_ledc用了esp_rom_delay_us()就esp_rom——正是上面文件里 REQUIRES 恰好只有三个的原因。那日志的esp_log.h和 FreeRTOS 头文件为什么没列因为log、freertos这些由构建系统给每个组件自动加的公共依赖commonrequirements兜着不用自己写。REQUIRES 只写别人不会自动给你的。3.4 头文件机制#include的真相#include xxx.h在预处理阶段做的动作是把 xxx.h 的全部内容原样粘贴到这一行。就是这么原始。那被两个 .cpp 各贴一遍会不会出事分两种情况类定义、inline 函数、模板被多个 .cpp 各自包含一份合法。规则叫单一定义规则 ODR要求每个翻译单元里看到的定义完全一样翻译单元 一个 .cpp 连同被它#include贴进来的全部头文件编译器眼里的一份完整输入5.1 从编译流水线角度再讲一遍——同一个 .h 贴过去自然一样链接器把它们当同一份不会报错。本书的motor_control.h里整个class DCMotor就是这么被main.cpp和motor_control.cpp共同包含的安然无恙。普通函数的实现、全局变量的定义放进 .h出事了——两个 .cpp就产生两份同名符号链接时multiple definition重复定义错误。头文件保护防的是另一件事同一个 .h 在同一个 .cpp翻译单元里被绕来绕去贴第二遍比如 a.h 含了 b.hb.h 又含回 a.h第二遍就是编译错误类重定义。两种写法// 写法1#pragma once现代一个文件只贴一次——本书用的就是这个#pragmaonce// 写法2传统宏保护逐行读三行就是一个占坑-查坑机制#ifndefMOTOR_CONTROL_H// 如果宏 MOTOR_CONTROL_H 还没被定义过// 这个头文件在当前翻译单元里是第一次被贴……#defineMOTOR_CONTROL_H// ……就立刻把它定义上 占坑我贴过了classDCMotor{// 类的声明内容放这里};#endif// 保护到此为止。第二次绕来贴这个文件时// 坑已被占宏已定义#ifndef 不成立// 中间整段被跳过——类重定义错误就不会发生为什么.h里只放声明、.cpp里放定义因为定义函数实现、全局变量放进 .h → 被几个 .cpp 包含就产生几份→ 重复定义。声明可以重复每份 .cpp 记一笔账没关系定义不行。类定义/inline 属于允许各处各一份的特例见上面区分。3.5 链接把零件拼成整机链接器ld做的事收集所有 .o 和库检查每个 .o 里需要的符号undefined能否在别处找到定义按链接脚本linker script把各段.text/.data/.bss安排到目标芯片的内存地址第 0 章的内存映射表生成一个完整可运行的程序.elf含调试信息。main.o ──┐ motor.o ──┼──► 链接器 ──► l298n.elf带地址的完整程序 ledc.a ──┘undefined reference 有符号找不到定义声明了没实现 / 文件没编multiple definition 一个符号有多个定义实现放进了 .h。3.6 sdkconfigKconfig 配置系统配置从哪来ESP-IDF 的每个组件可以声明一堆开关Kconfig。menuconfig 是一个图形界面让你勾选。配置流程组件里的 Kconfig有哪些开关 │ menuconfig 勾选 sdkconfig.defaults默认值 ▼ sdkconfig实际配置自动生成含所有开关的值 │ 编译时被读取 ▼ 生成头文件 sdkconfig.h → 代码里可以用 CONFIG_XXX 宏为什么别手改 sdkconfigsdkconfig由工具自动生成/合并手改会被覆盖还可能漏改关联项。你要改的是sdkconfig.defaults你的默认值或通过 menuconfig。我们工程的默认配置逐字全文下面是本书sdkconfig.defaults的真实内容。别跳过注释——这些注释本身就是硬件说明书# ESP32-S3-WROOM-1-N16R8 硬件配置基线 # # 说明本文件只在 sdkconfig 尚不存在时全新配置才生效 # 用来给工程定一个和硬件匹配的下限。日常的 menuconfig 改动仍然保存在 sdkconfig 里。 # # 模组规格Espressif 官方 datasheet # Flash : 16 MBQuad SPI —— 占用 GPIO 26~32 # PSRAM : 8 MBOctal SPI —— 占用 GPIO 33~37 # 供电 : 3.3 V非 1.8 V 的 V 版本 CONFIG_IDF_TARGETesp32s3 # ---------- Flash ---------- # N16R8 的 flash 是 Quad千万不要开 CONFIG_ESPTOOLPY_OCT_FLASH。 # 只有 ESP32-S3-WROOM-2-N16R8V / N32R8V 这类 V 结尾模组才是 Octal Flash。 CONFIG_ESPTOOLPY_FLASHSIZE_16MBy CONFIG_ESPTOOLPY_FLASHMODE_DIOy CONFIG_ESPTOOLPY_FLASHFREQ_80My # ---------- PSRAM ---------- # R8 8MB 八线 PSRAM。八线模式对时序敏感80MHz 是稳的选择 # 120MHz 在 Octal 下属于实验特性温度漂移约 20 度就可能随机崩溃。 CONFIG_SPIRAMy CONFIG_SPIRAM_MODE_OCTy CONFIG_SPIRAM_SPEED_80My一句话读懂这个文件只负责把配置钉在和 N16R8 硬件匹配的下限上目标芯片、16MB Flash、DIO 模式、八线 80MHz PSRAM。⚠️ 有读者会问第 5 章讲体积优化时 sdkconfig 里明明出现了CONFIG_COMPILER_OPTIMIZATION_SIZEy怎么这里没有项住在哪怎么进去的上面文件里的所有行sdkconfig.defaults建工程时就写好CONFIG_COMPILER_OPTIMIZATION_SIZEy只在 sdkconfig 里5.5/11 章做体积优化时用menuconfig选的menuconfig 把它直接写进 sdkconfig这正是文件头注释说的分工defaults 只在 sdkconfig 不存在时生效之后的改动都落在 sdkconfig 里。⚠️ 配置名全名陷阱menuconfig 里显示SPIRAM speed: 80MHz生成到 sdkconfig 里是CONFIG_SPIRAM_SPEED80但defaults 里必须写选项全名CONFIG_SPIRAM_SPEED_80My——少写_80M后缀不生效。【动手框】menuconfig 长什么样现在只要求看懂手痒可跟做① 在哪执行任一工程根目录比如第 2 章建的 blink/的 IDF 终端里。② 敲什么idf.py menuconfig③ 预期看到一个蓝底或你终端配色的全屏配置界面顶栏写着“Espressif IoT Development Framework Configuration”中间是Component config ---、Compiler options ---这样的菜单行底部一行提示类似Select Exit Help | Move UP DOWN Pgntab Enter。操作方式方向键上下移动、回车进入下一级或切换 y/n 选项/-调数值改完按S保存会问你写到哪默认sdkconfig回车确认再按Q退出——底部那行提示永远是当前可用的键。④ 没看到a)idf.py不是内部命令 → 回 2.2b/2.3 把终端激活b) 报Failed to start menuconfig→ 工程从没 build 过先跑一次idf.py set-target esp32s3c) 界面花屏 → 窗口太窄拉大重来。退出时若问你 “Do you want to save your new configuration?”选 Yes 才会写进 sdkconfig——本章只是看看的话选 No什么都没改。3.7 分区表Flash 里的户型图分区是什么Flash 很大16MB我们按功能切成一块块分区。bootloader 和程序都靠分区表找到自己的家。本书工程里其实没有partitions.csv这个文件——我们用的是 ESP-IDF内置的单 app 分区表partitions_singleapp.csv它的值与下表完全相同等需要自定义布局OTA 双分区等时再在工程根目录建partitions.csv见 18.1。内置表的内容# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, phy_init, data, phy, 0xf000, 0x1000, factory, app, factory, 0x10000, 0x100000,分区装什么大小nvs掉电不丢的小数据WiFi 配置等24KBphy_initWiFi 射频校准数据phy physical射频物理层第 16 章主角4KBfactory我们的程序1MB开头 0x1000064KB之前是 bootloader 和分区表自己的位置我们的程序装在0x10000 起、最多 1MB烧录时打印的0xd5eb0 bytes (84%) free就是 factory 分区剩余空间。启动时怎么找到程序bootloader二级引导读分区表 → 找到factory类型分区 → 校验镜像 →加载执行。这就是为什么改分区表要谨慎bootloader 和程序都依赖它。只有factory一个 app 分区时固件只能整体替换。要做OTA 在线升级分区表要改成otadata 双 app 分区结构——见第 18 章。3.8 build 目录中间产物与成品build/ ├── l298n.elf # 完整程序 调试信息addr2line 用它第 11 章 ├── l298n.bin # 烧录用文件去掉调试信息、按分区对齐 ├── CMakeFiles/ # 各文件的中间信息 └── log/ # 构建日志报错时可翻idf.py fullclean清空 build从头构建把.elf删了addr2line 就没法翻译崩溃地址——调试信息别删。3.9 组件可复用的积木官方组件和第三方组件都放在组件目录自定义组件放components/。每个组件要有自己的 CMakeLists.txtidf_component_register。组件的好处底层逻辑职责隔离 依赖管理。你的 motor 驱动如果做成组件别的工程REQUIRES motor就能复用——链接器只把用到的东西编进来。把组件写到产品级自己的 Kconfig 配置项、目录规范、单元测试的完整做法见第 17 章。3.10 常见错误速查报错机制原因修法undefined reference to ...声明了没定义 / .cpp 没编译补实现 / 补 SRCSfatal error: xxx.h: No such fileinclude 路径没有该目录REQUIRES 补依赖 / INCLUDE_DIRS 补路径multiple definition of ...函数/变量的定义被多个 .cpp 各编了一份实现移到 .cpp头文件保护只管同一编译单元重复贴CONFIG_XXX not found配置名写错Kconfig 没有该选项menuconfig 查准确全名CMake ErrorCMakeLists 语法/依赖问题看完整报错定位行号3.11 想一想 小测验想一想为什么 .h 里只能放声明不能放实现为什么漏写 SRCS 会报未定义引用而不是编译错程序住的分区是哪个它有多大小测验CMake 和 Ninja 的分工是CMake 负责____Ninja 负责____。#include在哪个阶段被处理A. 预处理 B. 链接 C. 烧录REQUIRES漏写会导致什么报错A. 端口占用 B. 头文件找不到 C. 烧录失败配置项CONFIG_SPIRAM_SPEED_80My想表达什么3.12 本章总结构建 CMake 规划 Ninja 执行报错先分规划错还是执行错头文件 预处理贴入声明可重复、定义不可链接 对符号、排地址漏编文件 → undefined referencesdkconfig 自动生成的配置单改 defaults 或 menuconfig分区表 Flash 户型图factory 分区住我们的程序1MB。下一章真正上手控制硬件GPIO 和它的底层电路。