ESP-IDF编译系统详解（2）-编程知识

接前一篇文章：ESP-IDF编译系统详解（1）

本文内容主要参考：

《ESP32-C3物联网工程开发实战》 —— 乐鑫科技编著

特此致谢！

2. 工程文件结构

工程（Project，也称为项目）是指一个包含入口函数main、用户自定义组件，以及构建可执行应用程序所需的编译脚本、配置文件、分区表等文件的文件夹。工程可以被复制和传递，并可在安装了相同版本ESP-IDF开发环境的机器中编译生成相同的可执行文件。

笔者之前建立的VSCODE+ESP-IDF的工程结构如下所示：

（1）组件（components）

组件是模块化且独立的代码，在编译系统中以文件夹的形式管理（文件夹名默认为组件名）。经过组件的编译脚本，可以指定其编译参数和依赖关系。在编译时，组件会被编译成独立的静态库（.a）文件，最终在链接阶段共同组成应用程序。

ESP-IDF的关键功能（如操作系统、外设驱动、网络协议栈等）是以组件的形式提供的，这些组件保存在ESP-IDF根目录下的components目录中。

开发者无须将这些组件复制到myProject（其工程）的components目录中，只需要在CMakeLists.txt中使用REQUIRES或PRIV_REQUIRES指明对它们的依赖关系即可，编译系统会自动找到该组件并对其进行编译。

因此客户工程（myProject）下components目录并不是必需的。这里仅用于包含项目的部分自定义组件，自定义组件可以是第三方库或者用户的自定义代码。除此之外，组件也可以来自非ESP-IDF或非当前工程的任意目录，如来源于在其它目录下保存的开源项目。这时只需要在根目录的CMakeLists.txt中通过设置EXTRA_COMPONNT_DIRS变量来添加该组件的查找位置即可。

（2）入口程序

main目录和其它组件（如component1）的文件结构是一样的，它是一个必须存在的特殊组件。一个工程有且仅有一个main目录，该目录包含了项目本身的源代码和用户程序的入口app_main，用户程序默认从此处开始执行。main组件的特殊之处还有，它默认依赖于所有搜索路径中的组件，因此不必再自己的CMakeLists.txt中使用REQUIRES或PRIV_REQUIRES指明依赖关系。

（3）配置文件

工程的根目录下包含了一个名为sdkconfig的配置文件，该文件包含了工程所有组件的配置参数。其内容如下（只截取开头部分）：

#
# Automatically generated file. DO NOT EDIT.
# Espressif IoT Development Framework (ESP-IDF) 5.2.1 Project Configuration
#
CONFIG_SOC_ADC_SUPPORTED=y
CONFIG_SOC_DEDICATED_GPIO_SUPPORTED=y
CONFIG_SOC_UART_SUPPORTED=y
CONFIG_SOC_GDMA_SUPPORTED=y
CONFIG_SOC_AHB_GDMA_SUPPORTED=y
CONFIG_SOC_GPTIMER_SUPPORTED=y
CONFIG_SOC_TWAI_SUPPORTED=y
CONFIG_SOC_BT_SUPPORTED=y
CONFIG_SOC_ASYNC_MEMCPY_SUPPORTED=y
CONFIG_SOC_USB_SERIAL_JTAG_SUPPORTED=y
CONFIG_SOC_TEMP_SENSOR_SUPPORTED=y
CONFIG_SOC_XT_WDT_SUPPORTED=y
CONFIG_SOC_WIFI_SUPPORTED=y
CONFIG_SOC_SUPPORTS_SECURE_DL_MODE=y
CONFIG_SOC_EFUSE_KEY_PURPOSE_FIELD=y
CONFIG_SOC_EFUSE_HAS_EFUSE_RST_BUG=y
CONFIG_SOC_EFUSE_SUPPORTED=y
CONFIG_SOC_RTC_FAST_MEM_SUPPORTED=y
CONFIG_SOC_RTC_MEM_SUPPORTED=y
CONFIG_SOC_I2S_SUPPORTED=y
CONFIG_SOC_RMT_SUPPORTED=y
CONFIG_SOC_SDM_SUPPORTED=y
CONFIG_SOC_GPSPI_SUPPORTED=y
CONFIG_SOC_LEDC_SUPPORTED=y
CONFIG_SOC_I2C_SUPPORTED=y
……

