From 2b385a443d44b6123d6a8ffbeab4aa3c82e5ce0c Mon Sep 17 00:00:00 2001
From: Matthias Wittgen <matthias.michael.wittgen@cern.ch>
Date: Mon, 6 Jun 2022 10:22:57 -0700
Subject: [PATCH] Add section on static C++ code analysis

---
 cpp/code-analysis.rst | 58 +++++++++++++++++++++++++++++++++++++++++++
 index.rst             |  2 ++
 2 files changed, 60 insertions(+)
 create mode 100644 cpp/code-analysis.rst

diff --git a/cpp/code-analysis.rst b/cpp/code-analysis.rst
new file mode 100644
index 00000000..68ff3197
--- /dev/null
+++ b/cpp/code-analysis.rst
@@ -0,0 +1,58 @@
+###########################
+Static Analysis of C++ code
+###########################
+
+`CodeChecker <https://codechecker.readthedocs.io>`_,
+`clang static analyzer <https://clang-analyzer.llvm.org>`_  and
+`clang-tidy documentation <https://clang.llvm.org/extra/clang-tidy>`_ can be
+used to detect potential C++ problems enforce C++ coding standards.
+
+==============================
+Install tools from conda-forge
+==============================
+
+``CodeChecker`` depends on ``clang-tools`` and the clang compilers for static analysis.
+
+To install the compilers and tools into an LSST Science Pipelines conda stack for Linux x86_64
+.. code-block:: bash
+
+   mamba install -c conda-forge clang clangxx clang-tools
+
+To install ``CodeChecker``
+
+.. code-block:: bash
+
+   mamba install -c CodeChecker
+
+================================
+Running ``clang-tidy`` on builds
+================================
+
+``CodeChecker`` intercepts calls to the compiler executables, builds a compilation database and runs
+analyses on the source code. 
+
+To run ``CodeChecker`` in an lsstsw build environment
+.. code-block:: bash
+
+   C=gcc CXX=g++ CC_BIN=CodeChecker CodeChecker check -j4 --build "rebuild lsst_distrib" --analyzers clang-tidy -o results
+
+``--analyzers clang-tidy`` limits the analysis to ``clang-tidy`` checks and disables ``clang`` static analysis, which
+is very CPU intensive.
+The build command can be replaced as needed. For example, to run on ``scons`` builds
+
+.. code-block:: bash
+
+   C=gcc CXX=g++ CC_BIN=CodeChecker CodeChecker check -j4 --build "scons -j4 --analyzers clang-tidy" -o results
+
+The standard output format of ``CodeChecker`` is ``plist``.
+To produce a html report of the analysis results
+
+.. code-block:: bash
+
+   CodeChecker parse --trim-path-prefix $(pwd) -e html results -o results/html
+
+Adding ``--trim-path-prefix`` avoids absolute references in the html output.
+The result can be browsed with
+.. code-block:: bash
+
+   firefox html/index.html
diff --git a/index.rst b/index.rst
index 0e6ddb05..16f75917 100644
--- a/index.rst
+++ b/index.rst
@@ -196,6 +196,7 @@ Overview of Code Style Guides & Policies
    cpp/eigen
    cpp/profiling
    cpp/compilation-db
+   cpp/code-analysis
 
 .. _part-cpp:
 
@@ -211,6 +212,7 @@ C++
 - :doc:`cpp/eigen`
 - :doc:`cpp/profiling`
 - :doc:`cpp/compilation-db`
+- :doc:`cpp/code-analysis`
 
 .. PYTHON SECTION ============================================================