update documentation (#23)

adds extra_args for memcheck

debian/changelog

@@ -1,3 +1,24 @@
+xtdmake (1.2.1ppa1~xenial) xenial; urgency=medium
+
+  * update documentation
+  * adds extra_args for memcheck
+
+ -- Xavier MARCELET <xavier@marcelet.com>  Sun, 18 Jun 2017 11:25:28 +0200
+
+xtdmake (1.2.1ppa1~trusty) trusty; urgency=medium
+
+  * update documentation
+  * adds extra_args for memcheck
+
+ -- Xavier MARCELET <xavier@marcelet.com>  Sun, 18 Jun 2017 11:25:28 +0200
+
+xtdmake (1.2.1ppa1~precise) precise; urgency=medium
+
+  * update documentation
+  * adds extra_args for memcheck
+
+ -- Xavier MARCELET <xavier@marcelet.com>  Sun, 18 Jun 2017 11:25:28 +0200
+
 xtdmake (1.2.0ppa1~xenial) xenial; urgency=medium
 
   * adds codedup rule to detect code duplication

debian/control

@@ -9,7 +9,7 @@ X-Python2-Version: >= 2.7
 Package: xtdmake
 Architecture: all
 Depends: python (>= 2.7), python (<< 2.8), cmake (>= 2.6), ${misc:Depends}
-Suggests: doxygen, graphviz, xsltproc, lcov, cloc, cppcheck, valgrind
+Suggests: doxygen, graphviz, xsltproc, lcov, cloc, cppcheck, valgrind, default-jre
 Description: CMake modules to generate C and CXX code quality measurements targets
  http://github.com/psycofdj/xtdmake
  .

docs/installation.rst

@@ -6,19 +6,19 @@ From PPA Package
 
 Project homepage : https://launchpad.net/~psycofdj/+archive/ubuntu/xtdmake
 
-1. Add PPA repository to apt 
+1. Add PPA repository to apt
 
    .. code-block:: bash
 
      sudo add-apt-repository ppa:psycofdj/xtdmake
 
-2. Update apt 
+2. Update apt
 
    .. code-block:: bash
 
      sudo apt-get update
 
-3. Install XTDMake 
+3. Install XTDMake
 
    .. code-block:: bash
 
@@ -52,6 +52,11 @@ Project homepage : https://github.com/psycofdj/xtdmake
     sudo apt-get install valgrind
     # jq, awk for json
     sudo apt-get install jq
+    # java 8
+    sudo apt-get install openjdk-8-jre
+    # 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
 
 2. Download latest release
 

docs/intro.rst

@@ -11,6 +11,7 @@ code quality measurements reports :
 * Unit tests
 * Coverage of unit tests
 * Memory leak of unit tests
+* Code duplication analysis
 
 
 Each target generates both a locally readable and machine processable reports.

docs/other.rst

@@ -65,6 +65,7 @@ xtdmake_find_program
     REQUIRED <bool>
     [ VERSION_OPT <options> ]
     [ VERSION_POS <int>     ]
+    [ MIN_VERSION <version> ]
   )
 
 Search program matching one of given ``NAMES``, try to extract its version using
@@ -103,6 +104,9 @@ VERSION_POS
   position of the version number in the space-delimited string outputted by program
   with ``VERSION_OPT``
 
+MIN_VERSION
+  minimum allowed version of searched program
+
 
 **Example**
 
@@ -114,6 +118,7 @@ VERSION_POS
      URL "http://cloc.sourceforge.net/"
      VERSION_OPT "--version"
      VERSION_POS "0"
+     MIN_VERSION 1.2
      REQUIRED 0)
 
    if (cloc_FOUND)

docs/quality.codedup.rst

