ESP32 之 ESP-IDF 教学（五）——IDF工程项结构

本文章 来自原创专栏《ESP32教学专栏 (基于ESP-IDF)》，讲解如何使用 ESP-IDF 构建 ESP32 程序，发布文章并会持续为已发布文章添加新内容！ 每篇文章都经过了精打细磨！

↓↓↓通过下方对话框进入专栏目录页↓↓↓
CSDN 请求进入目录 　　　　　　_ O x

是否进入ESP32教学导航(基于ESP-IDF)?

　　　　　　　确定

---

1、IDF工程简介

一个 ESP-IDF 项目可以看作是多个不同组件的集合，例如一个显示当前湿度的网页服务器会包含以下组件：

• ESP-IDF 基础库，包括 libc、ROM bindings 等

• Wi-Fi 驱动

• TCP/IP 协议栈

• FreeRTOS 操作系统

• 网页服务器

• 湿度传感器的驱动

• 负责将上述组件整合到一起的主程序

在ESP-IDF借助CMake的可自定义性，独创了“组件”式的工程。

整个工程是由若干个组件构成。可以理解成每个组件都是一块积木。含有用户应用程序入口函数的组件称为“main”组件。组件之间的关系以依赖关系为主。每个组件可以有单独的配置。

ESP-IDF 可以显式地指定和配置每个组件。在构建项目的时候，构建系统会前往 ESP-IDF 目录、项目目录和用户自定义组件目录（可选）中查找所有组件，允许用户通过文本菜单系统配置 ESP-IDF 项目中用到的每个组件。在所有组件配置结束后，构建系统开始编译整个项目。

ESP32工程有如下重要概念：

• 项目 (Project) 特指一个目录，其中包含了构建可执行应用程序所需的全部文件和配置，以及其他支持型文件，例如分区表、数据/文件系统分区和引导程序。

• 项目配置 保存在项目根目录下名为sdkconfig的文件中，可以通过 idf.py menuconfig 进行修改，且一个项目只能包含一个项目配置。

• 应用程序 是由 ESP-IDF 构建得到的可执行文件。一个项目通常会构建两个应用程序：项目应用程序（可执行的主文件，即用户自定义的固件）和引导程序（启动并初始化项目应用程序）。

• 组件 (Components) 是模块化且独立的代码，会被编译成静态库（.a 文件）并链接到应用程序。部分组件由 ESP-IDF 官方提供，其他组件则来源于其它开源项目。

• 目标 (Target) 特指运行构建后应用程序的硬件设备。ESP-IDF 当前仅支持 esp32 和 esp32s2 以及 esp32c3 这三个硬件目标。

请注意，以下内容并不属于项目的组成部分：

• ESP-IDF 并不是项目的一部分，它独立于项目，通过 IDF_PATH 环境变量（保存 esp-idf 目录的路径）链接到项目，从而将 IDF 框架与项目分离。
• 交叉编译工具链并不是项目的组成部分，它应该被安装在系统 PATH 环境变量中。

2、ESP-IDF 的工程解构详解

使用idf.py新建工程：

idf.py create-project 工程名

新ESP-IDF工程为CMake工程，CMakeLists.txt是它的构建脚本

类似于Java界Maven工程的pom.xml，Gradle工程的build.gradle或build.gradle.kts

使用idf.py即可使用构建系统构建，您还可以使用集成了 CMake 的 IDE（如CLion），仅需将项目 CMakeLists.txt 文件的路径告诉 IDE 即可。集成 CMake 的 IDE 通常会有自己的构建工具（CMake 称之为“生成器”），它是组成 IDE 的一部分，用来构建源文件。

【1】ESP-IDF 的工程文件夹详析

• 顶层项目 CMakeLists.txt 文件，这是 CMake 用于学习如何构建项目的主要文件，可以在这个文件中设置项目全局的 CMake 变量。顶层项目 CMakeLists.txt 文件会导入 /tools/cmake/project.cmake 文件，由它负责实现构建系统的其余部分。该文件最后会设置项目的名称，并定义该项目。

• “sdkconfig” 项目配置文件，执行 idf.py menuconfig 时会创建或更新此文件，文件中保存了项目中所有组件（包括 ESP-IDF 本身）的配置信息。 sdkconfig 文件可能会也可能不会被添加到项目的源码管理系统中。

• 可选的 “components” 目录中包含了项目的部分自定义组件，并不是每个项目都需要这种自定义组件，但它有助于构建可复用的代码或者导入第三方（不属于 ESP-IDF）的组件。或者，您也可以在顶层 CMakeLists.txt 中设置 EXTRA_COMPONENT_DIRS 变量以查找其他指定位置处的组件。有关详细信息，请参阅 重命名 main 组件。如果项目中源文件较多，建议将其归于组件中，而不是全部放在 “main” 中。

