Add clang-tidy workflow (#4806)

* added instructions and script to run clang-tidy locally

* make script executable

* remove installation of blaspp and lapackpp from runClangTidy.sh script

* improved documentation

Docs/source/developers/run_clang_tidy_locally.rst

@@ -0,0 +1,55 @@
+.. _developers-run_clang_tidy_locally:
+
+The clang-tidy linter
+=====================
+
+Clang-tidy CI test
+------------------
+
+WarpX's CI tests include several checks performed with the
+`clang-tidy <https://releases.llvm.org/15.0.0/tools/clang/tools/extra/docs/clang-tidy/index.html>`__ linter
+(currently the version 15 of this tool). The complete list of checks
+enforced in CI tests can be found in the ``.clang-tidy`` configuration file.
+
+.. dropdown:: clang-tidy configuration file
+   :color: light
+   :icon: info
+   :animate: fade-in-slide-down
+
+   .. literalinclude:: ../../../.clang-tidy
+      :language: yaml
+
+Run clang-tidy linter locally
+-----------------------------
+
+We provide a script to run clang-tidy locally. The script can be run as follows,
+provided that all the requirements to compile WarpX are met (see `building from source <install-developers>`).
+The script generates a simple wrapper to ensure that `clang-tidy` is only applied to WarpX source files
+and compiles WarpX in 1D,2D,3D, and RZ using such wrapper. By default WarpX is compiled in single precision
+with PSATD solver, QED module, QED table generator and Embedded boundary in order to find more
+potential issues with the `clang-tidy` tool.
+
+Few optional environment variables can be set to tune the behavior of the script:
+
+* ``WARPX_TOOLS_LINTER_PARALLEL``: sets the number of cores to be used for the compilation
+* ``CLANG``, ``CLANGXX``, and ``CLANGTIDY`` : set the version of the compiler and of the linter
+
+Note: clang v15 is currently used in CI tests. It is therefore recommended to use this version.
+Otherwise, a newer version may find issues not currently covered by CI tests (checks are opt-in)
+while older versions may not find all the issues.
+
+.. code-block:: bash
+
+   export WARPX_TOOLS_LINTER_PARALLEL=12
+   export CLANG=clang-15
+   export CLANGXX=clang++-15
+   export CLANGTIDY=clang-tidy-15
+   ./Tools/Linter/runClangTidy.sh
+
+.. dropdown:: Script Details
+   :color: light
+   :icon: info
+   :animate: fade-in-slide-down
+
+   .. literalinclude:: ../../../Tools/Linter/runClangTidy.sh
+      :language: bash

Docs/source/developers/workflows.rst

@@ -11,3 +11,4 @@ Workflows
    documentation
    checksum
    local_compile
+   run_clang_tidy_locally

Tools/Linter/runClangTidy.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# Copyright 2024 Luca Fedeli
+#
+# This file is part of WarpX.
+#
+
+# This script is a developer's tool to perform the
+# checks done by the clang-tidy CI test locally.
+#
+# Note: this script is only tested on Linux
+
+echo "============================================="
+echo
+echo "This script is a developer's tool to perform the"
+echo "checks done by the clang-tidy CI test locally"
+echo "_____________________________________________"
+
+# Check source dir
+REPO_DIR=$(cd $(dirname ${BASH_SOURCE})/../../ && pwd)
+echo
+echo "Your current source directory is: ${REPO_DIR}"
+echo "_____________________________________________"
+
+# Set number of jobs to use for compilation
+PARALLEL="${WARPX_TOOLS_LINTER_PARALLEL:-4}"
+echo
+echo "${PARALLEL} jobs will be used for compilation."
+echo "This can be overridden by setting the environment"
+echo "variable WARPX_TOOLS_LINTER_PARALLEL, e.g.: "
+echo
+echo "$ export WARPX_TOOLS_LINTER_PARALLEL=8"
+echo "$ ./Tools/Linter/runClangTidy.sh"
+echo "_____________________________________________"
+
+# Check clang version
+export CC="${CLANG:-"clang"}"
+export CXX="${CLANGXX:-"clang++"}"
+export CTIDY="${CLANGTIDY:-"clang-tidy"}"
+echo
+echo "The following versions of the clang compiler and"
+echo "of the clang-tidy linter will be used:"
+echo
+echo "clang version:"
+which ${CC}
+${CC} --version
+echo
+echo "clang++ version:"
+which ${CXX}
+${CXX} --version
+echo
+echo "clang-tidy version:"
+which ${CTIDY}
+${CTIDY} --version
+echo
+echo "This can be overridden by setting the environment"
+echo "variables CLANG, CLANGXX, and CLANGTIDY e.g.: "
+echo "$ export CLANG=clang-15"
+echo "$ export CLANGXX=clang++-15"
+echo "$ export CTIDCLANGTIDYY=clang-tidy-15"
+echo "$ ./Tools/Linter/runClangTidy.sh"
+echo
+echo "******************************************************"
+echo "* Warning: clang v15 is currently used in CI tests.  *"
+echo "* It is therefore recommended to use this version.   *"
+echo "* Otherwise, a newer version may find issues not     *"
+echo "* currently covered by CI tests while older versions *"
+echo "* may not find all the issues.                       *"
+echo "******************************************************"
+echo "_____________________________________________"
+
+# Prepare clang-tidy wrapper
+echo
+echo "Prepare clang-tidy wrapper"
+echo "The following wrapper ensures that only source files"
+echo "in WarpX/Source/* are actually processed by clang-tidy"
+echo
+cat > ${REPO_DIR}/clang_tidy_wrapper << EOF
+#!/bin/bash
+REGEX="[a-z_A-Z0-9\/]*WarpX\/Source[a-z_A-Z0-9\/]+.cpp"
+if [[ \$4 =~ \$REGEX ]];then
+  ${CTIDY} \$@
+fi
+EOF
+chmod +x ${REPO_DIR}/clang_tidy_wrapper
+echo "clang_tidy_wrapper: "
+cat ${REPO_DIR}/clang_tidy_wrapper
+echo "_____________________________________________"
+
+# Compile Warpx using clang-tidy
+echo
+echo "*******************************************"
+echo "* Compile Warpx using clang-tidy          *"
+echo "* Please ensure that all the dependencies *"
+echo "* required to compile WarpX are met       *"
+echo "*******************************************"
+echo
+
+rm -rf ${REPO_DIR}/build_clang_tidy
+
+cmake -S ${REPO_DIR} -B ${REPO_DIR}/build_clang_tidy \
+  -DCMAKE_CXX_CLANG_TIDY="${REPO_DIR}/clang_tidy_wrapper;--system-headers=0;--config-file=${REPO_DIR}/.clang-tidy" \
+  -DCMAKE_VERBOSE_MAKEFILE=ON  \
+  -DWarpX_DIMS="1;2;3;RZ"      \
+  -DWarpX_MPI=ON               \
+  -DWarpX_COMPUTE=OMP          \
+  -DWarpX_PSATD=ON             \
+  -DWarpX_QED=ON               \
+  -DWarpX_QED_TABLE_GEN=ON     \
+  -DWarpX_OPENPMD=ON           \
+  -DWarpX_PRECISION=SINGLE
+
+cmake --build ${REPO_DIR}/build_clang_tidy -j ${PARALLEL} 2> ${REPO_DIR}/build_clang_tidy/clang-tidy.log
+
+cat ${REPO_DIR}/build_clang_tidy/clang-tidy.log
+echo
+echo "============================================="