@@ -0,0 +1,251 @@
+.. _CodeDupRule:
+
+------------
+CodeDupRule
+------------
+
+.. contents::
+   :local:
+
+This module generates a report that shows detected code duplication blocks.
+
+Prerequisites
+-------------
+
+Java
+  Java runtime environment. Available from ubuntu packages or from
+  source at http://cppcheck.sourceforge.net/
+
+  .. warning:: module requires Java 8 minimum version.
+
+Pmd
+  PMD is a source code analyzer. Available from source or binaries at
+  http://pmd.sourceforge.net/
+
+xsltproc
+  XSL Template rendering tool. Available from ubuntu packages or from
+  source at http://xmlsoft.org/
+
+
+Functions
+---------
+
+.. code-block:: cmake
+
+  add_codedup(module,
+    [INTPUT           <dir>     [ <dir>     ... ]],
+    [FILE_PATTERNS    <pattern> [ <pattern> ... ]],
+    [EXCLUDE_PATTERNS <regexp>  [ <regexp>  ... ]],
+    [MIN_TOKENS       <int>]
+    [ARGS             <int>]
+  )
+
+
+This function generates cmake targets that produce codedup report for a given module.
+Generated targets are added as dependency of the global ``codedup`` and ``codedup-clean``
+targets.
+
+
+Parameters
+----------
+
+module
+  Name of the module. It determines the name of the generated cmake
+  targets and the directory where targets generate the report.
+
+INPUT
+  List of directories where target should search source files process.
+  Default value is given by :py:obj:`CodeDupRule_DEFAULT_INPUT`
+
+FILE_PATTERNS
+  List of wildcards search files in given input directories.
+  Default value is given by :py:obj:`CodeDupRule_DEFAULT_FILE_PATTERNS`
+
+EXCLUDE_PATTERNS
+  List of regular expressions to exclude matched input files.
+  Default value is given by :py:obj:`CodeDupRule_DEFAULT_EXCLUDE_PATTERNS`
+
+Global variables
+----------------
+
+.. py:attribute:: CodeDupRule_DEFAULT_PMD_VERSION
+                  "5.7.0"
+
+CodeDupRule PDM installed version.
+
+
+.. py:attribute:: CodeDupRule_DEFAULT_PMD_HOME
+                  "/usr/share/pmd-bin-\${CodeDupRule_PMD_VERSION}"
+
+CodeDupRule location of PDM installation.
+
+
+.. py:attribute:: CodeDupRule_DEFAULT_INPUT
+                  "${CMAKE_CURRENT_SOURCE_DIR}/src"
+
+CodeDupRule default list of input source directories
+
+.. py:attribute:: CodeDupRule_DEFAULT_FILE_PATTERNS
+                  "*.cc;*.hh;*.hxx"
+
+CodeDupRule default list of wildcard patterns to search in INPUT directories
+
+.. py:attribute:: CodeDupRule_DEFAULT_EXCLUDE_PATTERNS
+                  "\${CMAKE_CURRENT_SOURCE_DIR}/unit/.*"
+
+CodeDupRule default list of regexp to exclude from analysis
+
+.. py:attribute:: CodeDupRule_DEFAULT_MIN_TOKENS
+                  "100"
+
+CodeDupRule default minimum token length which should be reported as a duplicate
+
+.. py:attribute:: CodeDupRule_DEFAULT_ARGS
+                  "--skip-lexical-errors"
+
+CodeDupRule default additional arguments to give to PMD
+
+Generated targets
+-----------------
+
+``codedup``
+  generate codedup reports for all modules
+
+``codedup-clean``
+   removes codedup reports for all modules
+
+``<module>-codedup``
+  generate codedup report for module *<module>*
+
+``<module>-codedup-clean``
+  removes codedup report for module *<module>*
+
+Dependencies
+------------
+
+.. graphviz::
+
+   digraph G {
+     rankdir="LR";
+     node [shape=box, style=filled, fillcolor="#ffff99", fontsize=12];
+     "cmake" -> "dir_list(INPUT)"
+     "cmake" -> "codedup"
+     "cmake" -> "codedup-clean"
+     "codedup" -> "<module>-codedup"
+     "<module>-codedup" -> "file_list(INPUT, FILE_PATTERNS) - EXCLUDE_PATTERNS"
+     "codedup-clean" -> "<module>-codedup-clean"
+   }
+
+.. warning::
+
+  The dependency of cmake build system to the modification time of
+  :py:obj:`INPUT` directories doesn't work with cmake versions
+  prior to 3.0. This mean you must re-run cmake after adding new sources files in
+  order to properly update the rule files dependencies
+
+Generated reports
+-----------------
+
+**HTML** : ``reports/codedup/<module>/index.html``
+
+Bellow an example of generated html report :
+
+.. image:: _static/codedup.png
+  :align: center
+
+**XML** : ``reports/codedup/<module>/codedup.xml``
+
+.. code-block:: xml
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <pmd-cpd>
+     <duplication lines="18" tokens="121">
+        <file line="16" path="/home/psyco/dev/xtdcpp/core/src/log/ColoredFormatter.cc"/>
+        <file line="34" path="/home/psyco/dev/xtdcpp/core/src/log/ColoredFormatter.cc"/>
+        <codefragment><![CDATA[  Formatter()
+  {
+    using namespace tty;
+
+    setStyles({
+        { "name",     style(color::green)               },
+        { "threadid", style(color::yellow)              },
+        { "message",  style(color::white)               },
+        { "module",   style(color::lyellow)             },
+        { "time",     style(color::cyan)                },
+        { "slevel",   style(color::lred, attrs::bold)   },
+        { "location", style(color::lblack)              },
+        { "pid",      style(color::lblue)               },
+        { "ppid",     style(color::lblue, attrs::bold)  }
+      });
+  }
+
+  ColoredFormatter::ColoredFormatter(const Formatter& p_base) :]]></codefragment>
+     </duplication>
+  </pmd-cpd>
+
+**JSON** : ``reports/codedup/<module>/status.json``
+
+
+.. code-block:: json
+
+  {
+    "status": "failure",
+    "index": "index.html",
+    "module": "core",
+    "label": "1",
+    "graphs": [
+      {
+        "data": {
+          "labels": [],
+          "datasets": [
+            {
+              "borderColor": "rgba(179, 0, 0, 0.5)",
+              "pointBorderColor": "rgba(102, 0, 0, 1)",
+              "yAxisID": "absolute",
+              "label": "codedup: # error count",
+              "backgroundColor": "rgba(179, 0, 0, 0.5)",
+              "pointBackgroundColor": "rgba(102, 0, 0, 1)",
+              "data": "%(total)d"
+            }
+          ]
+        },
+        "type": "line",
+        "options": {
+          "scales": {
+            "xAxes": [
+              {
+                "ticks": {
+                  "fontSize": 12,
+                  "minRotation": 80
+                }
+              }
+            ],
+            "yAxes": [
+              {
+                "position": "left",
+                "ticks": {
+                  "fontSize": 24,
+                  "beginAtZero": true
+                },
+                "type": "linear",
+                "id": "absolute",
+                "display": true
+              }
+            ]
+          },
+          "title": {
+            "text": "%(module)s : codedup",
+            "display": true
+          }
+        }
+      }
+    ],
+    "kpi": "codedup",
+    "data": {
+      "total": 1
+    }
+  } 
+..
+   Local Variables:
+   ispell-local-dictionary: "en"
+   End:

docs/quality.memcheck.rst

@@ -7,7 +7,8 @@ MemcheckRule
 .. contents::
    :local:
 
-This module generates a report from result of cppcheck static analysis.
+This module generates a report that shows defects memory detected by valgrind for
+available unit tests.
 
 Prerequisites
 -------------
@@ -25,13 +26,32 @@ Functions
 
 .. code-block:: cmake
 
-  add_memcheck(<module>)
+  add_memcheck(<module>
+  [SUPPRESSIONS <file> [<file> ... ]]
+  [EXTRA_ARGS   <args>]
+  )
 
 This function generates cmake targets that produce reports that show memory flaws
 detected by valgrind on module's test suite. Generated targets are added as dependency
 of the global ``memcheck`` and ``memcheck-clean`` targets.
 
 
+
+Parameters
+----------
+
+module
+  Name of the module. It determines the name of the generated cmake
+  targets and the directory where targets generate the report.
+
+SUPPRESSIONS
+  List of existing files to add as valgrind supression stacks. See
+  http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress
+
+EXTRA_ARGS
+  List of additional arguments to pass to valgrind. Use with caution,
+  parameters must be compatible with ```--tool=memcheck```.
+
 Generated targets
 -----------------