• “main” 目录是一个特殊的组件，它包含项目本身的源代码。”main” 是默认名称，CMake 变量 COMPONENT_DIRS 默认包含此组件，但您可以修改此变量。

• “build” 目录是存放构建输出的地方，如果没有此目录，idf.py 会自动创建。CMake 会配置项目，并在此目录下生成临时的构建文件。随后，在主构建进程的运行期间，该目录还会保存临时目标文件、库文件以及最终输出的二进制文件。此目录通常不会添加到项目的源码管理系统中，也不会随项目源码一同发布。

【2★】项目 CMakeList.txt 文件

每个项目都有一个顶层 CMakeLists.txt 文件，包含整个项目的构建设置。默认情况下，项目 CMakeLists 文件会非常小。

cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(myProject)

上文中最小的CMakeList.txt中：

• cmake_minimum_required(VERSION 3.5) 必须放在 CMakeLists.txt 文件的第一行，它会告诉 CMake 构建该项目所需要的最小版本号。ESP-IDF 支持 CMake 3.5 或更高的版本。
• include($ENV{IDF_PATH}/tools/cmake/project.cmake) 会导入 CMake 的其余功能来完成配置项目、检索组件等任务。
• project(myProject) 会创建项目本身，括号内容作为项目名称。

为项目 CMakeList.txt 的 必要部分。除此之外，还有一些 可选部分。

以下这些变量都有默认值，用户可以覆盖这些变量值以自定义构建行为。更多实现细节。

• COMPONENT_DIRS：组件的搜索目录，默认为 IDF_PATH/components、 工程文件夹/components、和变量 EXTRA_COMPONENT_DIRS。如果您不想在这些位置搜索组件，请覆盖此变量。
  (通常情况下此变量不需要覆盖，如果想要添加额外的组件，请放到) 工程文件夹/components或者变量EXTRA_COMPONENT_DIRS中
• EXTRA_COMPONENT_DIRS：用于搜索组件的其它可选目录列表。路径可以是相对于项目目录的相对路径，也可以是绝对路径。
• COMPONENTS：要构建进项目中的组件名称列表，默认为 COMPONENT_DIRS 目录下检索到的所有组件。使用此变量可以“精简”项目以缩短构建时间。请注意，如果一个组件通过 COMPONENT_REQUIRES 指定了它依赖的另一个组件，则会自动将其添加到 COMPONENTS 中，所以 COMPONENTS 列表可能会非常短。

以上变量中的路径可以是绝对路径，或者是相对于项目目录的相对路径。

请使用 cmake 中的 set() 命令 来设置这些变量。
如 set(VARIABLE "VALUE")。

请注意
想要使用set() 命令设置上文的变量，请将其放在 include(...) 之前，cmake_minimum(...) 之后。

【3★】组件 CMakeList.txt 文件

组件是 COMPONENT_DIRS 列表中的任何目录。此列表中的目录可以是组件自身（即包含 CMakeLists.txt 文件的目录），也可以是子目录为组件的顶级目录，例如$ENV{PROJECT_DIR}/components

构建 或 编译 时，ESP-IDF 搜索所有待构建的组件的顺序为COMPONENT_DIRS 指定的顺序依次进行。
因此，在默认情况下：

1. 搜索 ESP-IDF 内部组件（$ENV{IDF_PATH}/components）
2. 搜索 EXTRA_COMPONENT_DIRS 中的组件
3. 搜索项目组件（$ENV{PROJECT_DIR}/components）

注意
如果这些目录中的两个或者多个包含具有相同名字的组件，则使用 搜索到的最后一个 位置的组件。这就允许将组件复制到项目目录中再修改以覆盖 ESP-IDF 组件。


这样做的优点时可以在 “替换” ESP-IDF内置组件时，ESP-IDF 目录本身可以保持不变。

组件的最小的CMakeList.txt文件十分简洁，只有一句

idf_component_register(	
	SRCS 		   "foo.c"	"cplus.cpp"
	INCLUDE_DIRS   "include"
)

其中：

• SRCS 是源文件列表（.c、.cpp、.cc、.S），里面所有的源文件都将会编译进组件库中。
• INCLUDE_DIRS 是目录列表，里面的路径会被添加到所有需要该组件的组件（包括 main 组件）全局 include 搜索路径中。

除此之外，还有很多非必须的参数，可以通过CLion CMake按住Ctrl跳转至源码查看详情。

• REQUIRES 声明组件的public依赖，可供其他依赖者访问
• PRIV_REQUIRES声明private依赖，只能被当前组件访问。
• ...

有关更多关于组件 CMakeList.txt 的使用和细节，请参照乐鑫官方文档https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/build-system.html#id40

3*、参考文章列表

• 乐鑫ESP-IDF文档 API指南 构建系统：https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/build-system.html#id40