警告

This document is not updated for ESP32H2 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

迁移构建系统至 ESP-IDF v5.0

从 GNU Make 构建系统迁移至 ESP-IDF v5.0

ESP-IDF v5.0 已不再支持基于 Make 的工程,请参考 从 ESP-IDF GNU Make 构建系统迁移到 CMake 构建系统 进行迁移。

更新片段文件语法

请参考 将链接器脚本片段文件语法迁移至 ESP-IDF v5.0 适应版本 对 v3.x 的语法进行更新。

明确指定组件依赖

在之前的 ESP-IDF 版本中,除了 通用组件依赖项,还有一些组件总是作为公共依赖项在构建中被添加至每个组件中,如:

  • driver

  • efuse

  • esp_timer

  • lwip

  • vfs

  • esp_wifi

  • esp_event

  • esp_netif

  • esp_eth

  • esp_phy

这意味着可以直接包含这些组件的头文件,而无需在 idf_component_register 中将它们指定为依赖。此行为是由各种常见组件的传递依赖关系引起的。

在 ESP-IDF v5.0 中,此行为已修复,这些组件不再默认作为公共依赖项添加。

如果组件所依赖的某个组件不属于通用组件依赖项,则必须显式地声明此依赖关系。可以通过在组件的 CMakeLists.txt 中的 idf_component_register 调用中添加 REQUIRES <component_name>PRIV_REQUIRES <component_name> 来完成。有关指定组件依赖的更多信息,请参阅 组件依赖

设置 COMPONENT_DIRSEXTRA_COMPONENT_DIRS 变量

为了实现构建项目时的路径能够包含空格,ESP-IDF v5.0 做了一系列改进,其中包括改进了 CMakeLists.txt 文件中的 COMPONENT_DIRSEXTRA_COMPONENT_DIRS 变量。

ESP-IDF v5.0 版本中,不再支持添加不存在的目录到变量 COMPONENT_DIRSEXTRA_COMPONENT_DIRS 中,否则会出现报错。

同时,ESP-IDF v5.0 中也不再支持使用字符串拼接的方式定义 COMPONENT_DIRSEXTRA_COMPONENT_DIRS 变量。这些变量应该定义为 CMake 列表。 例如:

set(EXTRA_COMPONENT_DIRS path1 path2)
list(APPEND EXTRA_COMPONENT_DIRS path3)

不支持:

set(EXTRA_COMPONENT_DIRS "path1 path2")
set(EXTRA_COMPONENT_DIRS "${EXTRA_COMPONENT_DIRS} path3")

将这些变量定义为 CMake 列表的方式兼容之前的 ESP-IDF 版本。

更新 CMake 版本

在 ESP-IDF v5.0 中,最低 CMake 版本已更新到 3.16,并且不再支持低于 3.16 的版本。如果您的操作系统没有安装 CMake,请运行 tools/idf_tools.py install cmake 来安装合适的版本。

该变更会影响到使用系统提供的 CMake 以及自定义 CMake 的 ESP-IDF 用户。

重新定义特定目标配置文件的应用顺序

ESP-IDF v5.0 重新安排了特定目标配置文件和 SDKCONFIG_DEFAULTS 中所有其他文件的应用顺序。现在,特定目标的配置文件将在引入它的文件之后、在 SDKCONFIG_DEFAULTS 中后续的其他文件之前应用。

例如:

如果 ``SDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig_devkit1"``,且同一文件夹内有 ``sdkconfig.defaults.esp32`` 文件,那么文件的应用顺序为:(1) sdkconfig.defaults (2) sdkconfig.defaults.esp32 (3) sdkconfig_devkit1

如果某个键在不同的特定目标配置文件中有不同的值,那么后者的值会覆盖前者。例如在以上案例中,如果某个键在 sdkconfig.defaults.esp32sdkconfig_devkit1 中的值不同,则在 sdkconfig_devkit1 中的值会覆盖在 sdkconfig.defaults.esp32 中的值。

如果确实需要设置特定目标的配置值,请将其放到后应用的特定目标文件中,如 sdkconfig_devkit1.esp32