From 47fc76129998a2e8684823e3f3179f9a5f3eb504 Mon Sep 17 00:00:00 2001 From: Fu Hanxi Date: Tue, 9 Nov 2021 15:30:09 +0800 Subject: [PATCH 1/2] feat(idf.py): add `idf.py clang-check` and `idf.py clang-html-report` --- tools/idf.py | 8 ++++++++ tools/idf_py_actions/core_ext.py | 4 ++++ 2 files changed, 12 insertions(+) diff --git a/tools/idf.py b/tools/idf.py index 3e3986ac5e..74704466e7 100755 --- a/tools/idf.py +++ b/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)) diff --git a/tools/idf_py_actions/core_ext.py b/tools/idf_py_actions/core_ext.py index 53130cbd6d..b67c2e82c4 100644 --- a/tools/idf_py_actions/core_ext.py +++ b/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)) From a081a67f8e6858a129070df22d7b3da5b0678283 Mon Sep 17 00:00:00 2001 From: Fu Hanxi Date: Mon, 15 Nov 2021 14:38:15 +0800 Subject: [PATCH 2/2] docs(idf.py): add IDF Clang Tidy chapter --- docs/en/api-guides/tools/idf-clang-tidy.rst | 57 +++++++++++++++++++ docs/en/api-guides/tools/index.rst | 1 + .../zh_CN/api-guides/tools/idf-clang-tidy.rst | 1 + docs/zh_CN/api-guides/tools/index.rst | 1 + 4 files changed, 60 insertions(+) create mode 100644 docs/en/api-guides/tools/idf-clang-tidy.rst create mode 100644 docs/zh_CN/api-guides/tools/idf-clang-tidy.rst diff --git a/docs/en/api-guides/tools/idf-clang-tidy.rst b/docs/en/api-guides/tools/idf-clang-tidy.rst new file mode 100644 index 0000000000..254a8c1d10 --- /dev/null +++ b/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 `_ 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 `_ 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 ``/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 ``/html_report`` according to the ``warnings.txt``. Please open the ``/html_report/index.html`` in your browser to check the report. + +Bug Report +========== + +This tool is hosted in `espressif/clang-tidy-runner `_. If you faced any bugs or have any feature request, please report them via `github issues `_. diff --git a/docs/en/api-guides/tools/index.rst b/docs/en/api-guides/tools/index.rst index 49b85291c3..8e2aed3fec 100644 --- a/docs/en/api-guides/tools/index.rst +++ b/docs/en/api-guides/tools/index.rst @@ -9,3 +9,4 @@ Tools IDF Docker image IDF Windows Installer IDF Component Manager + IDF Clang Tidy diff --git a/docs/zh_CN/api-guides/tools/idf-clang-tidy.rst b/docs/zh_CN/api-guides/tools/idf-clang-tidy.rst new file mode 100644 index 0000000000..2615fa000c --- /dev/null +++ b/docs/zh_CN/api-guides/tools/idf-clang-tidy.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-guides/tools/idf-clang-tidy.rst diff --git a/docs/zh_CN/api-guides/tools/index.rst b/docs/zh_CN/api-guides/tools/index.rst index 41438ae874..67dad3f038 100644 --- a/docs/zh_CN/api-guides/tools/index.rst +++ b/docs/zh_CN/api-guides/tools/index.rst @@ -9,3 +9,4 @@ IDF Docker image IDF Windows Installer IDF Component Manager + IDF Clang Tidy