commit 515296c7eb0d89c5358795d10055d0440265901d
parent 78b0d98544d1b540319775ba393ba3a1b1a42dda
Author: Kyle Milz <kyle@0x30.net>
Date: Sun, 14 Aug 2016 22:37:44 -0600
www: sync
Diffstat:
2 files changed, 91 insertions(+), 21 deletions(-)
diff --git a/www/man/citrun-check.1.html b/www/man/citrun-check.1.html
@@ -29,7 +29,7 @@ CITRUN-CHECK(1)</td>
</tbody>
</table>
<div class="section">
-<h1 id="NAME">NAME</h1> <b class="name">citrun-check</b> — <span class="desc">check directories for instrumentation artifacts</span></div>
+<h1 id="NAME">NAME</h1> <b class="name">citrun-check</b> — <span class="desc">check directories for log files</span></div>
<div class="section">
<h1 id="SYNOPSIS">SYNOPSIS</h1><table class="synopsis">
<col style="width: 12.00ex;"/>
@@ -45,22 +45,78 @@ CITRUN-CHECK(1)</td>
</table>
</div>
<div class="section">
-<h1 id="DESCRIPTION">DESCRIPTION</h1> The <b class="name">citrun-check</b> script recursively checks either <i class="arg">dir</i> or the current working directory for instrumentation artifacts.<div class="spacer">
+<h1 id="DESCRIPTION">DESCRIPTION</h1> The <b class="name">citrun-check</b> script recursively checks either <i class="arg">dir</i>, if given, or the current working directory for <i class="file">citrun.log</i> files created by the rewrite tool.<div class="spacer">
</div>
-A summary is printed showing detailed counts of important events. The following is an example of what the output looks like:<div class="spacer">
+When <b class="name">citrun-check</b> does not have its stdout redirected it prints a “Checking” line that adds a single period for every file processed.<div class="spacer">
+</div>
+Once checking is complete two sections are printed. The text below shows the output of <b class="name">citrun-check</b> after <a class="link-man" href="citrun-wrap.1.html">citrun-wrap(1)</a> had been used to instrument a simple project:<div class="spacer">
</div>
<pre style="margin-left: 5.00ex;" class="lit display">
-Checking '/usr/ports/pobj/spidermonkey-24.2.0/'...
- 3 Log files found
- 185 Calls to the instrumentation tool
- 117 Forked compilers
- 97 Instrumentation successes
- 19 Instrumentation failures (false positive)
- 1 Instrumentation failures (true positive)
- 60 Application link commands</pre>
+Checking '/home/kyle/test' ..done
+
+Summary:
+ 1 Calls to the rewrite tool
+ 1 Source files used as input
+ 1 Application link commands
+ 1 Rewrite successes
+ 1 Rewritten source compile successes
+
+Totals:
+ 6 Lines of source code
+ 53 Milliseconds spent rewriting source
+ 1 Functions called 'main'
+ 1 Function definitions
+ 1 Return statement values
+ 3 Total statements</pre>
<div class="spacer">
</div>
-The value of “Instrumentation failures (true positive)” is important. If this value is more than 0 it means that instrumentation failed but a native compile of the same source succeeded.</div>
+The first section is a summary. It has counts that are related to source files and source compilation. The most important counts are in this section.<div class="spacer">
+</div>
+The second section contains rewriting totals. These counts are related to individual source code elements that were possibly rewritten during a previous <a class="link-man" href="citrun-wrap.1.html">citrun-wrap(1)</a> session.</div>
+<div class="section">
+<h1 id="SUMMARY_COUNTS">SUMMARY COUNTS</h1> The summary section contains the most important counts. The following table describes each of them in detail:<dl style="margin-top: 0.00em;margin-bottom: 0.00em;" class="list list-tag">
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Calls to the rewrite tool”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+The total number of times <a class="link-man" href="citrun-inst.1.html">citrun-inst(1)</a> was called.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Source files used as input”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+The total number of C/C++ source files that had rewriting attempted on them.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Application link commands”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+Number of link commands detected and modified to include the runtime.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Rewrite parse {warnings,errors}”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+The total number of parsing problems the rewriter had.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Rewrite successes”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+The number of times the rewriter successfully transformed the entire source file.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Rewrite failures (False Positive)”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+The number of times the rewriter encountered a fatal error however the native compiler also failed to compile the same code.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Rewrite failures (True Positive!)”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+The number of times the rewriter encountered a fatal error but the native compiler succeeded on the same code. This is bad.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Rewritten source compile successes”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+The number of times the rewritten source file is processed successfully by the native compiler.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Rewritten source compile failures (False Positive)”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+Similar to rewrite failure false positives, the number of times the native compiler fails on both the rewritten source and the original source.</dd>
+<dt class="list-tag" style="margin-top: 1.00em;">
+“Rewritten source compile failures (True Positive!)”</dt>
+<dd class="list-tag" style="margin-left: 6.00ex;">
+The number of times the native compiler fails on the rewritten source and succeeds on the original source. This is bad.</dd>
+</dl>
+</div>
<div class="section">
<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun-check</b> utility exits 0 on success, and >0 if an error occurs.</div>
<div class="section">
diff --git a/www/man/citrun-wrap.1.html b/www/man/citrun-wrap.1.html
@@ -45,23 +45,35 @@ CITRUN-WRAP(1)</td>
</table>
</div>
<div class="section">
-<h1 id="DESCRIPTION">DESCRIPTION</h1> Add instrumentation to any source files compiled by <i class="arg">build_cmd</i>. The build command must search <span class="env">PATH</span> when finding compiler executables, which must be one of the following:<div class="spacer">
+<h1 id="DESCRIPTION">DESCRIPTION</h1> C It Run uses source code rewriting, also called instrumentation. The only time rewriting can succeed is at software compilation time.<div class="spacer">
+</div>
+The <b class="name">citrun-wrap</b> utility enables rewriting on any source files compiled by <i class="arg">build_cmd</i>.<div class="spacer">
+</div>
+An important caveat is that <i class="arg">build_cmd</i> must search <span class="env">PATH</span> when finding compiler executables, which must be one of the following:<div class="spacer">
</div>
<ul style="margin-top: 0.00em;margin-bottom: 0.00em;" class="list list-bul">
<li class="list-bul" style="margin-top: 0.00em;">
-clang or clang++</li>
+clang</li>
+<li class="list-bul" style="margin-top: 0.00em;">
+clang++</li>
+<li class="list-bul" style="margin-top: 0.00em;">
+egcc</li>
<li class="list-bul" style="margin-top: 0.00em;">
-egcc or eg++</li>
+eg++</li>
<li class="list-bul" style="margin-top: 0.00em;">
-gcc or g++</li>
+gcc</li>
<li class="list-bul" style="margin-top: 0.00em;">
-cc or c++</li>
+g++</li>
+<li class="list-bul" style="margin-top: 0.00em;">
+cc</li>
+<li class="list-bul" style="margin-top: 0.00em;">
+c++</li>
</ul>
<div class="spacer">
</div>
-All instrumentation activity is logged to <i class="file">citrun.log</i>. Instrumentation summaries can be generated by the <a class="link-man" href="citrun-check.1.html">citrun-check(1)</a> script.<div class="spacer">
+Because the warnings and errors from the rewrite tool will look indiscernible from the warnings and errors generated by the native compiler, all rewriting activity is logged to the <i class="file">citrun.log</i> file. Human readable summaries can be generated by the <a class="link-man" href="citrun-check.1.html">citrun-check(1)</a> script.<div class="spacer">
</div>
-Incremental building is supported. If <i class="arg">build_cmd</i> fails, fix the problem and rerun <b class="name">citrun-wrap</b> <i class="arg">build_cmd</i>.</div>
+Incremental building is supported, but mixing object files created by different versions of <b class="name">citrun-wrap</b> is not.</div>
<div class="section">
<h1 id="FILES">FILES</h1><dl style="margin-top: 0.00em;margin-bottom: 0.00em;" class="list list-tag">
<dt class="list-tag" style="margin-top: 1.00em;">
@@ -73,7 +85,7 @@ Instrumentation log.</dd>
<div class="section">
<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="name">citrun-wrap</b> utility exits with the build command exit code.</div>
<div class="section">
-<h1 id="EXAMPLES">EXAMPLES</h1> Let “program” exist. It is:<div class="spacer">
+<h1 id="EXAMPLES">EXAMPLES</h1> Let “program” be in a project that is:<div class="spacer">
</div>
<ul style="margin-top: 0.00em;margin-bottom: 0.00em;" class="list list-bul">
<li class="list-bul" style="margin-top: 0.00em;">
@@ -85,7 +97,7 @@ built with make and make searches PATH for gcc</li>
</ul>
<div class="spacer">
</div>
-Prepending <b class="name">citrun-wrap</b> to the build command adds instrumentation:<div class="spacer">
+Prepending <b class="name">citrun-wrap</b> to the projects build command adds instrumentation:<div class="spacer">
</div>
<blockquote style="margin-top: 0.00em;margin-bottom: 0.00em;">
<div class="display">
@@ -99,7 +111,9 @@ Now see “program” run:<div class="spacer">
<div class="display">
<code class="lit">$ ./program</code></div>
</blockquote>
+<div class="spacer">
</div>
+If no viewer is running then <a class="link-man" href="citrun-gl.1.html">citrun-gl(1)</a> is started.</div>
<div class="section">
<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun-check.1.html">citrun-check(1)</a>, <a class="link-man" href="citrun-term.1.html">citrun-term(1)</a></div>
<table class="foot">
