|
|
@@ -16,7 +16,6 @@
|
|
|
<link href="assets/css/docs.css" rel="stylesheet">
|
|
|
<link href="assets/js/google-code-prettify/prettify.css" rel="stylesheet">
|
|
|
|
|
|
-
|
|
|
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
|
|
|
<!--[if lt IE 9]>
|
|
|
<script src="assets/js/html5shiv.js"></script>
|
|
|
@@ -168,11 +167,12 @@
|
|
|
<li><a href="#download_section"><i class="icon-chevron-right"></i> Download & Install</a></li>
|
|
|
<li><a href="#workflow_collect_section"><i class="icon-chevron-right"></i> Workflow: Collect data</a></li>
|
|
|
<li><a href="#workflow_view_section"><i class="icon-chevron-right"></i> Workflow: View data</a></li>
|
|
|
- <li><a href="#workflow_view_distributions_section"><i class="icon-hand-right"></i> · distributions</a></li>
|
|
|
- <li><a href="#workflow_view_details_section"><i class="icon-hand-right"></i> · details</a></li>
|
|
|
+ <li><a href="#workflow_view_summary_section"><i class="icon-hand-right"></i> · summary & distributions</a></li>
|
|
|
+ <li><a href="#workflow_view_details_section"><i class="icon-hand-right"></i> · details per file/region</a></li>
|
|
|
<li><a href="#workflow_limit_section"><i class="icon-chevron-right"></i> Workflow: Apply thresholds</a></li>
|
|
|
<li><a href="#workflow_limit_hotspots_section"><i class="icon-hand-right"></i> · hotspots</a></li>
|
|
|
- <li><a href="#workflow_limit_suppress_section"><i class="icon-hand-right"></i> · suppressions</a></li>
|
|
|
+ <li><a href="#workflow_limit_control_section"><i class="icon-hand-right"></i> · controlling trends</a></li>
|
|
|
+ <li><a href="#workflow_other_section"><i class="icon-chevron-right"></i> Workflow: Other applications</a></li>
|
|
|
<li><a href="#extend_section"><i class="icon-chevron-right"></i> Create plugin</a></li>
|
|
|
<li><a href="#contribute_section"><i class="icon-chevron-right"></i> Feedback & Contribute</a></li>
|
|
|
</ul>
|
|
|
@@ -387,19 +387,287 @@ file: __global__: comment
|
|
|
<div class="page-header">
|
|
|
<h1>Workflow</h1>
|
|
|
</div>
|
|
|
+ <p>The workflow and application usecases are demonstrated using source code of
|
|
|
+ <a href="http://www.boost.org/doc/libs/1_54_0/doc/html/interprocess.html">boost/interprocess</a> library.
|
|
|
+ Boost versions 1.52 and 1.54 are used and refered below as 'previous' and 'current' accordingly.</p>
|
|
|
<section id="workflow_collect_section">
|
|
|
<h2>Collect data</h2>
|
|
|
- <p>...</p>
|
|
|
+ <p>The first obvious step is to collect the data.
|
|
|
+ The 'collect' tool has got multiple options to enable various metrics plugins.
|
|
|
+ Let's collect number of lines of code and cyclomatic complexity metrics
|
|
|
+ for the previous (1.52.0 version) boost interprocess library. Assuming that 2 versions of boost library
|
|
|
+ are unpacked in the current working directory:</p>
|
|
|
+ <pre>
|
|
|
+> cd boost_1_52_0
|
|
|
+> python "/path/to/metrix++.py" collect --std.code.lines.code --std.code.complexity.cyclomatic -- boost/interprocess
|
|
|
+> cd ../ # return back to working directory
|
|
|
+</pre>
|
|
|
+ <p>The list of arguments after '--' enumerates paths where to read source files.
|
|
|
+ As a result of execution of this command, a file metrixpp.db will be written in the current working directory.
|
|
|
+ It can be redefined with help of --db-file option.</p>
|
|
|
+ <p>Metrix++ has got rich functionality in comparing code bases and reducing processing scope to modified or new code.
|
|
|
+ So, let's collect the same data for the current (1.54.0 version) boost interprocess library.</p>
|
|
|
+ <pre>
|
|
|
+> cd boost_1_54_0
|
|
|
+> python "/path/to/metrix++.py" collect --std.code.lines.code --std.code.complexity.cyclomatic -- boost/interprocess --db-file-prev=../boost_1_52_0/metrixpp.db
|
|
|
+> cd ../ # return back to working directory
|
|
|
+</pre>
|
|
|
+ <p>The option --db-file-prev points out to the file with data collected in the previous step.
|
|
|
+ So, eventually it executed iterative collection. It can speed up the exectuion significantly,
|
|
|
+ depending on amount of changes between two version.</p>
|
|
|
+ <p>Check other options of the collect tool by executing:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" collect --help
|
|
|
+</pre>
|
|
|
</section>
|
|
|
<section id="workflow_view_section">
|
|
|
<h2>View data</h2>
|
|
|
- <p>...</p>
|
|
|
+ </section>
|
|
|
+ <section id="workflow_view_summary_section">
|
|
|
+ <h3>Summary metrics and distribution tables/graphs</h3>
|
|
|
+ <p>It is time to look at the data. The command:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db
|
|
|
+</pre>
|
|
|
+ <p>prints summary metrics, like minimum/maximum, and distribution/frequency tables:</p>
|
|
|
+ <pre>
|
|
|
+:: info: Overall metrics for 'std.code.complexity:cyclomatic' metric
|
|
|
+ Average : 0.652902698283
|
|
|
+ Minimum : 0
|
|
|
+ Maximum : 37
|
|
|
+ Total : 1597.0
|
|
|
+ Distribution : 2446 regions in total (including 0 suppressed)
|
|
|
+ Metric value : Ratio : R-sum : Number of regions
|
|
|
+ 0 : 0.771 : 0.771 : 1886 |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
|
+ 1 : 0.110 : 0.881 : 268 |||||||||||
|
|
|
+ 2 : 0.044 : 0.925 : 108 ||||
|
|
|
+ 3 : 0.025 : 0.949 : 60 ||
|
|
|
+ 4 : 0.016 : 0.966 : 40 ||
|
|
|
+ 5 : 0.007 : 0.973 : 18 |
|
|
|
+ 6 : 0.006 : 0.979 : 14 |
|
|
|
+ 7 : 0.004 : 0.983 : 10
|
|
|
+ 8 : 0.003 : 0.986 : 8
|
|
|
+ 9 : 0.002 : 0.988 : 4
|
|
|
+ 10 : 0.004 : 0.991 : 9
|
|
|
+ 11 : 0.002 : 0.993 : 4
|
|
|
+ 12 : 0.001 : 0.994 : 3
|
|
|
+ 13 : 0.001 : 0.995 : 2
|
|
|
+ 14 : 0.001 : 0.996 : 2
|
|
|
+ 15-16 : 0.001 : 0.997 : 3
|
|
|
+ 17-18 : 0.001 : 0.998 : 3
|
|
|
+ 20 : 0.000 : 0.999 : 1
|
|
|
+ 23-25 : 0.001 : 1.000 : 2
|
|
|
+ 37 : 0.000 : 1.000 : 1
|
|
|
+
|
|
|
+:: info: Overall metrics for 'std.code.lines:code' metric
|
|
|
+ Average : 6.64356984479
|
|
|
+ Minimum : 0
|
|
|
+ Maximum : 201
|
|
|
+ Total : 23970.0
|
|
|
+ Distribution : 3608 regions in total (including 0 suppressed)
|
|
|
+ Metric value : Ratio : R-sum : Number of regions
|
|
|
+ 0-1 : 0.088 : 0.088 : 319 |||||||||
|
|
|
+ 2 : 0.320 : 0.409 : 1155 ||||||||||||||||||||||||||||||||
|
|
|
+ 3 : 0.108 : 0.517 : 390 |||||||||||
|
|
|
+ 4 : 0.081 : 0.598 : 294 ||||||||
|
|
|
+ 5 : 0.080 : 0.678 : 290 ||||||||
|
|
|
+ 6 : 0.061 : 0.739 : 220 ||||||
|
|
|
+ 7 : 0.049 : 0.788 : 176 |||||
|
|
|
+ 8 : 0.030 : 0.818 : 109 |||
|
|
|
+ 9 : 0.025 : 0.843 : 89 ||
|
|
|
+ 10-11 : 0.032 : 0.876 : 117 |||
|
|
|
+ 12-13 : 0.020 : 0.895 : 71 ||
|
|
|
+ 14 : 0.012 : 0.907 : 43 |
|
|
|
+ 15-16 : 0.017 : 0.924 : 61 ||
|
|
|
+ 17-19 : 0.015 : 0.939 : 55 ||
|
|
|
+ 20-22 : 0.013 : 0.952 : 46 |
|
|
|
+ 23-26 : 0.011 : 0.963 : 40 |
|
|
|
+ 27-30 : 0.009 : 0.972 : 33 |
|
|
|
+ 31-39 : 0.009 : 0.981 : 33 |
|
|
|
+ 40-65 : 0.009 : 0.991 : 34 |
|
|
|
+ 66-201 : 0.009 : 1.000 : 33 |
|
|
|
+
|
|
|
+:: info: Directory content:
|
|
|
+ Directory : .
|
|
|
+</pre>
|
|
|
+ <p>The same command with --db-file-prev option enables comparision and change trends are shown in [] brackets:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db
|
|
|
+</pre>
|
|
|
+ <pre>
|
|
|
+:: info: Overall metrics for 'std.code.complexity:cyclomatic' metric
|
|
|
+ Average : 0.652902698283 [+0.00362138411453]
|
|
|
+ Minimum : 0 [+0]
|
|
|
+ Maximum : 37 [+1]
|
|
|
+ Total : 1597.0 [+16.0]
|
|
|
+ Distribution : 2446 [+11] regions in total (including 0 [+0] suppressed)
|
|
|
+ Metric value : Ratio : R-sum : Number of regions
|
|
|
+ 0 : 0.771 : 0.771 : 1886 [+5 ] |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
|
+ 1 : 0.110 : 0.881 : 268 [+4 ] |||||||||||
|
|
|
+ 2 : 0.044 : 0.925 : 108 [+0 ] ||||
|
|
|
+ 3 : 0.025 : 0.949 : 60 [+2 ] ||
|
|
|
+ 4 : 0.016 : 0.966 : 40 [-1 ] ||
|
|
|
+ 5 : 0.007 : 0.973 : 18 [-1 ] |
|
|
|
+ 6 : 0.006 : 0.979 : 14 [+1 ] |
|
|
|
+ 7 : 0.004 : 0.983 : 10 [+1 ]
|
|
|
+ 8 : 0.003 : 0.986 : 8 [+1 ]
|
|
|
+ 9 : 0.002 : 0.988 : 4 [+0 ]
|
|
|
+ 10 : 0.004 : 0.991 : 9 [-2 ]
|
|
|
+ 11 : 0.002 : 0.993 : 4 [+1 ]
|
|
|
+ 12 : 0.001 : 0.994 : 3 [+0 ]
|
|
|
+ 13 : 0.001 : 0.995 : 2 [+0 ]
|
|
|
+ 14 : 0.001 : 0.996 : 2 [+0 ]
|
|
|
+ 15-16 : 0.001 : 0.997 : 3 [-1 ]
|
|
|
+ 17-18 : 0.001 : 0.998 : 3 [+1 ]
|
|
|
+ 20 : 0.000 : 0.999 : 1 [+0 ]
|
|
|
+ 23-25 : 0.001 : 1.000 : 2 [+0 ]
|
|
|
+ 36-37 : 0.000 : 1.000 : 1 [+0 ]
|
|
|
+
|
|
|
+:: info: Overall metrics for 'std.code.lines:code' metric
|
|
|
+ Average : 6.64356984479 [+0.012181964309]
|
|
|
+ Minimum : 0 [+0]
|
|
|
+ Maximum : 201 [+4]
|
|
|
+ Total : 23970.0 [+223.0]
|
|
|
+ Distribution : 3608 [+27] regions in total (including 0 [+0] suppressed)
|
|
|
+ Metric value : Ratio : R-sum : Number of regions
|
|
|
+ 0-1 : 0.088 : 0.088 : 319 [+3 ] |||||||||
|
|
|
+ 2 : 0.320 : 0.409 : 1155 [+9 ] ||||||||||||||||||||||||||||||||
|
|
|
+ 3 : 0.108 : 0.517 : 390 [-3 ] |||||||||||
|
|
|
+ 4 : 0.081 : 0.598 : 294 [+7 ] ||||||||
|
|
|
+ 5 : 0.080 : 0.678 : 290 [+7 ] ||||||||
|
|
|
+ 6 : 0.061 : 0.739 : 220 [-1 ] ||||||
|
|
|
+ 7 : 0.049 : 0.788 : 176 [-2 ] |||||
|
|
|
+ 8 : 0.030 : 0.818 : 109 [-1 ] |||
|
|
|
+ 9 : 0.025 : 0.843 : 89 [+4 ] ||
|
|
|
+ 10-11 : 0.032 : 0.876 : 117 [+9 ] |||
|
|
|
+ 12-13 : 0.020 : 0.895 : 71 [-9 ] ||
|
|
|
+ 14 : 0.012 : 0.907 : 43 [+0 ] |
|
|
|
+ 15-16 : 0.017 : 0.924 : 61 [+0 ] ||
|
|
|
+ 17-19 : 0.015 : 0.939 : 55 [+6 ] ||
|
|
|
+ 20-22 : 0.013 : 0.952 : 46 [-3 ] |
|
|
|
+ 23-26 : 0.011 : 0.963 : 40 [+2 ] |
|
|
|
+ 27-30 : 0.009 : 0.972 : 33 [-3 ] |
|
|
|
+ 31-39 : 0.009 : 0.981 : 33 [+0 ] |
|
|
|
+ 40-65 : 0.009 : 0.991 : 34 [+1 ] |
|
|
|
+ 66-201 : 0.009 : 1.000 : 33 [+1 ] |
|
|
|
+
|
|
|
+:: info: Directory content:
|
|
|
+ Directory : .
|
|
|
+</pre>
|
|
|
+ <h4>Reducing analysis scope</h4>
|
|
|
+ <p>There are two ways to reduce the analysis scope for the view tool. The first is to enumerate paths of interest.
|
|
|
+ For example, the following command reduces scope to 'allocators' sub-directory within the processed code.</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db -- ./boost/interprocess/allocators
|
|
|
+</pre>
|
|
|
+ <p>The second is to specify --scope-mode option, which instructs the tool to process only modified and/or new files/regions.
|
|
|
+ For example, view the summary metrics for all modified and new regions:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db --scope-mode=touched
|
|
|
+</pre>
|
|
|
+ <pre>
|
|
|
+:: info: Overall metrics for 'std.code.complexity:cyclomatic' metric
|
|
|
+ Average : 1.84924623116 [-0.0230941943761]
|
|
|
+ Minimum : 0 [+0]
|
|
|
+ Maximum : 37 [+1]
|
|
|
+ Total : 368.0 [+16.0]
|
|
|
+ Distribution : 199 [+11] regions in total (including 0 [+0] suppressed)
|
|
|
+ Metric value : Ratio : R-sum : Number of regions
|
|
|
+ 0 : 0.608 : 0.608 : 121 [+5 ] |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
|
+ 1 : 0.131 : 0.739 : 26 [+4 ] |||||||||||||
|
|
|
+ 2 : 0.070 : 0.809 : 14 [+0 ] |||||||
|
|
|
+ 3 : 0.060 : 0.869 : 12 [+2 ] ||||||
|
|
|
+ 4 : 0.015 : 0.884 : 3 [-1 ] ||
|
|
|
+ 5 : 0.015 : 0.899 : 3 [-1 ] ||
|
|
|
+ 6 : 0.005 : 0.905 : 1 [+1 ] |
|
|
|
+ 7 : 0.015 : 0.920 : 3 [+1 ] ||
|
|
|
+ 8 : 0.015 : 0.935 : 3 [+1 ] ||
|
|
|
+ 9 : 0.010 : 0.945 : 2 [+0 ] |
|
|
|
+ 10 : 0.010 : 0.955 : 2 [-2 ] |
|
|
|
+ 11 : 0.005 : 0.960 : 1 [+1 ] |
|
|
|
+ 12 : 0.005 : 0.965 : 1 [+0 ] |
|
|
|
+ 13 : 0.005 : 0.970 : 1 [+0 ] |
|
|
|
+ 16 : 0.005 : 0.975 : 1 [-1 ] |
|
|
|
+ 17 : 0.005 : 0.980 : 1 [+0 ] |
|
|
|
+ 18 : 0.010 : 0.990 : 2 [+1 ] |
|
|
|
+ 20 : 0.005 : 0.995 : 1 [+0 ] |
|
|
|
+ 36-37 : 0.005 : 1.000 : 1 [+0 ] |
|
|
|
+
|
|
|
+:: info: Overall metrics for 'std.code.lines:code' metric
|
|
|
+ Average : 15.9645390071 [-0.815853149771]
|
|
|
+ Minimum : 0 [+0]
|
|
|
+ Maximum : 201 [+6]
|
|
|
+ Total : 4502.0 [+223.0]
|
|
|
+ Distribution : 282 [+27] regions in total (including 0 [+0] suppressed)
|
|
|
+ Metric value : Ratio : R-sum : Number of regions
|
|
|
+ 0-1 : 0.053 : 0.053 : 15 [+3 ] |||||
|
|
|
+ 2 : 0.124 : 0.177 : 35 [+9 ] ||||||||||||
|
|
|
+ 3 : 0.053 : 0.230 : 15 [-3 ] |||||
|
|
|
+ 4 : 0.060 : 0.291 : 17 [+7 ] ||||||
|
|
|
+ 5 : 0.089 : 0.379 : 25 [+7 ] |||||||||
|
|
|
+ 6 : 0.060 : 0.440 : 17 [-1 ] ||||||
|
|
|
+ 7 : 0.050 : 0.489 : 14 [-2 ] |||||
|
|
|
+ 8-9 : 0.074 : 0.564 : 21 [+3 ] |||||||
|
|
|
+ 10 : 0.035 : 0.599 : 10 [+5 ] ||||
|
|
|
+ 11 : 0.082 : 0.681 : 23 [+4 ] ||||||||
|
|
|
+ 12-13 : 0.043 : 0.723 : 12 [-9 ] ||||
|
|
|
+ 14-15 : 0.039 : 0.762 : 11 [-1 ] ||||
|
|
|
+ 16-18 : 0.028 : 0.791 : 8 [+4 ] |||
|
|
|
+ 19-22 : 0.039 : 0.830 : 11 [+0 ] ||||
|
|
|
+ 23-26 : 0.039 : 0.869 : 11 [+2 ] ||||
|
|
|
+ 27-32 : 0.028 : 0.897 : 8 [-3 ] |||
|
|
|
+ 38-50 : 0.025 : 0.922 : 7 [+0 ] ||
|
|
|
+ 51-69 : 0.025 : 0.947 : 7 [+1 ] ||
|
|
|
+ 71-100 : 0.032 : 0.979 : 9 [+2 ] |||
|
|
|
+ 101-201 : 0.021 : 1.000 : 6 [-1 ] ||
|
|
|
+
|
|
|
+:: info: Directory content:
|
|
|
+ Directory : .
|
|
|
+</pre>
|
|
|
+ </section>
|
|
|
+ <section id="workflow_view_details_section">
|
|
|
+ <h3>Detailed metrics per file/region</h3>
|
|
|
+ <p>The same view tool can print detailed metrics per file and per every region in the specified file.
|
|
|
+ In order to get detailed metrics, enumerate files of interest after '--'. For example:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db -- ./boost/interprocess/detail/managed_open_or_create_impl.hpp
|
|
|
+</pre>
|
|
|
+ <p>produces output similar to this (truncated to make the page shorter):</p>
|
|
|
+ <pre>
|
|
|
+./interprocess/detail/managed_open_or_create_impl.hpp:302: info: Metrics per 'priv_open_or_create' region
|
|
|
+ Region name : priv_open_or_create
|
|
|
+ Region type : function
|
|
|
+ Offsets : 8314-14526
|
|
|
+ Line numbers : 301-467
|
|
|
+ Modified : True
|
|
|
+ std.code.complexity:cyclomatic: 37 [+1]
|
|
|
+ std.code.lines:code: 148 [+4]
|
|
|
+</pre>
|
|
|
+ </section>
|
|
|
+ <section>
|
|
|
+ <h3>More about the viewer</h3>
|
|
|
+ <p>The 'view' command has got an option to alter the output format. It is possible to get the same data
|
|
|
+ in xml pr python disctionary formats. This can be particularly useful for integration of the tool with
|
|
|
+ other applications. For example, an editor may re-collect and show context based metrics when a file is saved.</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" view --format=xml
|
|
|
+</pre>
|
|
|
+ <p>Check other options of the view tool by executing:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" view --help
|
|
|
+</pre>
|
|
|
</section>
|
|
|
<section id="workflow_limit_section">
|
|
|
<h2>Apply thresholds</h2>
|
|
|
<p>...</p>
|
|
|
</section>
|
|
|
- <section id="workflow_limit_suppress_section">
|
|
|
+ <section id="workflow_limit_hotspots_section">
|
|
|
+ <h3>Suppressions</h3>
|
|
|
+ <p>Metrix++ has got suppressions capability. Suppressions are collected from comments in code
|
|
|
+ and used by post-processing tools, like 'limit'. It allows to take fine grained control
|
|
|
+ over false-positive warnings, if there are.</p>
|
|
|
+ </section>
|
|
|
+ <section id="workflow_limit_control_section">
|
|
|
<h3>Suppressions</h3>
|
|
|
<p>Metrix++ has got suppressions capability. Suppressions are collected from comments in code
|
|
|
and used by post-processing tools, like 'limit'. It allows to take fine grained control
|
|
|
@@ -484,6 +752,10 @@ file: __global__: comment
|
|
|
|
|
|
<script src="assets/js/application.js"></script>
|
|
|
|
|
|
+ <script>
|
|
|
+
|
|
|
+ </script>
|
|
|
+
|
|
|
|
|
|
<!-- Analytics
|
|
|
================================================== -->
|
avkonst