|
|
@@ -43,7 +43,7 @@ along with Metrix++. If not, see <http://www.gnu.org/licenses/>.
|
|
|
</tr>
|
|
|
<tr>
|
|
|
<td><img src="logo_project.png" alt="Software Index Project Page" /></td>
|
|
|
- <td valign="center">
|
|
|
+ <td valign="top">
|
|
|
<div align="right">
|
|
|
<p align="center"><a href="http://sourceforge.net/projects/swi"
|
|
|
class="lowImportance"><img
|
|
|
@@ -203,11 +203,214 @@ along with Metrix++. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
|
|
<h4>Basic Workflow</h4>
|
|
|
|
|
|
- <p>TBD</p>
|
|
|
+ <p>Assuming that you opened a terminal and your current working
|
|
|
+ directory is in the root folder of the tool installed.</p>
|
|
|
+
|
|
|
+ <p><strong>I.</strong> Start with running a collector tool,
|
|
|
+ enabling a collection of cyclomatic complexity:</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">collect.py</span> <span class="normalImportance">--std.code.complexity.on</span> -- /path/to/your/project ../../path/to/some/other/project</pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>It will generate a database file in working directory with
|
|
|
+ default name. In order to change the name or location, use
|
|
|
+ corresponding command line option. Depending on a size of code
|
|
|
+ base, colection may take seconds or minutes, but it is very
|
|
|
+ fast in general. In order to achive the highest performance (~
|
|
|
+ to calculation of crc32) for iterative re-scans, point out to
|
|
|
+ the dabase file collected for the previous code revision:</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">collect.py</span> --std.code.complexity.on <span class="highImportance normalImportance">--general.db-file-prev=metrixpp-prev.db</span> --
|
|
|
+ /path/to/your/project</pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>Paths are optional. If you do not specify a path, it will
|
|
|
+ scan files in current working directory. Check other available
|
|
|
+ options for the tool by executing:</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">collect.py</span> <span class="normalImportance">--help</span></pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p><strong>II.</strong> Secondly, export data using export
|
|
|
+ tool.</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">export.py</span> --
|
|
|
+<span class="lowImportance"><export>
|
|
|
+ <data>
|
|
|
+ <info path="" id="1" />
|
|
|
+ <file-data />
|
|
|
+ <subfiles>
|
|
|
+ </subfiles>
|
|
|
+ <subdirs>
|
|
|
+ <subdir>path</subdir>
|
|
|
+ </subdirs>
|
|
|
+ <aggregated-data>
|
|
|
+ <<span class="normalImportance">std.code.complexity</span>>
|
|
|
+ <cyclomatic max="2" total="14.0" avg="0.168674698795" min="0" />
|
|
|
+ </<span class="normalImportance">std.code.complexity</span>>
|
|
|
+ <<span class="normalImportance">std.code.cpp</span>>
|
|
|
+ <files max="1" total="4.0" avg="1.0" min="1" />
|
|
|
+ </<span class="normalImportance">std.code.cpp</span>>
|
|
|
+ </aggregated-data>
|
|
|
+ </data>
|
|
|
+</export></span>
|
|
|
+ </pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>By default, it exports all aggregated data for all files
|
|
|
+ scanned in xml format. It is possible to re-configure output
|
|
|
+ format to python or plain text. In order to narrow the scope,
|
|
|
+ specify a path to directory or a file. In order to export only
|
|
|
+ subset of metrics, specify them as well.</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">export.py</span> --general.format=<span class="normalImportance">python</span> --general.namespaces=<span class="normalImportance">std.code.complexity</span> --
|
|
|
+ <span class="normalImportance">/path/to/your/project/subdir</span>
|
|
|
+<span class="lowImportance"><export>
|
|
|
+ ...
|
|
|
+</export></span></pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>If you have got results collected for previous version,
|
|
|
+ point out to the file using the corresponding option and the
|
|
|
+ tool will add diff data.</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">export.py</span> --general.namespaces=<span class="normalImportance">std.code.complexity</span> --general.db-file-prev=<span class="normalImportance">metrixpp-prev.db</span> --
|
|
|
+<span class="lowImportance"><export>
|
|
|
+ <data>
|
|
|
+ <info path="" id="1" />
|
|
|
+ <file-data />
|
|
|
+ <subfiles>
|
|
|
+ </subfiles>
|
|
|
+ <subdirs>
|
|
|
+ <subdir>path</subdir>
|
|
|
+ </subdirs>
|
|
|
+ <aggregated-data>
|
|
|
+ <<span class="normalImportance">std.code.complexity</span>>
|
|
|
+ <cyclomatic max="2" total="14.0" avg="0.168674698795" min="0">
|
|
|
+ <<span class="normalImportance">__diff__ max="0" total="0.0" avg="0.0" min="0"</span> />
|
|
|
+ </cyclomatic>
|
|
|
+ </<span class="normalImportance">std.code.complexity</span>>
|
|
|
+ </aggregated-data>
|
|
|
+ </data>
|
|
|
+</export></span>
|
|
|
+ </pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>Check other available options for the tool by executing:</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">export.py</span> <span class="normalImportance">--help</span></pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p><strong>III.</strong> Finally, identify code regions which
|
|
|
+ exceed a specified limit, applying it to all scanned files:</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">limit.py</span> --general.max-limit=<span class="normalImportance">std.code.complexity</span><strong>:</strong><span class="normalImportance">cyclomatic</span><strong>:</strong><span class="normalImportance">7</span><strong> </strong>--
|
|
|
+<span class="lowImportance">/path/to/your/project/ui/notifications.cpp:72: warning: Metric '<span class="normalImportance">std.code.complexity</span>/<span class="normalImportance">cyclomatic</span>' for
|
|
|
+ region 'doFont' exceeds the limit.
|
|
|
+ Metric name : <span class="normalImportance">std.code.complexity</span>/<span class="normalImportance">cyclomatic</span>
|
|
|
+ Region name : doFont
|
|
|
+ Metric value : 10
|
|
|
+ Modified : None
|
|
|
+ Change trend : None
|
|
|
+ Limit : 7
|
|
|
+/path/to/your/project/ui/notifications.cpp:144: warning: Metric '<span class="normalImportance">std.code.complexity</span>/<span class="normalImportance">cyclomatic</span>' for
|
|
|
+ region 'doStyle' exceeds the limit.
|
|
|
+ Metric name : <span class="normalImportance">std.code.complexity</span>/<span class="normalImportance">cyclomatic</span>
|
|
|
+ Region name : doStyle
|
|
|
+ Metric value : 9
|
|
|
+ Modified : None
|
|
|
+ Change trend : None
|
|
|
+ Limit : 7</span></pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>You can limit the scope of analysis by defining paths to
|
|
|
+ directories or files.If you have got results collected for
|
|
|
+ previous version, point out to the file using the corresponding
|
|
|
+ option and the tool will notify about change status:</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">limit.py</span> --general.max-limit=std.code.complexity<strong>:</strong>cyclomatic<strong>:</strong>7
|
|
|
+ --general.db-file-prev=<span class="normalImportance">metrixpp-prev.db</span> --
|
|
|
+<span class="lowImportance normalImportance">/path/to/your/project/ui/notifications.cpp:72: warning: Metric 'std.code.complexity/cyclomatic' for
|
|
|
+ region 'doFont' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity/cyclomatic
|
|
|
+ Region name : doFont
|
|
|
+ Metric value : 10
|
|
|
+ Modified : <span class="normalImportance">True</span>
|
|
|
+ Change trend : <span class="normalImportance">0</span>
|
|
|
+ Limit : 7
|
|
|
+/path/to/your/project/ui/notifications.cpp:144: warning: Metric 'std.code.complexity/cyclomatic' for
|
|
|
+ region 'doStyle' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity/cyclomatic
|
|
|
+ Region name : doStyle
|
|
|
+ Metric value : 9
|
|
|
+ Modified : <span class="normalImportance">True</span>
|
|
|
+ Change trend : <span class="normalImportance">+1</span>
|
|
|
+ Limit : 7</span></pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>Another useful option for this tool helps you to <span
|
|
|
+ class="highImportance">deal with legacy code</span>. It is not
|
|
|
+ unusual if you have got enormous number of warnings enabling
|
|
|
+ new thresholds for the code designed in the past, which has not
|
|
|
+ be profiled/targeted to specific metric limits. By default the
|
|
|
+ tool warns about all code regions, ignoring their change
|
|
|
+ status. You can reconfigure it to one of the following:</p>
|
|
|
+ <ul>
|
|
|
+ <li>warn only about <span class="normalImportance">new</span>
|
|
|
+ code regions (functions, classes):</li>
|
|
|
+ </ul>
|
|
|
|
|
|
- <h4>Dealing Legacy Code</h4>
|
|
|
+ <p><pre>> python <span class="highImportance">limit.py</span> --general.max-limit=std.code.complexity<strong>:</strong>cyclomatic<strong>:</strong>7
|
|
|
+ --general.db-file-prev=metrixpp-prev.db <span class="normalImportance">--general.warn=<strong>new</strong></span> --</pre>
|
|
|
+ </p>
|
|
|
+ <ul>
|
|
|
+ <li>warn about <span class="normalImportance">new</span> code
|
|
|
+ regions and <span class="normalImportance">modifed regions
|
|
|
+ <strong>regressing</strong> the metric</span> (enforces the
|
|
|
+ rule 'leave not worse than it was before'):</li>
|
|
|
+ </ul>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">limit.py</span> --general.max-limit=std.code.complexity<strong>:</strong>cyclomatic<strong>:</strong>7
|
|
|
+ --general.db-file-prev=metrixpp-prev.db <span class="normalImportance">--general.warn=<strong>trend</strong></span> --
|
|
|
+<span class="lowImportance normalImportance">/path/to/your/project/ui/notifications.cpp:144: warning: Metric 'std.code.complexity/cyclomatic' for
|
|
|
+ region 'doStyle' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity/cyclomatic
|
|
|
+ Region name : doStyle
|
|
|
+ Metric value : 9
|
|
|
+ Modified : <span class="normalImportance">True</span>
|
|
|
+ Change trend : <span class="normalImportance"><strong>+1</strong></span>
|
|
|
+ Limit : 7</span></pre>
|
|
|
+ </p>
|
|
|
+ <ul>
|
|
|
+ <li>warn about <span class="normalImportance">new</span> and
|
|
|
+ <span class="normalImportance">all modified regions</span>
|
|
|
+ (motivates for refactoring of legacy code): </li>
|
|
|
+ </ul>
|
|
|
|
|
|
- <p>TBD</p>
|
|
|
+ <p><pre>> python <span class="highImportance">limit.py</span> --general.max-limit=std.code.complexity<strong>:</strong>cyclomatic<strong>:</strong>7
|
|
|
+ --general.db-file-prev=metrixpp-prev.db <span class="normalImportance">--general.warn=<strong>touched</strong></span> --
|
|
|
+<span class="lowImportance normalImportance">/path/to/your/project/ui/notifications.cpp:72: warning: Metric 'std.code.complexity/cyclomatic' for
|
|
|
+ region 'doFont' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity/cyclomatic
|
|
|
+ Region name : doFont
|
|
|
+ Metric value : 10
|
|
|
+ Modified : <span class="normalImportance"><strong>True</strong></span>
|
|
|
+ Change trend : <span class="normalImportance">0</span>
|
|
|
+ Limit : 7
|
|
|
+/path/to/your/project/ui/notifications.cpp:144: warning: Metric 'std.code.complexity/cyclomatic' for
|
|
|
+ region 'doStyle' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity/cyclomatic
|
|
|
+ Region name : doStyle
|
|
|
+ Metric value : 9
|
|
|
+ Modified : <strong><span class="normalImportance">True</span></strong>
|
|
|
+ Change trend : <span class="normalImportance">+1</span>
|
|
|
+ Limit : 7</span></pre>
|
|
|
+ </p>
|
|
|
+
|
|
|
+ <p>Check other available options for the tool by executing:</p>
|
|
|
+
|
|
|
+ <p><pre>> python <span class="highImportance">limit.py</span> <span class="normalImportance">--help</span></pre>
|
|
|
+ </p>
|
|
|
|
|
|
<h3 id="Support">Bug Report & Feature Request</h3>
|
|
|
|
|
|
@@ -227,15 +430,51 @@ along with Metrix++. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
|
|
<h4>New Metric</h4>
|
|
|
|
|
|
- <p>TBD</p>
|
|
|
+ <p>Unfortunately, there is no rich documentation at this stage.
|
|
|
+ Briefly, any new plugin starts with creating 2 new files: 'ini'
|
|
|
+ and 'py'. You can copy from other avaialble (for example, <a
|
|
|
+ href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/ext/std/code/complexity.ini">ini</a>
|
|
|
+ and <a
|
|
|
+ href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/ext/std/code/complexity.py">py</a>
|
|
|
+ files for the standard complexity plugin) and impelement the
|
|
|
+ logic related to the new metric.</p>
|
|
|
|
|
|
<h4>New Analysis Tool</h4>
|
|
|
|
|
|
- <p>TBD</p>
|
|
|
+ <p>Unfortunately, there is no rich documentation at this stage.
|
|
|
+ Briefly, database API (class Loader implemented in '<a
|
|
|
+ href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/core/db/loader.py">core.db.loader</a>')
|
|
|
+ is a starting point for any new post-analysis tool. There are 2
|
|
|
+ standard tools (<a
|
|
|
+ href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/export.py">export.py</a>
|
|
|
+ and <a
|
|
|
+ href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/limit.py">limit.py</a>)
|
|
|
+ available which use this API.</p>
|
|
|
|
|
|
<h4>New Language Support</h4>
|
|
|
|
|
|
- <p>TBD</p>
|
|
|
+ <p>Unfortunately, there is no rich documentation at this stage.
|
|
|
+ Briefly:</p>
|
|
|
+ <ul>
|
|
|
+ <li>a plugin is registered in the same way as a plugin for
|
|
|
+ new metric</li>
|
|
|
+ <li>it subscribes to directory reader plugin</li>
|
|
|
+ <li>parses a file in a callback, called by directory
|
|
|
+ reader</li>
|
|
|
+ <li>parser needs to identify markers (like comments, strings,
|
|
|
+ preprocessor) and regions (like functions, classes, etc.)
|
|
|
+ and tell about this to file data object passed as an
|
|
|
+ argument for the callback.</li>
|
|
|
+ </ul>
|
|
|
+
|
|
|
+ <p>Parser for C/C++ language can serve as <a
|
|
|
+ href="http://swi.svn.sourceforge.net/viewvc/swi/mainline/ext/std/code/cpp.py">an
|
|
|
+ example</a>.</p>
|
|
|
+
|
|
|
+ <p>Finally, if there are any questions or enquires, please,
|
|
|
+ feel free to contact <a
|
|
|
+ href="mailto:avkonst@users.sourceforge.net">project
|
|
|
+ administrator</a> by e-mail.</p>
|
|
|
|
|
|
<h4>Source Code Repository</h4>
|
|
|
|
avkonst