Merge branch 'tools/idf_py_size_output_file_opt' into 'master'

tools: Add --output-file argument to idf.py size commands

Closes IDF-5954

See merge request espressif/esp-idf!20354

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

@@ -191,7 +191,7 @@ Will print app size information including occupied RAM and FLASH and section siz
 
 .. code-block:: bash
 
-  idf.py size
+  idf.py size-components
 
 Similarly, this will print the same information for each component used in the project.
 
@@ -201,7 +201,11 @@ Similarly, this will print the same information for each component used in the p
 
 Will print size information per source file in the project.
 
-If you define the ``OUTPUT_FORMAT`` variable as ``csv`` or ``json`` when running CMake (or ``idf.py``), the output will be formatted in the specified format and not as human readable text. See ``idf.py-size`` for more information.
+Options
+^^^^^^^
+
+- ``--format`` specifies the output format with available options: ``text``, ``csv``, ``json``, 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
 ------------------------------------

tools/cmake/run_size_tool.cmake

@@ -24,6 +24,10 @@ elseif(DEFINED ENV{SIZE_OUTPUT_FORMAT})
     list(APPEND IDF_SIZE_CMD "--format=$ENV{SIZE_OUTPUT_FORMAT}")
 endif()
 
+if(DEFINED ENV{SIZE_OUTPUT_FILE})
+    list(APPEND IDF_SIZE_CMD "--output-file=$ENV{SIZE_OUTPUT_FILE}")
+endif()
+
 if(DEFINED IDF_SIZE_MODE)
     list(APPEND IDF_SIZE_CMD ${IDF_SIZE_MODE})
 endif()

tools/idf_py_actions/core_ext.py

@@ -33,7 +33,7 @@ def action_extensions(base_actions: Dict, project_path: str) -> Any:
         ensure_build_directory(args, ctx.info_name)
         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) -> None:
+    def size_target(target_name: str, ctx: Context, args: PropertyDict, output_format: str, output_file: str) -> None:
         """
         Builds the app and then executes a size-related target passed in 'target_name'.
         `tool_error_handler` handler is used to suppress errors during the build,
@@ -45,6 +45,9 @@ def action_extensions(base_actions: Dict, project_path: str) -> Any:
                 yellow_print(hint)
 
         os.environ['SIZE_OUTPUT_FORMAT'] = output_format
+        if output_file:
+            os.environ['SIZE_OUTPUT_FILE'] = os.path.abspath(output_file)
+
         ensure_build_directory(args, ctx.info_name)
         run_target('all', args, force_progression=GENERATORS[args.generator].get('force_progression', False),
                    custom_error_handler=tool_error_handler)
@@ -343,7 +346,9 @@ def action_extensions(base_actions: Dict, project_path: str) -> Any:
     size_options = [{'names': ['--format', 'output_format'],
                      'type': click.Choice(['default', 'text', 'csv', 'json']),
                      'help': 'Specify output format: text (same as "default"), csv or json.',
-                     'default': 'default'}]
+                     'default': 'default'},
+                    {'names': ['--output-file', 'output_file'],
+                     'help': 'Print output to the specified file instead of to the standard output'}]
 
     build_actions = {
         'actions': {