Various improvments (#28)

* fix multiple graphs and allow debug check arguments
* improves iwyu mapping and report
* force memcheck run when error founds
* fix memcheck
* refector iwyu result ui
* improve iwyu mapping
* fixes #29

CMakeLists.txt

@@ -11,6 +11,8 @@ list(APPEND l_dirs doc-coverage)
 list(APPEND l_dirs interface)
 list(APPEND l_dirs memcheck)
 list(APPEND l_dirs tracking)
+list(APPEND l_dirs codedup)
+list(APPEND l_dirs iwyu)
 
 file(GLOB l_files "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cmake")
 install(FILES ${l_files}

docs/installation.rst

@@ -28,8 +28,14 @@ Project homepage : https://launchpad.net/~psycofdj/+archive/ubuntu/xtdmake
 From source
 -----------
 
+
 Project homepage : https://github.com/psycofdj/xtdmake
 
+.. note::
+
+   Each packages requires a set of programs. You're not forced to install everything
+   if you don't need all XTDMake's modules.
+
 1. Install suggested dependencies
 
   .. code-block:: bash
@@ -57,6 +63,8 @@ Project homepage : https://github.com/psycofdj/xtdmake
     # PMD
     wget https://github.com/pmd/pmd/releases/download/pmd_releases%2F5.7.0/pmd-bin-5.7.0.zip
     sudo unzip -d /usr/share pmd-bin-5.7.0.zip
+    # Include what you use
+    sudo apt-get install iwyu
 
 2. Download latest release
 

docs/intro.rst

@@ -1,40 +1,56 @@
 Introduction
 ============
 
-XTDMake is a set of CMake packages that provides easy-to-use targets that generate
-code quality measurements reports :
-
-* Doxygen-based documentation
-* Coverage of documentation
-* Count lines of code
-* Cppcheck static analysis
-* Unit tests
-* Coverage of unit tests
-* Memory leak of unit tests
-* Code duplication analysis
+XTDMake is a set of CMake_ packages that provides easy-to-use targets that generate
+code quality measurements reports.
+
+* Documentation (using Doxygen_)
+* Documentation coverage (using Doxygen_ and Lcov_)
+* Count lines of code (using Cloc_)
+* C++ static code analysis (using CppCheck_)
+* Unit tests (using CMake_'s test facility)
+* Code coverage (using Lcov_)
+* Memory leak of unit tests (using Valgrind_)
+* Code duplication analysis (using Pmd_)
+* C++ include sanitizing (using Iwyu_)
+
+.. _Doxygen: http://www.doxygen.org/
+.. _Lcov: http://ltp.sourceforge.net/coverage/lcov.php
+.. _Cloc: http://cloc.sourceforge.net/
+.. _CppCheck: http://cppcheck.sourceforge.net/
+.. _Valgrind: http://valgrind.org/
+.. _Pmd: http://pmd.sourceforge.net
+.. _Iwyu: https://include-what-you-use.org/
+.. _CMake: https://cmake.org/
 
 
 Each target generates both a locally readable and machine processable reports.
 Local report targets the developer while the machine-processable reports can be
 used in your Continuous Integration (CI) process.
 
 
-.. note::
+Locally runnable
+----------------
+
+Key Point Indicators (KPIs) measurement tools are often built in the CI
+work flow and therefore cannot be run on the developer's local environment.
+This usually lead to discovering regressions (failed tests, a lower coverage
+or what-so-ever) only after pushing code to distant repository.
+Developer's being responsible for the KPIs, they should be able to
+run the measurement tools before pushing new code.
 
-  Key Points Indicators (KPIs) measurement tools are often built in the CI
-  work flow and therefore cannot be run on the developer's local environment.
-  This usually lead to discovering regressions (failed tests, a lower coverage
-  or what-so-ever) only after pushing code to distant repository.
-  Developer's being responsible for the KPIs, they should be able to
-  run the measurement tools before pushing new code.
+Per module
+----------
 
-  Because code of industrial applications is usually segmented in different modules,
-  each with a different purpose and levels of criticity, XTDMake's KPIs reports are
-  generated per module, allowing a finer interpretation of the indicators.
+Because code of industrial applications is usually divided in different modules,
+each with a different purpose and levels of criticity, XTDMake's KPIs reports are
+generated per module, allowing a finer interpretation of the indicators.
 
-  C++ compilation is already slow enough. XTDMake's targets are designed to be fully
-  incremental with a fine dependency tracking.
+Incremental execution
+---------------------
 
+C++ compilation is already slow enough. XTDMake's targets are designed to be fully
+incremental with a fine dependency tracking.
 
 
 ..

docs/quality.check.rst

@@ -4,6 +4,9 @@
 CheckRule
 ---------
 
+This module create targets that runs and generate reports about unit-tests.
+
+
 .. contents::
    :local:
 
@@ -25,18 +28,19 @@ Functions
 .. code-block:: cmake
 
   add_check(<module>
-    [PATTERNS  <pattern>     [<pattern>   ...]]
-    [INCLUDES  <dir>         [<dir>       ...]]
-    [LINKS     <lib>         [<lib>       ...]]
-    [ENV       <key>=<value> [<key=value> ...]]
-    [ARGS      <arg>         [<arg>       ...]]
-    [DIRECTORY <dir>]
-    [PREFIX    <str>]
-    [JOBS      <int>]
-    [NO_DEFAULT_ENV]
-    [NO_DEFAULT_ARGS]
-    [NO_DEFAULT_INCLUDES]
-    [NO_DEFAULT_LINKS]
+    [ PATTERNS  <pattern>     [<pattern>   ...]]
+    [ INCLUDES  <dir>         [<dir>       ...]]
+    [ LINKS     <lib>         [<lib>       ...]]
+    [ ENV       <key>=<value> [<key=value> ...]]
+    [ ARGS      <arg>         [<arg>       ...]]
+    [ DIRECTORY      <dir>  ]
+    [ PREFIX         <str>  ]
+    [ JOBS           <int>  ]
+    [ CMAKEVARS_NAME <name> ]
+    [ NO_DEFAULT_ENV        ]
+    [ NO_DEFAULT_ARGS       ]
+    [ NO_DEFAULT_INCLUDES   ]
+    [ NO_DEFAULT_LINKS      ]
   )
 
 
@@ -97,6 +101,17 @@ ARGS
 
   Default value is given :py:obj:`CheckRule_DEFAULT_ARGS`
 
+DBG_ARGS
+  List of command-line options to pass when running test through debugger.
+  It Usually sets arguments to command line to prevent your test framework
+  to protect run with forks, allowing to get a usable frame-stack to
+  investigate crashes.
+
+  Default value is given by :py:obj:`CheckRule_DEFAULT_DBG_ARGS` unless
+  ``NO_DEFAULT_ARGS`` option is given.
+
+  Default value is given :py:obj:`CheckRule_DEFAULT_DBG_ARGS`
+
 DIRECTORY
   Directory to search tests source files. See :ref:`details <CheckRule_matching>`
   about how tests are automatically detected by this module.
@@ -114,6 +129,12 @@ JOBS
 
   Default value is given :py:obj:`CheckRule_DEFAULT_JOBS`
 
+CMAKEVARS_NAME
+  Path to header file generated by check rule. See :ref:`details <CheckRule_paths>`
+  about how getting information about source/build tree in your test code.
+
+  Default value is given :py:obj:`CheckRule_DEFAULT_CMAKEVARS_NAME`
+
 NO_DEFAULT_ENV
   If option is given, don't use :py:obj:`CheckRule_DEFAULT_ENV`
 
@@ -131,6 +152,7 @@ Global variables
 ----------------
 
 
+
 .. py:attribute:: CheckRule_DEFAULT_PATTERNS
                   ".c;.cc;.cpp"
 .. py:attribute:: CheckRule_DEFAULT_INCLUDES
@@ -145,6 +167,60 @@ Global variables
                   "Test"
 .. py:attribute:: CheckRule_DEFAULT_JOBS
                   "1"
+.. py:attribute:: CheckRule_DEFAULT_ARGS
+                  ""
+.. py:attribute:: CheckRule_DEFAULT_DBG_ARGS
+                  ""
+.. py:attribute:: CheckRule_DEFAULT_CMAKEVARS_NAME
+                  "\${CMAKE_CURRENT_BINARY_DIR}/cmakevars.h"
+.. py:attribute:: CheckRule_DEFAULT_TIMEOUT
+                  "120"
+
+
+.. _CheckRule_paths:
+
+Getting path informations in tests
+----------------------------------
+
+Tests often need to read sample files located in either source or build directory.
+Because source and build trees are not relative to each others, only CMake knows
+where both root directories are located.
+
+XTDMake's CheckRule provides two ways to forward this informations to your tests :
+
+  1. Using ``ARGS`` and/or ``CheckRule_DEFAULT_ARGS`` to add command line parameters
+     built with CMake variables such as :
+
+     - ``CMAKE_SOURCE_DIR``         : top source directory
+     - ``CMAKE_BINARY_DIR``         : top build directory
+     - ``CMAKE_CURRENT_SOURCE_DIR`` : current module's source directory
+     - ``CMAKE_CURRENT_BINARY_DIR`` : current module's build directory
+
+     One possible value for ``CheckRule_DEFAULT_ARGS`` could be:
+
+     .. code-block:: shell
+
+        --topsrc-dir=\${CMAKE_PROJECT_SOURCE_DIR} \
+        --topbuild-dir=\${CMAKE_PROJECT_BINARY_DIR} \
+        --src-dir=\${CMAKE_SOURCE_DIR} \
+        --build-dir=\${CMAKE_BINARY_DIR}
+
+
+  2. Using generated header file. CheckRule automatically creates for each module
+     an header file named ``CheckRule_DEFAULT_CMAKEVARS`` or ``CMAKEVARS`` arguments.
+     This file is generated from the given template :
+
+     .. code-block:: C
+
+        #define   TOP_SRCDIR       "@CMAKE_SOURCE_DIR@"
+        #define       SRCDIR       "@CMAKE_CURRENT_SOURCE_DIR@"
+        #define TOP_BUILDDIR       "@PROJECT_BINARY_DIR@"
+        #define     BUILDDIR       "@CMAKE_CURRENT_BINARY_DIR@"
+        #define PROJECT_SOURCE_DIR "@PROJECT_SOURCE_DIR@"
+        #define PROJECT_BINARY_DIR "@PROJECT_BINARY_DIR@"
+
+     Your test code can simply include the generated header and use defined variables
+     to build path to your assets files located in source or build tree.
 
 
 .. _CheckRule_matching:
@@ -204,8 +280,8 @@ For each test *<name>*, the function also produces :
 ``<module>-check-ut-<name>``
   run individual test *<name>*
 
-``<module>-check-ut-<name>-gdb``
-  run individual test  *<name>* wrapped in gdb debugger
+``<module>-check-ut-<name>-dbg``
+  run individual test  *<name>* wrapped in debugger
 
 ``<module>-check-ut-<name>-cmd``
   prints individual test command *<name>*
@@ -221,7 +297,7 @@ function.
   This function must be called **before** ``add_check``
 
 .. code-block:: cmake
-  
+
   add_check_test(module name
     COMMAND <command> [ <arg> ... ]
     [ ENVIRONMENT <var>=<value> [ <var>=<value> ... ]
@@ -235,11 +311,17 @@ name
 
 COMMAND
   command line to run for this test
-  
+
 ENVIRONMENT
   environment variable to define before running the test
 
 
+About debugger
+--------------
+
+By default, CheckRule debugger target wraps test execution in ``GNU gdb``. If ``USE_CLANG``
+variable is defined, debugger is switched to ``lldb``.
+
 Target Dependencies
 -------------------
 

docs/quality.codedup.rst

@@ -1,8 +1,8 @@
 .. _CodeDupRule:
 
-------------
+-----------
 CodeDupRule
-------------
+-----------
 
 .. contents::
    :local:
@@ -36,6 +36,7 @@ Functions
     [INTPUT           <dir>     [ <dir>     ... ]],
     [FILE_PATTERNS    <pattern> [ <pattern> ... ]],
     [EXCLUDE_PATTERNS <regexp>  [ <regexp>  ... ]],
+    [SUPPRESSIONS     <file>]
     [MIN_TOKENS       <int>]
     [ARGS             <int>]
   )
@@ -65,6 +66,10 @@ EXCLUDE_PATTERNS
   List of regular expressions to exclude matched input files.
   Default value is given by :py:obj:`CodeDupRule_DEFAULT_EXCLUDE_PATTERNS`
 
+SUPPRESSIONS
+  Path to suppression list.
+  Default value is given by :py:obj:`CodeDupRule_DEFAULT_SUPPRESSION`
+
 Global variables
 ----------------
 
@@ -105,6 +110,54 @@ CodeDupRule default minimum token length which should be reported as a duplicate
 
 CodeDupRule default additional arguments to give to PMD
 
+
+.. py:attribute:: CodeDupRule_DEFAULT_SUPPRESSION
+                  "\${CMAKE_CURRENT_SOURCE_DIR}/src/codedup.suppr"
+
+CodeDupRule default path to suppression file
+
+
+
+Suppression file
+----------------
+
+You may want to squelch some of the duplicated blocks detected by PMD. To do so
+can provide a ``json`` file with the following format:
+
+.. code-block:: bash
+
+   [
+     <suppression_1>,
+     <suppression_2>,
+     ...
+   ]
+
+where each ``<suppression>`` structure gives instruction to squelch one bloc with
+the following format:
+
+
+.. code-block:: bash
+
+   [
+     {
+       "file" : "<path-to-file>",
+       "from" : <start_line>,
+       "to"   : <end_line>
+     },
+     {
+       "file" : "<path-to-file>",
+       "from" : <start_line>,
+       "to"   : <end_line>
+     },
+     ...
+   ]
+
+Duplicated code block detected by PMD is compared to each ``<suppression>``. When
+bloc if found is all given ``files`` between ``from`` and ``to`` lines, the
+duplication is squelched.
+
+
+
 Generated targets
 -----------------
 
@@ -244,7 +297,7 @@ Bellow an example of generated html report :
     "data": {
       "total": 1
     }
-  } 
+  }
 ..
    Local Variables:
    ispell-local-dictionary: "en"

docs/quality.cov.rst

@@ -28,7 +28,6 @@ Functions
   add_cov(<module>
     [ EXCLUDE_PATTERNS <pattern> [ <pattern> .. ]]
     [ MIN_PERCENT      <value> ]
-    [ PREFIX                   ]
   )
 
 This function generates cmake targets that produce reports that show your code coverage.