123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546 |
- <?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">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/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>
|