tools: replace _ with - in idf.py

Closes https://github.com/espressif/esp-idf/issues/5126

.gitlab/ci/host-test.yml

@@ -208,7 +208,7 @@ test_idf_tools:
   script:
     - cd ${IDF_PATH}/components/efuse/
     - ./efuse_table_gen.py -t "${IDF_TARGET}" ${IDF_PATH}/components/efuse/${IDF_TARGET}/esp_efuse_table.csv
-    - git diff --exit-code -- ${IDF_TARGET}/esp_efuse_table.c || { echo 'Differences found for ${IDF_TARGET} target. Please run make efuse_common_table or idf.py efuse_common_table and commit the changes.'; exit 1; }
+    - git diff --exit-code -- ${IDF_TARGET}/esp_efuse_table.c || { echo 'Differences found for ${IDF_TARGET} target. Please run make efuse_common_table or idf.py efuse-common-table and commit the changes.'; exit 1; }
     - cd ${IDF_PATH}/components/efuse/test_efuse_host
     - ./efuse_tests.py
 

README.md

@@ -103,9 +103,9 @@ After the initial flash, you may just want to build and flash just your app, not
 
 ## Erasing Flash
 
-The `idf.py flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `idf.py erase_flash`.
+The `idf.py flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `idf.py erase-flash`.
 
