Merge branch 'feature/idfpy_depecated_commands' into 'master'

tools: Remove deprecated idf.py commands

Closes IDF-3869

See merge request espressif/esp-idf!17525

docs/en/migration-guides/tools.rst

@@ -5,3 +5,33 @@ IDF Monitor
 -----------
 
 IDF Monitor follows the custom console baud-rate (:ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`) by default instead of 115200. Setting a custom baud rate is not supported from menuconfig anymore. A custom baud-rate can be specified from command line with the ``idf.py monitor -b <baud>`` command or through setting environment variables. Please note that the baud-rate argument has been renamed from ``-B`` to ``-b`` in order to be consistent with the global baud-rate ``idf.py -b <baud>``. Run ``idf.py monitor --help`` for more information.
+
+Deprecated commands
+-------------------
+
+``idf.py`` sub-commands and ``cmake`` targets are unified to contain ``-`` instead of ``_``. The following changes have been made. Deprecated sub-commands and targets produce a warning. It is advised to migrate to the new ones.
+
+.. list-table:: Target and sub-command deprecation
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Old name
+     - New name
+   * - efuse_common_table
+     - efuse-common-table
+   * - efuse_custom_table
+     - efuse-custom-table
+   * - erase_flash
+     - erase-flash
+   * - partition_table
+     - partition-table
+   * - partition_table-flash
+     - partition-table-flash
+   * - post_debug
+     - post-debug
+   * - show_efuse_table
+     - show-efuse-table
+   * - erase_otadata
+     - erase-otadata
+   * - read_otadata
+     - read-otadata

tools/ci/test_build_system_cmake.sh

@@ -958,11 +958,11 @@ endmenu\n" >> ${IDF_PATH}/Kconfig
     cd ${TESTDIR}/template
     # 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\""
+    grep "Error: Command \"post_debug\" is deprecated since v4.4 and was 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\""
+    grep "Have you wanted to run \"efuse-common-table\" instead?" tmp.log || failure "Missing deprecation warning with command \"efuse_common_table\""
     rm tmp.log
 
     print_status "Save-defconfig checks"

tools/cmake/utilities.cmake

@@ -358,9 +358,9 @@ endfunction()
 # 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
+     # `COMMAND` is important to print the `COMMENT` message at the end of the target action.
-        "Warning: Command \"${old_target}\" is deprecated and will be removed in the next major release. \
+        COMMAND ${CMAKE_COMMAND} -E echo ""
-        Please use \"${new_target}\" instead."
+        COMMENT "Warning: command \"${old_target}\" is deprecated. Have you wanted to run \"${new_target}\" instead?"
     )
     add_dependencies(${old_target} ${new_target})
 endfunction()

tools/idf_py_actions/core_ext.py

@@ -405,52 +405,24 @@ def action_extensions(base_actions, project_path):
             },
             'efuse-common-table': {
                 'callback': build_target,
-                'help': 'Generate C-source for IDF\'s eFuse fields. Deprecated alias: "efuse_common_table".',
+                'help': 'Generate C-source for IDF\'s eFuse fields.',
-                '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,
-                '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,

tools/idf_py_actions/debug_ext.py

@@ -389,8 +389,10 @@ def action_extensions(base_actions, project_path):
             'post_debug': {
                 'callback': post_debug,
                 'deprecated': {
+                    'since': 'v4.4',
                     'removed': 'v5.0',
-                    'message': 'Please use "post-debug" instead.',
+                    'exit_with_error': True,
+                    'message': 'Have you wanted to run "post-debug" instead?',
                 },
                 'hidden': True,
                 'help': 'Utility target to read the output of async debug action and stop them.',

tools/idf_py_actions/serial_ext.py

@@ -211,14 +211,15 @@ def action_extensions(base_actions, project_path):
             },
             'erase-flash': {
                 'callback': erase_flash,
-                'help': 'Erase entire flash chip. Deprecated alias: "erase_flash"',
+                'help': 'Erase entire flash chip.',
                 'options': BAUD_AND_PORT,
             },
             'erase_flash': {
                 'callback': erase_flash,
                 'deprecated': {
-                    'removed': 'v5.0',
+                    'since': 'v4.4',
-                    'message': 'Please use "erase-flash" instead.',
+                    'removed': 'next major release',
+                    'message': 'Have you wanted to run "erase-flash" instead?',
                 },
                 'hidden': True,
                 'help': 'Erase entire flash chip.',
@@ -283,13 +284,6 @@ def action_extensions(base_actions, project_path):
             },
             'partition-table-flash': {
                 'callback': flash,
-                'help': 'Flash partition table only. Deprecated alias: "partition_table-flash".',
-                'options': BAUD_AND_PORT,
-                'order_dependencies': ['partition-table', 'erase-flash'],
-            },
-            'partition_table-flash': {
-                'callback': flash,
-                'hidden': True,
                 'help': 'Flash partition table only.',
                 'options': BAUD_AND_PORT,
                 'order_dependencies': ['partition-table', 'erase-flash'],
@@ -316,26 +310,14 @@ def action_extensions(base_actions, project_path):
                 'help': 'Flash the encrypted project.',
                 'order_dependencies': ['all', 'erase-flash'],
             },
-            'erase_otadata': {
-                'callback': ota_targets,
-                'hidden': True,
-                'help': 'Erase otadata partition.',
-                'options': global_options + BAUD_AND_PORT,
-            },
             'erase-otadata': {
                 'callback': ota_targets,
-                'help': 'Erase otadata partition. Deprecated alias: "erase_otadata".',
+                'help': 'Erase otadata partition.',
-                'options': global_options + BAUD_AND_PORT,
-            },
-            'read_otadata': {
-                'callback': ota_targets,
-                'hidden': True,
-                'help': 'Read otadata partition.',
                 'options': global_options + BAUD_AND_PORT,
             },
             'read-otadata': {
                 'callback': ota_targets,
-                'help': 'Read otadata partition. Deprecated alias: "read_otadata".',
+                'help': 'Read otadata partition.',
                 'options': global_options + BAUD_AND_PORT,
             },
         },