diff --git a/docs/en/api-guides/tools/idf-py.rst b/docs/en/api-guides/tools/idf-py.rst index 850ed40e19..917286147f 100644 --- a/docs/en/api-guides/tools/idf-py.rst +++ b/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`` diff --git a/docs/en/migration-guides/release-6.x/6.0/tools.rst b/docs/en/migration-guides/release-6.x/6.0/tools.rst index 83ae179f71..25ae808557 100644 --- a/docs/en/migration-guides/release-6.x/6.0/tools.rst +++ b/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 `_. 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} + } + } + ] + } + diff --git a/docs/zh_CN/api-guides/tools/idf-py.rst b/docs/zh_CN/api-guides/tools/idf-py.rst index 0cb3973f2d..1c326c490e 100644 --- a/docs/zh_CN/api-guides/tools/idf-py.rst +++ b/docs/zh_CN/api-guides/tools/idf-py.rst @@ -216,7 +216,7 @@ uf2 二进制文件也可以通过 :ref:`idf.py uf2 ` 生 选项 ^^^^^^^ -- ``--format`` 指定输出格式，可输出 ``text``、``csv``、 ``json`` 格式，默认格式为 ``text``。 +- ``--format`` 指定输出格式，可输出 ``text``、``csv``、 ``json2``、``tree``、``raw`` 格式，默认格式为 ``text``。 - ``--output-file`` 可选参数，可以指定命令输出文件的文件名，而非标准输出。 重新配置工程：``reconfigure`` diff --git a/tools/cmake/run_size_tool.cmake b/tools/cmake/run_size_tool.cmake index df8108b57f..0be2d369c4 100644 --- a/tools/cmake/run_size_tool.cmake +++ b/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 - list(APPEND IDF_SIZE_CMD "--format=json") + # honor the legacy OUTPUT_JSON variable, if set (use json2 format as json is no longer supported) + list(APPEND IDF_SIZE_CMD "--format=json2") endif() elseif(DEFINED ENV{SIZE_OUTPUT_FORMAT}) # specific format was requested diff --git a/tools/idf_py_actions/core_ext.py b/tools/idf_py_actions/core_ext.py index 5eb66402fe..5762e0d213 100644 --- a/tools/idf_py_actions/core_ext.py +++ b/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, - ctx: Context, - args: PropertyDict, - output_format: str, - output_file: str, - diff_map_file: str, - legacy: bool, + target_name: str, ctx: Context, args: PropertyDict, output_format: str, output_file: str, diff_map_file: str ) -> 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': - try: - import esp_idf_size.ng # noqa: F401 - 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') - + # Enforce NG mode for esp-idf-size v 1.x. After v 2.x is fully incorporated, 'ESP_IDF_SIZE_NG' can be removed. + env['ESP_IDF_SIZE_NG'] = '1' + env['ESP_IDF_SIZE_FORCE_TERMINAL'] = '1' 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']), - 'help': 'Specify output format: text (same as "default"), csv, json, json2, tree or raw.', + 'type': click.Choice(['default', 'text', 'csv', 'json2', 'tree', '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': ( diff --git a/tools/idf_size.py b/tools/idf_size.py index a3cb75c7da..743ab98525 100755 --- a/tools/idf_size.py +++ b/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 - # legacy version is requested or if old json format is specified. - # 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') + try: + import esp_idf_size # noqa: F401 - # The sys.argv is parsed with "exit_on_error", but the argparse.ArgumentError - # exception should never occur, because unknown args should be put into - # the rest variable, since the parse_known_args() method is used. - args, rest = parser.parse_known_args() + # Enforce NG mode for esp-idf-size v 1.x. After v 2.x is fully incorporated, 'ESP_IDF_SIZE_NG' can be removed. + os.environ['ESP_IDF_SIZE_NG'] = '1' + except ImportError: + 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': - # 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) + sys.exit(subprocess.run([sys.executable, '-m', 'esp_idf_size'] + sys.argv[1:]).returncode)