<?xml version="1.0" encoding="iso-8859-5"?> <!-- Metrix++, Copyright 2009-2013, Metrix++ Project Link: http://metrixplusplus.sourceforge.net This file is part of Metrix++ Tool. Metrix++ is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License. Metrix++ is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Metrix++. If not, see <http://www.gnu.org/licenses/>. --> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="cache-control" content="max-age=0" /> <meta http-equiv="cache-control" content="no-cache" /> <meta http-equiv="expires" content="0" /> <meta http-equiv="expires" content="Tue, 01 Jan 1980 1:00:00 GMT" /> <meta http-equiv="pragma" content="no-cache" /> <meta http-equiv="content-type" content="text/html; charset=iso-8859-5" /> <title>Metrix++ Project</title> <link href="style.css" rel="stylesheet" type="text/css" /> </head> <body> <table border="0" align="center" cellpadding="0" cellspacing="0" width="800"> <tbody> <tr> <td></td> <td valign="middle"></td> </tr> <tr> <td><img src="logo_project.png" alt="Software Index Project Page" /></td> <td valign="top"> <div align="right"> <p align="center"><a href="http://sourceforge.net/projects/metrixplusplus" class="lowImportance"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=275605&type=13" alt="Get Software Index at SourceForge.net. Fast, secure and Free Open Source software downloads" border="0" /></a></p> <p align="center"><script type="text/javascript" src="http://www.ohloh.net/p/485947/widgets/project_users_logo.js"> </script> </p> </div> </td> </tr> <tr> <td colspan="2"><hr /> </td> </tr> <tr> <td colspan="2" class="highImportance" style="text-align:center;margin-left:auto;margin-right:0;"><a href="#Overview">Overview</a> | <a href="#Download">Download</a> | <a href="#Documentation">Documentation</a> | <a href="#Support">Bur report</a> | <a href="#Support">Feature request</a> | <a href="#Createplugin">Create plugin</a></td> </tr> <tr> <td colspan="2"><hr /> </td> </tr> <tr> <td colspan="2" valign="top"> <table width="100%" border="0" cellspacing="0" cellpadding="10"> <tbody> <tr> <td valign="top"><h3 id="Overview">Overview</h3> <p><span class="normalImportance">Metrix++</span> is the platform to collect and analyse code metrics.</p> <ul> <li>It has got plugin based architecture, so it is easy to add support for new languages and/or define new metrics and/or create new pre- and post-processing tools.</li> <li>Every metric has got 'turn-on' and other configuration options.</li> <li>There is no predefined thresholds for metrics or rules. You can choose and configure any limit you want.</li> <li>It scales well and support big code bases. For example initial parsing of about 10000 files takes 2-3 minutes on average PC, and ONLY 10-20 seconds for iterative re-run. Reporting, analysis and other postprocessings of results take few seconds.</li> <li>It can compare results for 2 code snapshots (collections) and differentiate added regions (classes, functions, etc.), modified regions and unchanged regions.</li> <li>As a result, easy deployment is guaranteed into legacy software, helping you to deal with legacy code effiently - either enforce 'make it [legacy code] not worse' or 're-factor if it is touched' policies.</li> </ul> <h4>Standard Plugins</h4> <p>The distributive includes a set of standard plugins:</p> <ul> <li><h4>Code parsers</h4> <ul> <li><span class="normalImportance">C/C++</span> parser recognises definition of namespaces, definition of classes/structs (including enclosed in functions), templates and definition of functions/operators</li> <li><span class="normalImportance">C#</span> parser recognises definition of namespaces, definition of classes/structs (including enclosed in functions), interfaces, generics, definition of functions/operators</li> <li><span class="normalImportance">Java</span> parser recognises definition of classes (including local in functions), interfaces, generics and functions</li> </ul> </li> <li><h4>Metrics</h4> <ul> <li><span class="normalImportance">cyclomatic complexity</span> (by McCabe) per function <span class="lowImportance">[supports C/C++, C#, Java languages]</span></li> <li><span class="normalImportance">processing errors</span> per file <span class="lowImportance">[supports any file type]</span></li> <li><span class="normalImportance">processing time</span> per file <span class="lowImportance">[supports any file type]</span></li> </ul> </li> <li><h4>Analysis tools</h4> <ul> <li><span class="normalImportance">export</span> - exporter to xml, python or plain text of detailed information per file and/or aggregated information per file or directory <span class="lowImportance">[aggregated data includes <span class="normalImportance">sum</span>, <span class="normalImportance">maximum</span>, <span class="normalImportance">minimum</span>, <span class="normalImportance">average</span> within a subset of selected files or directories]</span></li> <li><span class="normalImportance">limit</span> - a tool to report regions exceeding speified thresholds, which are configurable <span class="lowImportance">[output is plain text with metadata compatible with gcc compiler warning messages]</span></li> <li><span class="normalImportance">info</span> - a tool to show file metadata, such as properties, namespaces and fields recorded, files processed</li> </ul> </li> </ul> <h3 id="Download">Download & Installation</h3> <p>For the installation of the <span class="normalImportance">Metrix++</span> <a href="http://sourceforge.net/projects/metrixplusplus/files/">download the archive</a> with <span class="highImportance">the latest stable version</span> and unpack it to some folder. Corresponding checkout from the version control system:</p> <p><pre>> svn checkout <a href="https://metrixplusplus.svn.sourceforge.net/svnroot/metrixplusplus/releases/">https://metrixplusplus.svn.sourceforge.net/svnroot/metrixplusplus/releases/</a><version></pre> </p> <p>Alternatively, there is an option to <a href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/?view=tar">download tarball file</a> with <span class="highImportance">the latest development version</span> of the tool or checkout this version of <a href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/">source code</a> from the version conrol system:</p> <p><pre>> svn checkout <a href="https://metrixplusplus.svn.sourceforge.net/svnroot/metrixplusplus/mainline/">https://metrixplusplus.svn.sourceforge.net/svnroot/metrixplusplus/mainline/</a></pre> </p> <h4>Prerequisites:</h4> <p>Python Runtime Environment (version 2.7.* or later, version 3.* has not been tested)</p> <h4>License:</h4> <p>This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 3 of the License.</p> <p>This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.</p> <p>You should have received a copy of the GNU General Public License along with the <span class="normalImportance">Metriix++</span>; if not, contact <a href="mailto:avkonst@users.sourceforge.net">Project Administrator</a> and write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.</p> <h3 id="Documentation">Documentation</h3> <p>Tools are self-descriptive and have got comprehensive context help. Type in the command line: python metrixpp.py <tool-name> --help</p> <h4>Known Limitations</h4> <p>Check 'doc/limitations.txt' file distributed with the tool or browse for recent version <a href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/doc/limitations.txt">online</a>.</p> <h4>Basic Workflow</h4> <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 metixpp.py <span class="highImportance">collect</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, collection 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 metrixpp.py <span class="highImportance">collect</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 the current working directory. Check other available options for the tool by executing:</p> <p><pre>> python metrixpp.py <span class="highImportance">collect</span> <span class="normalImportance">--help</span></pre> </p> <p><strong>II.</strong> Secondly, export data using export tool.</p> <p><pre>> python metrixpp.py <span class="highImportance">export</span> --general.format=<span class="normalImportance">xml</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>> </aggregated-data> </data> </export></span> </pre> </p> <p>By default, it exports all aggregated data for all files scanned. 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. It is also possible to change output format too.</p> <p><pre>> python metrixpp.py <span class="highImportance">export</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"> ...</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 metrixpp.py <span class="highImportance">export</span> --general.format=<span class="normalImportance">xml</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 metrixpp.py <span class="highImportance">export</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 metrixpp.py <span class="highImportance">limit</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 inform about change trends:</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 normal that you have got enormous number of warnings 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> <p><pre>> python metrixpp.py <span class="highImportance">limit</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 metrixpp.py <span class="highImportance">limit</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><pre>> python metrixpp.py <span class="highImportance">limit</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 metrixpp.py <span class="highImportance">limit</span> <span class="normalImportance">--help</span></pre> </p> <h3 id="Support">Bug Report & Feature Request</h3> <p>Any types of enquiries are welcomed by e-mail to <a href="mailto:avkonst@users.sourceforge.net">project administrator</a>.</p> <h3 id="Createplugin">Create Plugin</h3> <p>Please, consider to join the project and <span class="normalImportance">contribute to the development</span> of the engine or <span class="normalImportance">include you plugins into the standard set</span> of plugins distributed together with this tool. Contact <a href="mailto:avkonst@users.sourceforge.net">project administrator</a> by e-mail.</p> <h4>New Metric</h4> <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://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/ext/std/code/complexity.ini">ini</a> and <a href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/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>Unfortunately, there is no rich documentation at this stage. Briefly, database API (class Loader implemented in '<a href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/core/db/loader.py">mpp.db.loader</a>') is a starting point for any new post-analysis tool. There are 2 standard tools (<a href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/tools/export.py">export</a> and <a href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/tools/limit.py">limit</a>) available which use this API.</p> <h4>New Language Support</h4> <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://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/ext/std/code/cpp.py">an example</a>. There useful options and tools are avaialble for trobuleshooting purposes during development:</p> <ul> <li><span class="normalImportance">metrixpp.py debug</span> tool is helpful troubleshooting tool. In mode 'dumphtml' it generates html code showing code highlightings</li> <li><span class="normalImportance">--general.nest-regions</span> for export tool forces exporting of code structure in tree format. It can be helpful for analysis of parser's internals</li> <li><span class="normalImportance">--general.log-level</span>=GENERAL.LOG_LEVEL for any tool is helpful to trace execution </li> </ul> <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> <p>Source code is in the Subversion repository <a href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/">(browse online)</a> used by the project. Corresponding checkout command is the following:</p> <p><pre>> svn checkout <a href="https://metrixplusplus.svn.sourceforge.net/svnroot/metrixplusplus/mainline/">https://metrixplusplus.svn.sourceforge.net/svnroot/metrixplusplus/mainline/</a></pre> </p> <h4></h4> </td> </tr> </tbody> </table> <hr /> </td> </tr> <tr> <td colspan="2"> <div align="center"> <p align="right">Copyright <strong>© </strong>2009 - 2013<br /> <a href="mailto:avkonst@users.sourceforge.net"><span class="normalImportance">Metrix++</span> Project</a></p> <p align="right">License: <a href="http://www.gnu.org/licenses/gpl.txt">GPL</a></p> </div> </td> </tr> </tbody> </table> </body> </html>