# 工具

[English]

## 安装 gdbgui

安装脚本中已移除对 `--enable-gdbgui` 参数的支持，因此不再能通过该方式安装 gdbgui。请参考 gdbgui 安装指南 使用 `pipx` 方式进行安装。

根据操作系统和 Python 版本的不同，可能需要参考 已知问题列表。

例如，目前所有操作系统均 不支持 Python 3.13。

gdbgui 自 v0.14 起不再支持 Windows 操作系统。由于其他兼容性问题，Windows 下需使用 Python 3.10，并配合特定依赖版本。可通过以下命令安装已知可用的 gdbgui 及其所需版本的依赖：

    pipx install "gdbgui==0.13.2.0" "pygdbmi<=0.9.0.2" "python-socketio<5" "jinja2<3.1" "itsdangerous<2.1"

如果操作系统为 Linux 或 macOS，可以使用 Python 3.11 或 3.12 以及 gdbgui v0.15.2.0。

请注意，以上推荐的版本可能会发生变化，请按需查阅 官方问题追踪页面 查看最新问题列表。

如果安装过程中遇到问题，建议使用 `idf.py gdb` 代替 `idf.py gdbgui`，或使用 Eclipse 或 VSCode 进行调试。

## `idf.py efuse*` 命令需要指定串口

所有 eFuse 相关命令现在都必须指定串口。这样做是为了防止意外使用错误的端口，因为这些操作是不可逆的。

对所有 `idf.py efuse*` 命令，需使用 `--port` 参数（或设置 `ESPPORT` 环境变量）明确指定串口。未指定时，命令将报错并终止执行。

## Python 3.9 弃用说明

Python 3.9 已不再受支持。现在要求的最低 Python 版本为 3.10。请将你的 Python 升级至 3.10 或更高版本，或者使用 Docker 镜像：IDF Docker 镜像。

参考 Python 官方文档 获取不同操作系统的 Python 升级指南。

对于 Linux 用户，建议升级到包含受支持 Python 版本的较新发行版。

## 配置文件语法变更

ESP-IDF v6 使用了 esp-idf-kconfig v3，对配置文件 `Kconfig` 的语法进行了若干变更。完整变更列表请参阅 Migration Guide From esp-idf-kconfig v2.x to v3.x。

## CMake 版本升级

最低支持的 CMake 版本已升级至 3.22.1。如果你在构建过程中遇到与此相关的问题，建议将操作系统升级到包含 CMake 3.22 或更高版本。

如果无法升级操作系统，可以使用以下命令安装推荐的 CMake 版本：`./tools/idf_tools.py install cmake`。

此变更影响所有使用系统自带 CMake 或自定义 CMake 的 ESP-IDF 用户。

## Unit-Test-App

旧版的 unit-test-app 已经从 ESP-IDF 仓库中移出，目前已无 ESP-IDF 组件使用该组件进行测试。现在可通过 乐鑫组件注册表 获取 unit-test-app，并且可以使用 `idf.py create-project-from-example` 命令创建测试应用：

    idf.py create-project-from-example espressif/unit-test-app:unit-test-app

## Catch

之前位于 tools/catch 目录下的 Catch2 单元测试库（仅头文件）已被移除。若想在项目中继续使用 Catch2，请迁移至 Catch2 3.x，该版本可从 乐鑫组件注册表 中获取。关于从 Catch2 2.x 迁移到 Catch2 3.x 的示例，请参见 79a2c15477dc327550ff46a64ee0f8b4679cc417 中的提交记录。

## 移除 `idf.py size --legacy` 选项

`idf.py size` 命令的 `--legacy` 参数已被移除，因为旧版实现已不再受支持。`ESP_IDF_SIZE_LEGACY` 环境变量也随之失效。如需继续使用旧版选项，请使用 ESP-IDF 5.5 或更早版本。对于 ESP-IDF v6.0 及更高版本，请直接将 `idf.py size --legacy` 替换为 `idf.py size`。若遇到 esp-idf-size 版本问题，请运行安装脚本更新至正确版本。

## 更改 `idf.py size --format json` 为 `--format json2`

`--format json` 选项已替换为 `--format json2`。`json2` 格式提供了更完善的结构，为每个内存区域提供明确的 `total`、`used` 和 `free` 字段，并在 `parts` 部分提供详细分类。迁移时，请将 `idf.py size --format json` 替换为 `idf.py size --format json2`。

- 旧格式 (json)：扁平结构，内存类型字段直接列出，如 `"dram_data": 9192, "iram_text": 43295`。

- 新格式 (json2)：分层结构，包含一个 `layout` 数组来表示内存区域：

  >     {
  >         "version": "1.1",
  >         "layout": [
  >             {
  >                 "name": "DRAM",
  >                 "total": 180736,
  >                 "used": 11344,
  >                 "free": 169392,
  >                 "parts": {
  >                     ".data": {"size": 9192},
  >                     ".bss": {"size": 2152}
  >                 }
  >             }
  >         ]
  >     }

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。