sdkconfig文件是由编译系统自动生成的，可通过命令idf.py menuconfig进行修改并重新生成。

C:\Users\ns\esp32\helloworld>idf.py menuconfig
Executing action: menuconfig
Running cmake in directory C:\Users\ns\esp32\helloworld\build
Executing "cmake -G Ninja -DPYTHON_DEPS_CHECKED=1 -DPYTHON=C:\Espressif\python_env\idf5.2_py3.11_env\Scripts\python.exe -DESP_PLATFORM=1 -DCCACHE_ENABLE=1 C:\Users\ns\esp32\helloworld"...
-- ccache will be used for faster recompilation
-- git rev-parse returned 'fatal: not a git repository (or any of the parent directories): .git'
-- Could not use 'git describe' to determine PROJECT_VER.
-- Building ESP-IDF components for target esp32c3
-- Project sdkconfig file C:/Users/ns/esp32/helloworld/sdkconfig
-- App "hello_world" version: 1
-- Adding linker script C:/Users/ns/esp32/helloworld/build/esp-idf/esp_system/ld/memory.ld
-- Adding linker script C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_system/ld/esp32c3/sections.ld.in
-- Adding linker script C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_rom/esp32c3/ld/esp32c3.rom.ld
-- Adding linker script C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_rom/esp32c3/ld/esp32c3.rom.api.ld
-- Adding linker script C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_rom/esp32c3/ld/esp32c3.rom.libgcc.ld
-- Adding linker script C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_rom/esp32c3/ld/esp32c3.rom.newlib.ld
-- Adding linker script C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_rom/esp32c3/ld/esp32c3.rom.version.ld
-- Adding linker script C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_rom/esp32c3/ld/esp32c3.rom.eco3.ld
-- Adding linker script C:/Espressif/frameworks/esp-idf-v5.2.1/components/soc/esp32c3/ld/esp32c3.peripherals.ld
-- Components: app_trace app_update bootloader bootloader_support bt cmock console cxx driver efuse esp-tls esp_adc esp_app_format esp_bootloader_format esp_coex esp_common esp_eth esp_event esp_gdbstub esp_hid esp_http_client esp_http_server esp_https_ota esp_https_server esp_hw_support esp_lcd esp_local_ctrl esp_mm esp_netif esp_netif_stack esp_partition esp_phy esp_pm esp_psram esp_ringbuf esp_rom esp_system esp_timer esp_wifi espcoredump esptool_py fatfs freertos hal heap http_parser idf_test ieee802154 json log lwip main mbedtls mqtt newlib nvs_flash nvs_sec_provider openthread partition_table protobuf-c protocomm pthread riscv sdmmc soc spi_flash spiffs tcp_transport ulp unity usb vfs wear_levelling wifi_provisioning wpa_supplicant
-- Component paths: C:/Espressif/frameworks/esp-idf-v5.2.1/components/app_trace C:/Espressif/frameworks/esp-idf-v5.2.1/components/app_update C:/Espressif/frameworks/esp-idf-v5.2.1/components/bootloader C:/Espressif/frameworks/esp-idf-v5.2.1/components/bootloader_support C:/Espressif/frameworks/esp-idf-v5.2.1/components/bt C:/Espressif/frameworks/esp-idf-v5.2.1/components/cmock C:/Espressif/frameworks/esp-idf-v5.2.1/components/console C:/Espressif/frameworks/esp-idf-v5.2.1/components/cxx C:/Espressif/frameworks/esp-idf-v5.2.1/components/driver C:/Espressif/frameworks/esp-idf-v5.2.1/components/efuse C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp-tls C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_adc C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_app_format C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_bootloader_format C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_coex C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_common C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_eth C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_event C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_gdbstub C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_hid C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_http_client C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_http_server C:/Espressif/frameworks/esp-idf-v5.2.1/components/esp_https_ota C:/Espressif/frameworks/esp-idf-v5.2.1/components/e(Top)                                                                                                                                                                          Espressif IoT Development Framework Configuration                                              Build type  --->                                                                                                                     Bootloader config  --->                                                                                                              Security features  --->                                                                                                              Application manager  --->                                                                                                            Boot ROM Behavior  --->                                                                                                              Serial flasher config  --->                                                                                                          Partition Table  --->                                                                                                                Compiler options  --->                                                                                                               Component config  --->                                                                                                           [ ] Make experimental features visible                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    [Space/Enter] Toggle/enter  [ESC] Leave menu           [S] Save                                                                      [O] Load                    [?] Symbol info            [/] Jump to symbol                                                            [F] Toggle show-help mode   [C] Toggle show-name mode  [A] Toggle show-all mode                                                      [Q] Quit (prompts for save) [D] Save minimal config (advanced)

