| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543 | <?xml version="1.0" encoding="iso-8859-5"?><!--Metrix++, Copyright 2009-2013, Metrix++ ProjectLink: http://metrixplusplus.sourceforge.netThis file is part of Metrix++ Tool.Metrix++ is free software: you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe 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 ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.You should have received a copy of the GNU General Public Licensealong 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 to 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                    summary results and exceeded limits is less than 1 - 10                    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 'leave it not worse than it was before' rule                    or motivate re-factoring.</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) and                        definition of functions/operators </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++                      language]</span></li>                      <li><span class="normalImportance">mismatched                        brackets</span> '{}'' per file <span                        class="lowImportance">[supports C/C++                      language]</span></li>                      <li><span class="normalImportance">processing time</span>                        per file <span class="lowImportance">[supports any                        file]</span></li>                    </ul>                  </li>                  <li><h4>Analysis tools</h4>                    <ul>                      <li><span class="normalImportance">export.py</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.py</span> - a                        tool to report regions exceeding speified thresholds,                        which are configurable (output is plain text with                        metadata compatible with gcc compiler warning                      messages)</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.0 or later, version                3.0 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                <tool-name>.py --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 <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, 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 <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 the 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>                <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><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>                <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">core.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/export.py">export.py</a>                and <a                href="http://metrixplusplus.svn.sourceforge.net/viewvc/metrixplusplus/mainline/limit.py">limit.py</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 are avaialble for                trobuleshooting purposes during development:</p>                <ul>                  <li><span                    class="normalImportance">--std.code.dumper.on</span> If the                    option is set (True), HTML files are generated for every                    parsed file with code showing identified markers and                    regions (functions only) [default: False]</li>                  <li><span class="normalImportance">--std.code.test.on</span>                    Enables test plugin. Currently dumps to stdout structure of                    the code (tree of namespaces, classes and functions                    identified) after processing by a parser (for development                    purposes) [default: False]</li>                  <li><span                    class="normalImportance">--general.log-level</span>=GENERAL.LOG_LEVEL                    Defines log level. Possible values are                    'DEBUG','INFO','WARNING' or 'ERROR' [default: INFO]</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>
 |