revert(tools): Removed --legacy option for esp-idf-size

docs/en/api-guides/tools/idf-py.rst

@@ -216,7 +216,7 @@ This command prints size information per source file in the project.
 Options
 ^^^^^^^
 
-- ``--format`` specifies the output format with available options: ``text``, ``csv``, ``json``, default being ``text``.
+- ``--format`` specifies the output format with available options: ``text``, ``csv``, ``json2``, ``tree``, ``raw``, default being ``text``.
 - ``--output-file`` optionally specifies the name of the file to print the command output to instead of the standard output.
 
 Reconfigure the Project: ``reconfigure``

docs/en/migration-guides/release-6.x/6.0/tools.rst

@@ -67,3 +67,35 @@ Catch
 -----
 
 The header-only copy of Catch2 unit testing library previously located in tools/catch directory has been removed. To continue using Catch2 in your project, migrate to Catch2 3.x, available from the `ESP component registry <https://components.espressif.com/components/espressif/catch2>`_. For an example of migrating from Catch2 2.x to Catch2 3.x, see commit 79a2c15477dc327550ff46a64ee0f8b4679cc417.
+
+Dropped `idf.py size --legacy` option
+-------------------------------------
+
+The ``--legacy`` argument for ``idf.py size`` has been removed, as the legacy implementation is no longer supported. The ``ESP_IDF_SIZE_LEGACY`` environment variable has also no longer any effect. To continue using the legacy option, use ESP-IDF version 5.5 or lower. For ESP-IDF v6.0 and later, simply replace ``idf.py size --legacy`` with ``idf.py size``. If you encounter esp-idf-size version problems, please run the install script to update to the correct version.
+
+Changed `idf.py size --format json` to `--format json2`
+-------------------------------------------------------
+
+The ``--format json`` option has been replaced with ``--format json2``. The ``json2`` format provides better structure with explicit ``total``, ``used``, and ``free`` fields for each memory region, and detailed breakdown in the ``parts`` section. To migrate, replace ``idf.py size --format json`` with ``idf.py size --format json2``.
+
+- **Old format (json)**: Flat structure with direct memory type fields like ``"dram_data": 9192, "iram_text": 43295``
+- **New format (json2)**: Hierarchical structure with a ``layout`` array containing memory regions:
+
+    .. code-block:: json
+
+        {
+            "version": "1.1",
+            "layout": [
+                {
+                    "name": "DRAM",
+                    "total": 180736,
+                    "used": 11344,
+                    "free": 169392,
+                    "parts": {
+                        ".data": {"size": 9192},
+                        ".bss": {"size": 2152}
+                    }
+                }
+            ]
+        }
+

docs/zh_CN/api-guides/tools/idf-py.rst

@@ -216,7 +216,7 @@ uf2 二进制文件也可以通过 :ref:`idf.py uf2 <generate-uf2-binary>` 生
 选项
 ^^^^^^^
 
-- ``--format`` 指定输出格式，可输出 ``text``、``csv``、 ``json`` 格式，默认格式为 ``text``。
+- ``--format`` 指定输出格式，可输出 ``text``、``csv``、 ``json2``、``tree``、``raw`` 格式，默认格式为 ``text``。
 - ``--output-file`` 可选参数，可以指定命令输出文件的文件名，而非标准输出。
 
 重新配置工程：``reconfigure``

tools/cmake/run_size_tool.cmake