-This can be combined with other targets, ie `idf.py -p PORT erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table.
+This can be combined with other targets, ie `idf.py -p PORT erase-flash flash` will erase everything and then re-flash the new app, bootloader and partition table.
 
 # Resources
 

README_CN.md

@@ -103,9 +103,9 @@ ESP-IDF 中的子模块采用相对路径（[详见 .gitmodules 文件](.gitmodu
 
 ## 擦除 Flash
 
-`idf.py flash` 并不会擦除 flash 上所有的内容，但是有时候我们需要设备恢复到完全擦除的状态，尤其是分区表发生了变化或者 OTA 应用升级时。要擦除整块 flash 请运行 `idf.py erase_flash`。
+`idf.py flash` 并不会擦除 flash 上所有的内容，但是有时候我们需要设备恢复到完全擦除的状态，尤其是分区表发生了变化或者 OTA 应用升级时。要擦除整块 flash 请运行 `idf.py erase-flash`。
 
-这条命令还可以和其余命令整合在一起，`idf.py -p PORT erase_flash flash` 会擦除一切然后重新烧写新的应用程序、引导程序和分区表。
+这条命令还可以和其余命令整合在一起，`idf.py -p PORT erase-flash flash` 会擦除一切然后重新烧写新的应用程序、引导程序和分区表。
 
 # 其它参考资源
 

components/app_update/CMakeLists.txt

@@ -55,7 +55,7 @@ if(NOT BOOTLOADER_BUILD)
                          "--partition-table-offset;${PARTITION_TABLE_OFFSET}")
         idf_component_get_property(esptool_py_dir esptool_py COMPONENT_DIR)
 
-        add_custom_target(read_otadata DEPENDS "${PARTITION_CSV_PATH}"
+        add_custom_target(read-otadata DEPENDS "${PARTITION_CSV_PATH}"
             COMMAND ${CMAKE_COMMAND}
             -D IDF_PATH="${idf_path}"
             -D SERIAL_TOOL="${otatool_py}"
@@ -65,8 +65,9 @@ if(NOT BOOTLOADER_BUILD)
             WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
             USES_TERMINAL
             )
+        add_deprecated_target_alias(read_otadata read-otadata)
 
-        add_custom_target(erase_otadata DEPENDS "${PARTITION_CSV_PATH}"
+        add_custom_target(erase-otadata DEPENDS "${PARTITION_CSV_PATH}"
             COMMAND ${CMAKE_COMMAND}
             -D IDF_PATH="${idf_path}"
             -D SERIAL_TOOL="${otatool_py}"
@@ -76,6 +77,7 @@ if(NOT BOOTLOADER_BUILD)
             WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
             USES_TERMINAL
             )
+        add_deprecated_target_alias(erase_otadata erase-otadata)
 
         idf_component_get_property(main_args esptool_py FLASH_ARGS)
         idf_component_get_property(sub_args esptool_py FLASH_SUB_ARGS)

components/efuse/CMakeLists.txt

@@ -39,9 +39,10 @@ idf_build_get_property(python PYTHON)
 # Make common files esp_efuse_table.c and include/esp_efuse_table.h files.
 set(EFUSE_COMMON_TABLE_CSV_PATH "${COMPONENT_DIR}/${target}/esp_efuse_table.csv")
 
-add_custom_target(efuse_common_table COMMAND "${python}"
+add_custom_target(efuse-common-table COMMAND "${python}"
                  "${CMAKE_CURRENT_SOURCE_DIR}/efuse_table_gen.py"
                  ${EFUSE_COMMON_TABLE_CSV_PATH} ${GEN_EFUSE_TABLE_ARG})
+add_deprecated_target_alias(efuse_common_table efuse-common-table)
 
 ###################
 # Make custom files project/main/esp_efuse_custom_table.c and project/main/include/esp_efuse_custom_table.h files.
@@ -51,15 +52,18 @@ if(${CONFIG_EFUSE_CUSTOM_TABLE})
     idf_build_get_property(project_dir PROJECT_DIR)
     get_filename_component(EFUSE_CUSTOM_TABLE_CSV_PATH "${CONFIG_EFUSE_CUSTOM_TABLE_FILENAME}"
                            ABSOLUTE BASE_DIR "${project_dir}")
-    add_custom_target(efuse_custom_table COMMAND "${python}" "${CMAKE_CURRENT_SOURCE_DIR}/efuse_table_gen.py"
+    add_custom_target(efuse-custom-table COMMAND "${python}" "${CMAKE_CURRENT_SOURCE_DIR}/efuse_table_gen.py"
                            ${EFUSE_COMMON_TABLE_CSV_PATH} ${EFUSE_CUSTOM_TABLE_CSV_PATH} ${GEN_EFUSE_TABLE_ARG})
+    add_deprecated_target_alias(efuse_custom_table efuse-custom-table)
 else()
-    add_custom_target(efuse_custom_table COMMAND)
+    add_custom_target(efuse-custom-table COMMAND)
+    add_deprecated_target_alias(efuse_custom_table efuse-custom-table)
 endif()#if(${CONFIG_EFUSE_CUSTOM_TABLE})
 
-add_custom_target(show_efuse_table COMMAND "${python}"
+add_custom_target(show-efuse-table COMMAND "${python}"
                   "${CMAKE_CURRENT_SOURCE_DIR}/efuse_table_gen.py"
                   ${EFUSE_COMMON_TABLE_CSV_PATH} ${EFUSE_CUSTOM_TABLE_CSV_PATH} ${GEN_EFUSE_TABLE_ARG} "--info")
+add_deprecated_target_alias(show_efuse_table show-efuse-table)
 
 ###################
 # Generates files for unit test. This command is run manually.

components/efuse/esp32/esp_efuse_table.csv

@@ -6,7 +6,7 @@
 ##########################################################################
 # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128.
 # !!!!!!!!!!! #
-# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table"
+# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table"
 # this will generate new source files, next rebuild all the sources.
 # !!!!!!!!!!! #
 

components/efuse/esp32c3/esp_efuse_table.csv

@@ -6,7 +6,7 @@
 ##########################################################################
 # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128.
 # !!!!!!!!!!! #
-# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table"
+# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table"
 # this will generate new source files, next rebuild all the sources.
 # !!!!!!!!!!! #
 

components/efuse/esp32h2/esp_efuse_table.csv

@@ -6,7 +6,7 @@
 ##########################################################################
 # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128.
 # !!!!!!!!!!! #
-# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table"
+# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table"
 # this will generate new source files, next rebuild all the sources.
 # !!!!!!!!!!! #
 

components/efuse/esp32s2/esp_efuse_table.csv

@@ -6,7 +6,7 @@
 ##########################################################################
 # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128.
 # !!!!!!!!!!! #
-# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table"
+# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table"
 # this will generate new source files, next rebuild all the sources.
 # !!!!!!!!!!! #
 

components/efuse/esp32s3/esp_efuse_table.csv

@@ -5,7 +5,7 @@
 #                   |     EFUSE_BLK10)|            |            |        #
 ##########################################################################
 # !!!!!!!!!!! #
-# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table"
+# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table"
 # this will generate new source files, next rebuild all the sources.
 # !!!!!!!!!!! #
 

components/partition_table/CMakeLists.txt

@@ -54,15 +54,16 @@ add_custom_target(partition_table_bin DEPENDS "${build_dir}/partition_table/${un
                                               "${build_dir}/partition_table/${final_partition_bin}")
 
 if(EXISTS ${partition_csv})
-    add_custom_target(partition_table
+    add_custom_target(partition-table
                         DEPENDS partition_table_bin
                         ${partition_table_display}
                         VERBATIM)
+    add_deprecated_target_alias(partition_table partition-table)
 else()
     # If the partition input CSV is not found, create a phony partition_table target that
     # fails the build. fail_at_build_time also touches CMakeCache.txt to cause a cmake run next time
     # (to pick up a new CSV if one exists, etc.)
-    fail_at_build_time(partition_table
+    fail_at_build_time(partition-table
         "Partition table CSV ${partition_csv} does not exist."
         "Either change partition table in menuconfig or create this input file.")
 endif()
@@ -81,7 +82,7 @@ if(CONFIG_SECURE_SIGNED_APPS_ECDSA_SCHEME)
             VERBATIM)
     else()
         string(REPLACE ";" " " espsecurepy "${ESPSECUREPY}")
-        add_custom_command(TARGET partition_table POST_BUILD
+        add_custom_command(TARGET partition-table POST_BUILD
             COMMAND ${CMAKE_COMMAND} -E echo
                 "Partition table built but not signed. Sign partition data before flashing:"
             COMMAND ${CMAKE_COMMAND} -E echo
@@ -89,7 +90,7 @@ if(CONFIG_SECURE_SIGNED_APPS_ECDSA_SCHEME)
             VERBATIM)
     endif()
 elseif(CONFIG_SECURE_SIGNED_APPS_RSA_SCHEME)
-    add_custom_command(TARGET partition_table POST_BUILD
+    add_custom_command(TARGET partition-table POST_BUILD
     COMMAND ${CMAKE_COMMAND} -E echo "Partition table built:"
     VERBATIM)
 endif()
@@ -98,9 +99,10 @@ idf_component_get_property(main_args esptool_py FLASH_ARGS)
 idf_component_get_property(sub_args esptool_py FLASH_SUB_ARGS)
 
 if(CONFIG_APP_BUILD_GENERATE_BINARIES)
-    esptool_py_flash_target(partition_table-flash "${main_args}" "${sub_args}")
+    esptool_py_flash_target(partition-table-flash "${main_args}" "${sub_args}")
-    esptool_py_flash_target_image(partition_table-flash partition_table "${PARTITION_TABLE_OFFSET}"
+    esptool_py_flash_target_image(partition-table-flash partition-table "${PARTITION_TABLE_OFFSET}"
                                         "${build_dir}/partition_table/${final_partition_bin}")
-    esptool_py_flash_target_image(flash partition_table "${PARTITION_TABLE_OFFSET}"
+    esptool_py_flash_target_image(flash partition-table "${PARTITION_TABLE_OFFSET}"
                                         "${build_dir}/partition_table/${final_partition_bin}")
+    add_deprecated_target_alias(partition_table-flash partition-table-flash)
 endif()

docs/en/api-guides/build-system.rst

@@ -96,9 +96,9 @@ The autocomplete support for PowerShell is planned in the future.
 Advanced Commands
 ^^^^^^^^^^^^^^^^^
 
-- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
+- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition-table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
 - There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the target.
-- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the target's entire flash chip.
+- ``idf.py -p PORT erase-flash`` will use esptool.py to erase the target's entire flash chip.
 - ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively. If you define variable ``-DOUTPUT_JSON=1`` when running CMake (or ``idf.py``), the output will be formatted as JSON not as human readable text. See ``idf.py-size`` for more information.
 - ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree, or when modifying CMake cache variables. For example, ``idf.py -DNAME='VALUE' reconfigure`` can be used to set variable ``NAME`` in CMake cache to value ``VALUE``.
 - ``idf.py python-clean`` deletes generated Python byte code from the IDF directory which may cause issues when switching between IDF and Python versions. It is advised to run this target after switching versions of Python.

docs/en/api-guides/partition-tables.rst

@@ -16,7 +16,7 @@ The simplest way to use the partition table is to open the project configuration
 * "Single factory app, no OTA"
 * "Factory app, two OTA definitions"
 
-In both cases the factory app is flashed at offset 0x10000. If you execute `idf.py partition_table` then it will print a summary of the partition table.
+In both cases the factory app is flashed at offset 0x10000. If you execute `idf.py partition-table` then it will print a summary of the partition table.
 
 Built-in Partition Tables
 -------------------------
@@ -155,7 +155,7 @@ Generating Binary Partition Table
 
 The partition table which is flashed to the {IDF_TARGET_NAME} is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats.
 
-If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process.
+If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition-table``, this conversion is done as part of the build process.
 
 To convert CSV to Binary manually::
 
@@ -165,7 +165,7 @@ To convert binary format back to CSV manually::
 
   python gen_esp32part.py binary_partitions.bin input_partitions.csv
 
-To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition_table`` are generated::
+To display the contents of a binary partition table on stdout (this is how the summaries displayed when running ``idf.py partition-table`` are generated::
 
   python gen_esp32part.py binary_partitions.bin
 
@@ -204,14 +204,14 @@ The binary format of the partition table contains an MD5 checksum computed based
 Flashing the partition table
 ----------------------------
 
-* ``idf.py partition_table-flash``: will flash the partition table with esptool.py.
+* ``idf.py partition-table-flash``: will flash the partition table with esptool.py.
 * ``idf.py flash``: Will flash everything including the partition table.
 
-A manual flashing command is also printed as part of ``idf.py partition_table`` output.
+A manual flashing command is also printed as part of ``idf.py partition-table`` output.
 
 .. note::
 
-  Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase_flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
+  Note that updating the partition table doesn't erase data that may have been stored according to the old partition table. You can use ``idf.py erase-flash`` (or ``esptool.py erase_flash``) to erase the entire flash contents.
 
 
 Partition Tool (parttool.py)

docs/en/api-reference/storage/nvs_flash.rst

@@ -16,7 +16,7 @@ Currently, NVS uses a portion of main flash memory through the :ref:`esp_partiti
 
 Future versions of this library may have other storage backends to keep data in another flash chip (SPI or I2C), RTC, FRAM, etc.
 