menuconfig中的选项主要从工程的Kconfig.projbuild以及组件的Kconfig导入，组件的开发者一般通过在Kconfig中添加配置项，使组件具有灵活可配置的特性。

（4）编译目录（build）

使用命令idf.py build编译产生的中间文件和最终的可执行程序，将默认保存在工程的build目录中。

C:\Users\ns\esp32\helloworld>dir build……2024/04/26  14:00    <DIR>          .
2024/04/26  11:49    <DIR>          ..
2024/04/26  14:00               148 .ninja_log
2024/04/26  11:49                77 app-flash_args
2024/04/26  11:49    <DIR>          bootloader
2024/04/26  11:49                83 bootloader-flash_args
2024/04/26  11:49    <DIR>          bootloader-prefix
2024/04/26  13:58         5,134,145 build.ninja
2024/04/26  13:58            25,231 CMakeCache.txt
2024/04/26  13:58    <DIR>          CMakeFiles
2024/04/26  11:49             1,827 cmake_install.cmake
2024/04/26  13:58         4,498,841 compile_commands.json
2024/04/26  11:49    <DIR>          config
2024/04/26  11:49             6,406 config.env
2024/04/26  13:58    <DIR>          esp-idf
2024/04/26  11:49               937 flasher_args.json
2024/04/26  11:49                77 flash_app_args
2024/04/26  11:49               152 flash_args
2024/04/26  11:49               192 flash_args.in
2024/04/26  11:49                83 flash_bootloader_args
2024/04/26  11:49               152 flash_project_args
2024/04/26  11:49             4,030 kconfigs.in
2024/04/26  11:49               449 kconfigs_projbuild.in
2024/04/26  11:49             4,307 ldgen_libraries
2024/04/26  11:49             1,994 ldgen_libraries.in
2024/04/26  11:49    <DIR>          log
2024/04/26  11:49                96 partition-table-flash_args
2024/04/26  11:49           154,009 project_description.json20 个文件      9,833,236 字节8 个目录 416,276,602,880 可用字节

一般情况下，用户不必查看build目录的内容，ESP-IDF预定义了操作该目录的命令。如使用命令“idf.py flash”将自动找到编译生成的二进制文件，并烧录到指定的Flash地址；使用命令“idf.py fullclean”可以对整个build目录进行清理。

（5）分区表（partitions.csv）

每一个工程都会配置相应的分区表，用于划分Flash的空间，指明可执行程序和用户数据空间的大小、起始地址等。命令“idf.py flash”或者OTA升级程序据此将固件烧录到Flash的对应地址。ESP-IDF在components/partitin_table中提供了几套系统默认的分区表，如partitions_singleapp.csv和partitions_two_ota.csv等，用户可以在menuconfig中进行选择。