@@ -16,8 +16,8 @@ if(NOT DEFINED ENV{SIZE_OUTPUT_FORMAT} OR "$ENV{SIZE_OUTPUT_FORMAT}" STREQUAL "d
     # Format not passed to "idf.py size" explicitly, or this target was invoked
     # from make/ninja directly (without idf.py)
     if(DEFINED OUTPUT_JSON AND OUTPUT_JSON)
-        # honor the legacy OUTPUT_JSON variable, if set
+        # honor the legacy OUTPUT_JSON variable, if set (use json2 format as json is no longer supported)
-        list(APPEND IDF_SIZE_CMD "--format=json")
+        list(APPEND IDF_SIZE_CMD "--format=json2")
     endif()
 elseif(DEFINED ENV{SIZE_OUTPUT_FORMAT})
     # specific format was requested

tools/idf_py_actions/core_ext.py

@@ -31,7 +31,6 @@ from idf_py_actions.tools import generate_hints
 from idf_py_actions.tools import get_target
 from idf_py_actions.tools import idf_version
 from idf_py_actions.tools import merge_action_lists
-from idf_py_actions.tools import print_warning
 from idf_py_actions.tools import run_target
 from idf_py_actions.tools import yellow_print
 
@@ -48,13 +47,7 @@ def action_extensions(base_actions: dict, project_path: str) -> Any:
         run_target(target_name, args, force_progression=GENERATORS[args.generator].get('force_progression', False))
 
     def size_target(
-        target_name: str,
+        target_name: str, ctx: Context, args: PropertyDict, output_format: str, output_file: str, diff_map_file: str
-        ctx: Context,
-        args: PropertyDict,
-        output_format: str,
-        output_file: str,
-        diff_map_file: str,
-        legacy: bool,
     ) -> None:
         """
         Builds the app and then executes a size-related target passed in 'target_name'.
@@ -68,27 +61,9 @@ def action_extensions(base_actions: dict, project_path: str) -> Any:
 
         env: dict[str, Any] = {}
 
-        if not legacy and output_format != 'json':
+        # Enforce NG mode for esp-idf-size v 1.x. After v 2.x is fully incorporated, 'ESP_IDF_SIZE_NG' can be removed.
-            try:
+        env['ESP_IDF_SIZE_NG'] = '1'
-                import esp_idf_size.ng  # noqa: F401
+        env['ESP_IDF_SIZE_FORCE_TERMINAL'] = '1'
-            except ImportError:
-                print_warning('WARNING: refactored esp-idf-size not installed, using legacy mode')
-                legacy = True
-            else:
-                # Legacy mode is used only when explicitly requested with --legacy option
-                # or when "--format json" option is specified. Here we enable the
-                # esp-idf-size refactored version with ESP_IDF_SIZE_NG env. variable.
-                env['ESP_IDF_SIZE_NG'] = '1'
-                # ESP_IDF_SIZE_FORCE_TERMINAL is set to force terminal control codes even
-                # if stdout is not attached to terminal. This is set to pass color codes
-                # from esp-idf-size to idf.py.
-                env['ESP_IDF_SIZE_FORCE_TERMINAL'] = '1'
-
-        if legacy and output_format in ['json2', 'raw', 'tree']:
-            # These formats are supported in new version only.
-            # We would get error from the esp-idf-size anyway, so print error early.
-            raise FatalError(f'Legacy esp-idf-size does not support {output_format} format')
-
         env['SIZE_OUTPUT_FORMAT'] = output_format
         if output_file:
             env['SIZE_OUTPUT_FILE'] = os.path.abspath(output_file)
@@ -441,16 +416,10 @@ def action_extensions(base_actions: dict, project_path: str) -> Any:
     size_options = [
         {
             'names': ['--format', 'output_format'],
-            'type': click.Choice(['default', 'text', 'csv', 'json', 'json2', 'tree', 'raw']),
+            'type': click.Choice(['default', 'text', 'csv', 'json2', 'tree', 'raw']),
-            'help': 'Specify output format: text (same as "default"), csv, json, json2, tree or raw.',
+            'help': 'Specify output format: text (same as "default"), csv, json2, tree or raw.',
             'default': 'default',
         },
-        {
-            'names': ['--legacy', '-l'],
-            'is_flag': True,
-            'default': os.environ.get('ESP_IDF_SIZE_LEGACY', '0') == '1',
-            'help': 'Use legacy esp-idf-size version',
-        },
         {
             'names': ['--diff', 'diff_map_file'],
             'help': (

tools/idf_size.py

@@ -1,49 +1,21 @@
 #!/usr/bin/env python
 #
-# SPDX-FileCopyrightText: 2017-2024 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2017-2025 Espressif Systems (Shanghai) CO LTD
 #
 # SPDX-License-Identifier: Apache-2.0
 #
-import argparse
 import os
 import subprocess
 import sys
 
 if __name__ == '__main__':
-    # Here the argparse is used only to "peek" into arguments if
+    try:
-    # legacy version is requested or if old json format is specified.
+        import esp_idf_size  # noqa: F401
-    # In these two cases the esp_idf_size legacy version is spawned.
-    parser = argparse.ArgumentParser(add_help=False)
-    # Make the --format arg optional, so this argparse instance does not
-    # fail with an error and the proper underlying help is displayed.
-    # Note that exit_on_error is supported from python3.9, so this is
-    # a workaround how to make sure that the args parsing doesn't fail here if idf_size.py
-    # is invoked e.g. without specifying the format, like "idf_size.py --format".
-    parser.add_argument('--format', nargs='?')
-    parser.add_argument('-l', '--legacy', action='store_true', default=os.environ.get('ESP_IDF_SIZE_LEGACY', '0') == '1')
 
-    # The sys.argv is parsed with "exit_on_error", but the argparse.ArgumentError
+        # Enforce NG mode for esp-idf-size v 1.x. After v 2.x is fully incorporated, 'ESP_IDF_SIZE_NG' can be removed.
-    # exception should never occur, because unknown args should be put into
+        os.environ['ESP_IDF_SIZE_NG'] = '1'
-    # the rest variable, since the parse_known_args() method is used.
+    except ImportError:
-    args, rest = parser.parse_known_args()
+        print('WARNING: esp-idf-size not installed, please run the install script to install it', file=sys.stderr)
+        raise SystemExit(1)
 
-    if not args.legacy and args.format != 'json':
+    sys.exit(subprocess.run([sys.executable, '-m', 'esp_idf_size'] + sys.argv[1:]).returncode)
-        # By default start the refactored version, unless legacy version is explicitly requested with
-        # -l/--legacy option or if old json format is specified.
-        try:
-            import esp_idf_size.ng  # noqa: F401
-        except ImportError:
-            print('warning: refactored esp-idf-size not installed, using legacy mode', file=sys.stderr)
-            args.legacy = True
-        else:
-            os.environ['ESP_IDF_SIZE_NG'] = '1'
-            if not rest or '-h' in rest or '--help' in rest:
-                print(('Note: legacy esp_idf_size version can be invoked by specifying the -l/--legacy '
-                       'option or by setting the ESP_IDF_SIZE_LEGACY environment variable. Additionally, the '
-                       'legacy version is automatically employed when the JSON format is specified for '
-                       'compatibility with previous versions.'))
-
-    if args.format is not None:
-        rest = ['--format', args.format] + rest
-
-    sys.exit(subprocess.run([sys.executable, '-m', 'esp_idf_size'] + rest).returncode)