-.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``idf.py erase_flash`` target to erase all contents of the flash chip.
+.. note:: if an NVS partition is truncated (for example, when the partition table layout is changed), its contents should be erased. ESP-IDF build system provides a ``idf.py erase-flash`` target to erase all contents of the flash chip.
 
 .. note:: NVS works best for storing many small values, rather than a few large values of the type 'string' and 'blob'. If you need to store large blobs or strings, consider using the facilities provided by the FAT filesystem on top of the wear levelling library.
 
@@ -118,7 +118,7 @@ The XTS encryption keys in the :ref:`nvs_key_partition` can be generated in one
     i) Build and flash the partition table
     ::
 
-        idf.py partition_table partition_table-flash
+        idf.py partition-table partition-table-flash
 
     ii) Store the keys in the :ref:`nvs_key_partition` (on the flash) with the help of :component_file:`parttool.py<partition_table/parttool.py>` (see Partition Tool section in :doc:`partition-tables </api-guides/partition-tables>` for more details)
     ::

docs/en/api-reference/system/efuse.rst

@@ -52,8 +52,8 @@ The component has API functions for reading and writing fields. Access to the fi
 
 CSV files:
 
-* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command ``idf.py efuse_common_table``). Note that changes in this file can lead to incorrect operation.
+* common (`esp_efuse_table.csv`) - contains eFuse fields which are used inside the IDF. C-source generation should be done manually when changing this file (run command ``idf.py efuse-common-table``). Note that changes in this file can lead to incorrect operation.
-* custom - (optional and can be enabled by :ref:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file and running ``idf.py efuse_custom_table``.
+* custom - (optional and can be enabled by :ref:`CONFIG_EFUSE_CUSTOM_TABLE`) contains eFuse fields that are used by the user in their application. C-source generation should be done manually when changing this file and running ``idf.py efuse-custom-table``.
 
 
 Description CSV file
@@ -136,7 +136,7 @@ efuse_table_gen.py tool
 
 The tool is designed to generate C-source files from CSV file and validate fields. First of all, the check is carried out on the uniqueness of the names and overlaps of the field bits. If an additional `custom` file is used, it will be checked with the existing `common` file (esp_efuse_table.csv). In case of errors, a message will be displayed and the string that caused the error. C-source files contain structures of type `esp_efuse_desc_t`.
 
-To generate a `common` files, use the following command ``idf.py efuse_common_table`` or:
+To generate a `common` files, use the following command ``idf.py efuse-common-table`` or:
 
 .. code-block:: bash
 
@@ -148,7 +148,7 @@ After generation in the folder $IDF_PATH/components/efuse/`{IDF_TARGET_PATH_NAME
 * `esp_efuse_table.c` file.
 * In `include` folder `esp_efuse_table.c` file.
 
-To generate a `custom` files, use the following command ``idf.py efuse_custom_table`` or:
+To generate a `custom` files, use the following command ``idf.py efuse-custom-table`` or:
 
 .. code-block:: bash
 
@@ -274,7 +274,7 @@ For frequently used fields, special functions are made, like this :cpp:func:`esp
 How to add a new field
 ----------------------
 
-1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``idf.py show_efuse_table`` or the next command:
+1. Find a free bits for field. Show `esp_efuse_table.csv` file or run ``idf.py show-efuse-table`` or the next command:
 
 .. code-block:: none
 

docs/en/get-started-legacy/make-project.rst

@@ -75,4 +75,3 @@ The simplest way to use the partition table is to `make menuconfig` and choose o
 In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
 
 For more details about :doc:`partition tables <../api-guides/partition-tables>` and how to create custom variations, view the :doc:`documentation <../api-guides/partition-tables>`.
-

docs/zh_CN/api-guides/build-system.rst

@@ -96,9 +96,9 @@ idf.py
 高级命令
 ^^^^^^^^
 
-- ``idf.py app``，``idf.py bootloader``，``idf.py partition_table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。
+- ``idf.py app``，``idf.py bootloader``，``idf.py partition-table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。
 - ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 {IDF_TARGET_NAME}。
-- ``idf.py -p PORT erase_flash`` 会使用 esptool.py 擦除 {IDF_TARGET_NAME} 的整个 Flash。
+- ``idf.py -p PORT erase-flash`` 会使用 esptool.py 擦除 {IDF_TARGET_NAME} 的整个 Flash。
 - ``idf.py size`` 会打印应用程序相关的大小信息，``size-components`` 和 ``size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。如果您在运行 CMake（或 ``idf.py``）时定义了变量 ``-DOUTPUT_JSON=1``，那么输出的格式会变成 JSON 而不是可读文本。详情请查看 ``idf.py-size``。
 - ``idf.py reconfigure`` 命令会重新运行 CMake_ （即便无需重新运行）。正常使用时，并不需要运行此命令，但当源码树中添加/删除文件后或更改 CMake cache 变量时，此命令会非常有用，例如，``idf.py -DNAME='VALUE' reconfigure`` 会将 CMake cache 中的变量 ``NAME`` 的值设置为 ``VALUE``。
 - ``idf.py python-clean`` 会从 IDF 目录中删除生成的 Python 字节码，Python 字节码可能会在切换 IDF 和 Python 版本时引发问题，因此建议在切换 Python 后运行该命令。

docs/zh_CN/api-guides/partition-tables.rst

@@ -16,7 +16,7 @@
 -  "Single factory app, no OTA"
 -  "Factory app, two OTA definitions"
 
-在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `idf.py partition_table` ，即可以打印当前使用分区表的信息摘要。
+在以上两种选项中，出厂应用程序均将被烧录至 flash 的 0x10000 偏移地址处。这时，运行 `idf.py partition-table` ，即可以打印当前使用分区表的信息摘要。
 
 内置分区表
 ------------
@@ -155,7 +155,7 @@ Flags 字段
 
 烧写到 {IDF_TARGET_NAME} 中的分区表采用二进制格式，而不是 CSV 文件本身。此时，:component_file:`partition_table/gen_esp32part.py` 工具可以实现 CSV 和二进制文件之间的转换。
 
-如果您在项目配置菜单（``idf.py menuconfig``）中设置了分区表 CSV 文件的名称，然后构建项目或执行 ``idf.py partition_table``。这时，转换将在编译过程中自动完成。
+如果您在项目配置菜单（``idf.py menuconfig``）中设置了分区表 CSV 文件的名称，然后构建项目或执行 ``idf.py partition-table``。这时，转换将在编译过程中自动完成。
 
 手动将 CSV 文件转换为二进制文件::
 
@@ -165,7 +165,7 @@ Flags 字段
 
    python gen_esp32part.py binary_partitions.bin input_partitions.csv
 
-在标准输出（stdout）上，打印二进制分区表的内容（运行  ``idf.py partition_table`` 时展示的信息摘要也是这样生成的）::
+在标准输出（stdout）上，打印二进制分区表的内容（运行  ``idf.py partition-table`` 时展示的信息摘要也是这样生成的）::
 
    python gen_esp32part.py binary_partitions.bin
 
@@ -204,14 +204,14 @@ MD5 校验和
 烧写分区表
 ----------
 
--  ``idf.py partition_table-flash`` ：使用 esptool.py 工具烧写分区表。
+-  ``idf.py partition-table-flash`` ：使用 esptool.py 工具烧写分区表。
 -  ``idf.py flash`` ：会烧写所有内容，包括分区表。
 
-在执行 ``idf.py partition_table`` 命令时，手动烧写分区表的命令也将打印在终端上。
+在执行 ``idf.py partition-table`` 命令时，手动烧写分区表的命令也将打印在终端上。
 
 .. note::
 
-   分区表的更新并不会擦除根据旧分区表存储的数据。此时，您可以使用 ``idf.py erase_flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
+   分区表的更新并不会擦除根据旧分区表存储的数据。此时，您可以使用 ``idf.py erase-flash`` 命令或者 ``esptool.py erase_flash`` 命令来擦除 flash 中的所有内容。
 
 
 分区工具 (parttool.py)

docs/zh_CN/api-reference/storage/nvs_flash.rst

@@ -15,7 +15,7 @@ NVS 通过调用 ``spi_flash_{read|write|erase}`` API 对主 flash 的部分空
 
 NVS 库后续版本可能会增加其他存储器后端，实现将数据保存至其他 flash 芯片（SPI 或 I2C 接口）、RTC 或 FRAM 中。
 
-.. note:: 如果 NVS 分区被截断（例如，更改分区表布局时），则应擦除分区内容。可以使用 ESP-IDF 构建系统中的 ``idf.py erase_flash`` 命令擦除 flash 上的所有内容。
+.. note:: 如果 NVS 分区被截断（例如，更改分区表布局时），则应擦除分区内容。可以使用 ESP-IDF 构建系统中的 ``idf.py erase-flash`` 命令擦除 flash 上的所有内容。
 
 .. note:: NVS 最适合存储一些较小的数据，而非字符串或二进制大对象 (BLOB) 等较大的数据。如需存储较大的 BLOB 或者字符串，请考虑使用基于磨损均衡库的 FAT 文件系统。
 

docs/zh_CN/get-started-legacy/make-project.rst

@@ -75,5 +75,3 @@ ESP32 的一块 flash 可以包含多个应用程序，以及多种数据（校
 上述两种情况中，factory app 在 flash 中的烧录偏移地址均为 0x10000。运行 ``make partition_table`` 命令可以打印分区表摘要。
 
 更多有关 :doc:`分区表 <../api-guides/partition-tables>` 及自定义分区表的内容，请见 :doc:`相关文档 <../api-guides/partition-tables>`。
-
-

examples/security/flash_encryption/README.md

@@ -37,7 +37,7 @@ The configuration for NVS encryption involves generating the XTS encryption keys
 
     i) Build and flash the partition table:
     ```
-    idf.py partition_table partition_table-flash
+    idf.py partition-table partition-table-flash
     ```
     ii) Store the `sample_encryption_keys.bin` in the `nvs_key`partition (on the flash) with the help of [parttool.py](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html#partition-tool-parttool-py):
     ```

examples/storage/nvs_rw_blob/README.md

@@ -63,5 +63,4 @@ Run time:
 2: 5860
 ```
 
-To reset the counter and run time array, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above.
+To reset the counter and run time array, erase the contents of flash memory using `idf.py erase-flash`, then upload the program again as described above.
-

examples/storage/nvs_rw_value/README.md

@@ -78,5 +78,4 @@ Restarting now.
 
 Restart counter will increment on each run.
 
-To reset the counter, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above.
+To reset the counter, erase the contents of flash memory using `idf.py erase-flash`, then upload the program again as described above.
-

examples/storage/nvs_rw_value_cxx/README.md

@@ -72,5 +72,4 @@ Restarting now.
 
 Restart counter will increment on each run.
 
-To reset the counter, erase the contents of flash memory using `idf.py erase_flash`, then upload the program again as described above.
+To reset the counter, erase the contents of flash memory using `idf.py erase-flash`, then upload the program again as described above.
-

examples/storage/spiffs/README.md

@@ -48,4 +48,4 @@ I (19584) example: Read from file: 'Hello World!'
 I (19584) example: SPIFFS unmounted
 ```
 
-To erase the contents of SPIFFS partition, run `idf.py erase_flash` command. Then upload the example again as described above.
+To erase the contents of SPIFFS partition, run `idf.py erase-flash` command. Then upload the example again as described above.

examples/storage/wear_levelling/README.md

@@ -51,4 +51,4 @@ I (920) example: Unmounting FAT filesystem
 I (1000) example: Done
 ```
 
-To erase the contents of wear levelling partition, run `idf.py erase_flash` command. Then upload the example again as described above.
+To erase the contents of wear levelling partition, run `idf.py erase-flash` command. Then upload the example again as described above.

examples/system/efuse/README.md

@@ -157,7 +157,7 @@ I (447) example: Done
 
 ### How to create the new custom table
 
-In the main folder of the example there is a custom eFuse table - `esp_efuse_custom_table.csv`. You can add there some fields and run `idf.py efuse_custom_table`, it will generate all the necessary source files. If all is ok then you will see:
+In the main folder of the example there is a custom eFuse table - `esp_efuse_custom_table.csv`. You can add there some fields and run `idf.py efuse-custom-table`, it will generate all the necessary source files. If all is ok then you will see:
 
 ```
 ...
@@ -181,4 +181,4 @@ idf_component_register(SRCS "efuse_main.c" "esp_efuse_custom_table.c"
                        INCLUDE_DIRS "." "include")
 ```
 
-If you are not sure which eFuse bits are free you can run `idf.py show_efuse_table`. It prints a sorted list of the common and custom tables.
+If you are not sure which eFuse bits are free you can run `idf.py show-efuse-table`. It prints a sorted list of the common and custom tables.

examples/system/efuse/main/esp_efuse_custom_table.csv

@@ -6,7 +6,7 @@
 ##########################################################################
 # *) The value MAX_BLK_LEN depends on CONFIG_EFUSE_MAX_BLK_LEN, will be replaced with "None" - 256. "3/4" - 192. "REPEAT" - 128.
 # !!!!!!!!!!! #
-# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse_common_table"
+# After editing this file, run the command manually "make efuse_common_table" or "idf.py efuse-common-table"
 # this will generate new source files, next rebuild all the sources.
 # !!!!!!!!!!! #
 

examples/system/ota/README.md

@@ -138,7 +138,7 @@ In ``native_ota_example``, ``$PROJECT_PATH/version.txt`` is used to define the a
 
 If you see this error, check that the configured (and actual) flash size is large enough for the partitions in the partition table. The default "two OTA slots" partition table requires at least 4MB flash size. To use OTA with smaller flash sizes, create a custom partition table CSV (for details see [Partition Tables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html)) and configure it in menuconfig.
 
-Make sure to run "idf.py erase_flash" after making changes to the partition table.
+Make sure to run "idf.py erase-flash" after making changes to the partition table.
 
 ### Local https server
 

tools/ci/test_build_system_cmake.sh

@@ -526,7 +526,7 @@ function run_tests()
     fi
 
     print_status "Displays partition table when executing target partition_table"
-    idf.py partition_table | grep -E "# ESP-IDF .+ Partition Table"
+    idf.py partition-table | grep -E "# ESP-IDF .+ Partition Table"
     rm -r build
 
     print_status "Make sure a full build never runs '/usr/bin/env python' or similar"
@@ -863,6 +863,16 @@ endmenu\n" >> ${IDF_PATH}/Kconfig
     idf.py docs --no-browser --language en --version v4.2.1 --target esp32 | grep "https://docs.espressif.com/projects/esp-idf/en/v4.2.1/esp32" || failure "'idf.py docs --no-browser --language en --version v4.2.1 --target esp32' failed"
     idf.py docs --no-browser --language en --version v4.2.1 --target esp32 --starting-page get-started | grep "https://docs.espressif.com/projects/esp-idf/en/v4.2.1/esp32/get-started" || failure "'idf.py docs --no-browser --language en --version v4.2.1 --target esp32 --starting-page get-started' failed"
 
+    print_status "Deprecation warning check"
+    # click warning
+    idf.py post_debug &> tmp.log
+    grep "Warning: Command \"post_debug\" is deprecated and will be removed in v5.0." tmp.log || (failure "Missing deprecation warning with command \"post_debug\"")
+    rm tmp.log
+    # cmake warning
+    idf.py efuse_common_table &> tmp.log
+    grep "Warning: Command efuse_common_table is deprecated and will be removed in the next major release." tmp.log || (failure "Missing deprecation warning with command \"efuse_common_table\"")
+    rm tmp.log
+
     print_status "All tests completed"
     if [ -n "${FAILURES}" ]; then
         echo "Some failures were detected:"

tools/cmake/utilities.cmake

@@ -340,3 +340,16 @@ function(add_subdirectory_if_exists source_dir)
         message(STATUS "Subdirectory '${abs_dir}' does not exist, skipped.")
     endif()
 endfunction()
+
+
+# add_deprecated_target_alias
+#
+# Creates an alias for exising target and shows deprectation warning
+function(add_deprecated_target_alias old_target new_target)
+    add_custom_target(${old_target}
+        COMMAND ${CMAKE_COMMAND} -E echo
+        "Warning: Command \"${old_target}\" is deprecated and will be removed in the next major release. \
+        Please use \"${new_target}\" instead."
+    )
+    add_dependencies(${old_target} ${new_target})
+endfunction()

tools/idf.py

@@ -519,8 +519,8 @@ def init_cli(verbose_output=None):
             else:
                 if 'app' in actions:
                     print_flashing_message('App', 'app')
-                if 'partition_table' in actions:
+                if 'partition-table' in actions:
-                    print_flashing_message('Partition Table', 'partition_table')
+                    print_flashing_message('Partition Table', 'partition-table')
                 if 'bootloader' in actions:
                     print_flashing_message('Bootloader', 'bootloader')
 

tools/idf_py_actions/core_ext.py

@@ -399,40 +399,80 @@ def action_extensions(base_actions, project_path):
                 'order_dependencies': ['clean', 'fullclean', 'reconfigure'],
                 'options': global_options,
             },
