From 96aeb4408c14d88b94cc9c1f2d113a948d286bb4 Mon Sep 17 00:00:00 2001 From: mikee47 Date: Mon, 22 Apr 2024 20:01:13 +0100 Subject: [PATCH] Update documentation --- .../information/develop/clang-tools.rst | 89 ++++++++++++++++--- 1 file changed, 75 insertions(+), 14 deletions(-) diff --git a/docs/source/information/develop/clang-tools.rst b/docs/source/information/develop/clang-tools.rst index aba5e45913..d8e0b70ac7 100644 --- a/docs/source/information/develop/clang-tools.rst +++ b/docs/source/information/develop/clang-tools.rst @@ -5,10 +5,10 @@ Clang Tools is a tool that implements automatic source code formatting. It can be used to automatically enforce the layout rules for Sming. -`clang-tidy `__ -is a C++ “linter” tool to assist with diagnosing and fixing typical programming errors -such as style violations, interface misuse, or bugs that can be deduced via static analysis. -It is provided as part of +`clang-tidy `__ +is a C++ “linter” tool to assist with diagnosing and fixing typical programming errors +including portability/readability issues, bug-prone code constructs, +interface misuse, or bugs that can be deduced via static analysis. You can find details for the current release at https://releases.llvm.org/download.html. Note that *clang-format* is part of the main **Clang** project, whilst *clang-tidy* can be @@ -31,15 +31,15 @@ systems. Different versions of clang-format can produce different results, despite using the same configuration file. - We are using version 8.0.1 of clang-format and clang-tidy on our + We are using version 8.0.1 of clang-format on our Continuous Integration (CI) System. - + You should install the same version on your development computer. -Configuration -------------- +clang-format +------------ Rules ~~~~~ @@ -60,7 +60,7 @@ in the `ClangFormat documentation Eclipse IDE ^^^^^^^^^^^ -For our Eclipse IDE, which is our preferred IDE, we recommend installing +For the Eclipse IDE we recommend installing the `CppStyle plugin `__. You can configure your IDE to auto-format the code on “Save” using the recommended coding style and/or format according to our coding style @@ -79,10 +79,10 @@ Single File If you want to directly apply the coding standards from the command line you can run the following command:: - + cd $SMING_HOME clang-format -style=file -i Core/ - + Where ``Core/`` should be replaced with the path to the file that you have modified. @@ -91,10 +91,10 @@ All files The following command will run again the coding standards formatter over all C, C++ and header files inside the ``Sming/Core``, ``samples`` and other key directories:: - + cd $SMING_HOME make cs - + The command needs time to finish. So be patient. It will go over all files and will try to fix any coding style issues. @@ -105,7 +105,7 @@ All files make cs from your project directory. - + Eclipse ~~~~~~~ @@ -116,3 +116,64 @@ Alternatively, you can manually apply the coding style rules by selecting the so C, C++ or header file or a selection in it and run the ``Format`` command (usually Ctrl-Shift-F). + +clang-tidy +---------- + +Configuration +~~~~~~~~~~~~~ + +No specific version is required but generally you should aim to use the most recent version +available in your distribution. Version 17.0.6 was used at time of writing these notes. + +The default tool configuration is defined in the +`.clang-tidy `__ +file, located in the root directory of the framework. + +.. note:: + + Unlike clang-format, clang-tidy has to be able to compile the target code in order to perform static analysis. + Code must build without errors for **Host** architecture. + + Clang has more limited `constexpr` support than GCC so cannot parse some of the FlashString + and NanoTime code without modification. + However, these changes are only made when `__clang__` is defined and do not affect regular builds with GCC. + + No object code is generated by clang-tidy. + +Usage +----- + +Only source files which haven't been built are inspected. +So, to restrict which code gets processed built the entire application normally, +then 'clean' the relevant modules before proceeding with clang-tidy. + +For example: + +``` +cd $SMING_HOME/../samples/Basic_Servo +make -j SMING_SOC=host +make clean Servo-clean +make CLANG_TIDY=clang-tidy +``` + +If you want to fix a particular type of problem, it's usually easiest to be explicit:: + + make CLANG_TIDY="clang-tidy --checks='-*,modernize-use-equals-default' --fix" + +Remember to run ``make cs`` and check the output before committing! + +If you want to provide a custom configuration file:: + + make CLANG_TIDY="clang-tidy --config-file=myTidyConfig" + + +.. note:: + + clang-tidy can take a long time to do its work, so it's tempting to use the `-j` option + to speed things up. + You may see some corrupted output though as the output from multiple clang-tidy + instances aren't serialised correctly. + It's usually fine to get a rough 'first-pass' indication of any problems though. + + However, if attempting to apply fixes **DO NOT** use the -j option as this will result in corrupted output.