Merge branch 'feature/idf_py_clang_tidy_check' into 'master'

feat(idf.py): add `idf.py clang-check` and `idf.py clang-html-report`

Closes IDF-1909

See merge request espressif/esp-idf!15848

docs/en/api-guides/tools/idf-clang-tidy.rst

@@ -0,0 +1,57 @@
+**************
+IDF Clang Tidy
+**************
+
+The IDF Clang Tidy is a tool that uses `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`_ to run static analysis on your current app.
+
+.. warning::
+
+   This functionality and the toolchain it relies on are still under development. There may be breaking changes before a final release.
+
+.. only:: esp32c3 or esp32h2
+
+   .. warning::
+    
+      This tool does not support RISC-V based chips yet. For now, we don't provide clang based toolchain for RISC-V.
+
+Prerequisites
+=============
+
+If you have never run this tool before, take the following steps to get this tool prepared.
+
+#. Run the export scripts (``export.sh`` / ``export.bat`` / ... ) to set up the environment variables.
+#. Run ``pip install --upgrade pyclang`` to install this plugin. The extra commands would be activated in ``idf.py`` automatically. 
+#. Run ``idf_tools.py install xtensa-clang`` to install the clang-tidy required binaries
+
+   .. note::
+
+      This toolchain is still under development. After the final release, you don't have to install them manually.
+
+#. Get file from the `llvm repository <https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/tool/run-clang-tidy.py>`_  and add the folder of this script to the ``$PATH``. Or you could pass an optional argument ``--run-clang-tidy-py`` later when you call ``idf.py clang-check``.
+
+   .. note::
+
+      This file would be bundled in future toolchain releases. This is a temporary workaround.
+   
+#. Run the export scripts (``export.sh`` / ``export.bat`` / ... ) again to refresh the environment variables.
+
+Extra Commands
+==============
+
+``clang-check``
+---------------
+
+Run ``idf.py clang-check`` to re-generate the compilation database and run ``clang-tidy`` under your current project folder. The output would be written to ``<project_dir>/warnings.txt``.
+
+Run ``idf.py clang-check --help`` to see the full documentation.
+
+``clang-html-report``
+---------------------
+
+#. Run ``pip install codereport`` to install the additional dependency.
+#. Run ``idf.py clang-html-report`` to generate an HTML report in folder ``<project_dir>/html_report`` according to the ``warnings.txt``. Please open the ``<project_dir>/html_report/index.html`` in your browser to check the report.
+
+Bug Report
+==========
+
+This tool is hosted in `espressif/clang-tidy-runner <https://github.com/espressif/clang-tidy-runner>`_. If you faced any bugs or have any feature request, please report them via `github issues <https://github.com/espressif/clang-tidy-runner/issues>`_.

docs/en/api-guides/tools/index.rst

@@ -9,3 +9,4 @@ Tools
    IDF Docker image <idf-docker-image>
    IDF Windows Installer <idf-windows-installer>
    IDF Component Manager <idf-component-manager>
+   IDF Clang Tidy <idf-clang-tidy>

docs/zh_CN/api-guides/tools/idf-clang-tidy.rst

@@ -0,0 +1 @@
+.. include:: ../../../en/api-guides/tools/idf-clang-tidy.rst

docs/zh_CN/api-guides/tools/index.rst

@@ -9,3 +9,4 @@
    IDF Docker image <idf-docker-image>
    IDF Windows Installer <idf-windows-installer>
    IDF Component Manager <idf-component-manager>
+   IDF Clang Tidy <idf-clang-tidy>

tools/idf.py

@@ -687,6 +687,14 @@ def init_cli(verbose_output=None):
         except ImportError:
             pass
 
+    # Optional load `pyclang` for additional clang-tidy related functionalities
+    try:
+        from pyclang import idf_extension
+
+        extensions.append(('idf_clang_tidy_ext', idf_extension))
+    except ImportError:
+        pass
+
     for name, extension in extensions:
         try:
             all_actions = merge_action_lists(all_actions, extension.action_extensions(all_actions, project_dir))

tools/idf_py_actions/core_ext.py

@@ -69,6 +69,10 @@ def action_extensions(base_actions, project_path):
             subprocess.check_output(GENERATORS[args.generator]['dry_run'] + [target_name], cwd=args.build_dir)
 
         except Exception:
+            if target_name in ['clang-check', 'clang-html-report']:
+                raise FatalError('command "{}" requires an additional plugin "pyclang". '
+                                 'Please install it via "pip install --upgrade pyclang"'.format(target_name))
+
             raise FatalError(
                 'command "%s" is not known to idf.py and is not a %s target' % (target_name, args.generator))