+            'efuse-common-table': {
+                'callback': build_target,
+                'help': 'Generate C-source for IDF\'s eFuse fields. Deprecated alias: "efuse_common_table".',
+                'order_dependencies': ['reconfigure'],
+                'options': global_options,
+            },
             'efuse_common_table': {
                 'callback': build_target,
+                'hidden': True,
                 'help': "Generate C-source for IDF's eFuse fields.",
                 'order_dependencies': ['reconfigure'],
                 'options': global_options,
             },
+            'efuse-custom-table': {
+                'callback': build_target,
+                'help': 'Generate C-source for user\'s eFuse fields. Deprecated alias: "efuse_custom_table".',
+                'order_dependencies': ['reconfigure'],
+                'options': global_options,
+            },
             'efuse_custom_table': {
                 'callback': build_target,
-                'help': "Generate C-source for user's eFuse fields.",
+                'hidden': True,
+                'help': 'Generate C-source for user\'s eFuse fields.',
+                'order_dependencies': ['reconfigure'],
+                'options': global_options,
+            },
+            'show-efuse-table': {
+                'callback': build_target,
+                'help': 'Print eFuse table. Deprecated alias: "show_efuse_table".',
                 'order_dependencies': ['reconfigure'],
                 'options': global_options,
             },
             'show_efuse_table': {
                 'callback': build_target,
+                'hidden': True,
                 'help': 'Print eFuse table.',
                 'order_dependencies': ['reconfigure'],
                 'options': global_options,
             },
