Update clang-tidy to clang version 8

[alexxy/gromacs.git] / docs / dev-manual / build-system.rst

diff --git a/docs/dev-manual/build-system.rst b/docs/dev-manual/build-system.rst
index fbdbedb2f462d11f9681667a63d41acf368761cc..f7a3f0ab400ef653e9bc95913007e260046d4d58 100644 (file)
--- a/docs/dev-manual/build-system.rst
+++ b/docs/dev-manual/build-system.rst
@@ -346,6 +346,28 @@ Variables affecting the ``all`` target
    inconvenient for a general user) can be added to the set controlled by this
    variable.
 
+.. cmake:: GMX_CLANG_TIDY
+
+  `clang-tidy <http://releases.llvm.org/8.0.0/tools/clang/tools/extra/docs/clang-tidy/index.html>`_
+  is used for static code analysis and (some) automated fixing of issues detected. clang-tidy is easy to install. It is contained in
+  the llvm binary `package <http://releases.llvm.org/download.html#8.0.0>`_. Only
+  version 8.0.* with libstdc++<7 or libc++ is supported. Others might miss tests or give false positives.
+  It is run automatically on Jenkins for each commit. Many checks have fixes which can automatically be
+  applied. To run it, the build has to be configured with
+  ``cmake -DGMX_CLANG_TIDY=ON -DGMX_OPENMP=no -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=on``.
+  Any ``CMAKE_BUILD_TYPE`` which enables asserts (e.g. ASAN) works. Such a configured build will
+  run both the compiler as well as clang-tidy when building. The name of the clang-tidy executable is set with
+  ``-DCLANG_TIDY=...``, and the full path to it can be set with ``-DCLANG_TIDY_EXE=...``.
+  To apply the automatic fixes to the issue identified clang-tidy should be run seperately (running clang-tidy
+  with ``-fix-errors`` as part of the build can corrupt header files). To fix a specific file run
+  ``clang-tidy -fix-errors -header-filter '.*' {file}``, to fix all files in parallel
+  ``run-clang-tidy.py -fix -header-filter '.*' '(?<!/selection/parser\.cpp|selection/scanner\.cpp)$'``,
+  and to fix all modified files ``run-clang-tidy.py -fix -header-filter '.*' $(git diff HEAD --name-only)``.
+  The run-clang-tidy.py script is in the
+  ``share/clang/`` subfolder of the llvm distribution. ``clang-tidy`` has to be able to find the
+  ``compile_commands.json`` file. Either run from the build folder or add a symlink to the source folder.
+  :cmake:`GMX_ENABLE_CCACHE` does not work with clang-tidy.
+
 Variables affecting special targets
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^