+            'partition-table': {
+                'callback': build_target,
+                'help': 'Build only partition table. Deprecated alias: "parititon_table".',
+                'order_dependencies': ['reconfigure'],
+                'options': global_options,
+            },
             'partition_table': {
                 'callback': build_target,
+                'hidden': True,
                 'help': 'Build only partition table.',
                 'order_dependencies': ['reconfigure'],
                 'options': global_options,
             },
             'erase_otadata': {
                 'callback': build_target,
+                'hidden': True,
                 'help': 'Erase otadata partition.',
                 'options': global_options,
             },
+            'erase-otadata': {
+                'callback': build_target,
+                'help': 'Erase otadata partition. Deprecated alias: "erase_otadata".',
+                'options': global_options,
+            },
             'read_otadata': {
                 'callback': build_target,
+                'hidden': True,
                 'help': 'Read otadata partition.',
                 'options': global_options,
             },
+            'read-otadata': {
+                'callback': build_target,
+                'help': 'Read otadata partition. Deprecated alias: "read_otadata".',
+                'options': global_options,
+            },
             'build-system-targets': {
                 'callback': list_build_system_targets,
                 'help': 'Print list of build system targets.',

tools/idf_py_actions/debug_ext.py

@@ -367,8 +367,26 @@ def action_extensions(base_actions, project_path):
                 'options': [gdbinit, fail_if_openocd_failed],
                 'order_dependencies': ['all', 'flash'],
             },
+            'post-debug': {
+                'callback': post_debug,
+                'help': 'Utility target to read the output of async debug action and stop them.',
+                'options': [
+                    {
+                        'names': ['--block', '--block'],
+                        'help':
+                        ('Set to 1 for blocking the console on the outputs of async debug actions\n'),
+                        'default': 0,
+                    },
+                ],
+                'order_dependencies': [],
+            },
             'post_debug': {
                 'callback': post_debug,
+                'deprecated': {
+                    'removed': 'v5.0',
+                    'message': 'Please use "post-debug" instead.',
+                },
+                'hidden': True,
                 'help': 'Utility target to read the output of async debug action and stop them.',
                 'options': [
                     {

tools/idf_py_actions/serial_ext.py

@@ -177,10 +177,20 @@ def action_extensions(base_actions, project_path):
                 'callback': flash,
                 'help': 'Flash the project.',
                 'options': global_options + [baud_rate, port],
-                'order_dependencies': ['all', 'erase_flash'],
+                'order_dependencies': ['all', 'erase-flash'],
+            },
+            'erase-flash': {
+                'callback': erase_flash,
+                'help': 'Erase entire flash chip. Deprecated alias: "erase_flash"',
+                'options': [baud_rate, port],
             },
             'erase_flash': {
                 'callback': erase_flash,
+                'deprecated': {
+                    'removed': 'v5.0',
+                    'message': 'Please use "erase-flash" instead.',
+                },
+                'hidden': True,
                 'help': 'Erase entire flash chip.',
                 'options': [baud_rate, port],
             },
@@ -235,39 +245,46 @@ def action_extensions(base_actions, project_path):
                 'order_dependencies': [
                     'flash',
                     'encrypted-flash',
-                    'partition_table-flash',
+                    'partition-table-flash',
                     'bootloader-flash',
                     'app-flash',
                     'encrypted-app-flash',
                 ],
             },
+            'partition-table-flash': {
+                'callback': flash,
+                'help': 'Flash partition table only. Deprecated alias: "partition_table-flash".',
+                'options': [baud_rate, port],
+                'order_dependencies': ['partition-table', 'erase-flash'],
+            },
             'partition_table-flash': {
                 'callback': flash,
+                'hidden': True,
                 'help': 'Flash partition table only.',
                 'options': [baud_rate, port],
-                'order_dependencies': ['partition_table', 'erase_flash'],
+                'order_dependencies': ['partition-table', 'erase-flash'],
             },
             'bootloader-flash': {
                 'callback': flash,
                 'help': 'Flash bootloader only.',
                 'options': [baud_rate, port],
-                'order_dependencies': ['bootloader', 'erase_flash'],
+                'order_dependencies': ['bootloader', 'erase-flash'],
             },
             'app-flash': {
                 'callback': flash,
                 'help': 'Flash the app only.',
                 'options': [baud_rate, port],
-                'order_dependencies': ['app', 'erase_flash'],
+                'order_dependencies': ['app', 'erase-flash'],
             },
             'encrypted-app-flash': {
                 'callback': flash,
                 'help': 'Flash the encrypted app only.',
-                'order_dependencies': ['app', 'erase_flash'],
+                'order_dependencies': ['app', 'erase-flash'],
             },
             'encrypted-flash': {
                 'callback': flash,
                 'help': 'Flash the encrypted project.',
-                'order_dependencies': ['all', 'erase_flash'],
+                'order_dependencies': ['all', 'erase-flash'],
             },
         },
     }