citrun

watch C/C++ source code execute
Log | Files | Refs | LICENSE

commit 6750db1a57b632e47ffca82cc469120ef9abf6a4
parent 71e4dc74794e439850003caf9920ec5d7ff10294
Author: Kyle Milz <kyle@0x30.net>
Date:   Sun, 25 Dec 2016 14:34:56 -0700

www: regen man pages

Diffstat:
Mwww/index.html | 10+++++-----
Dwww/man/citrun-check.1.html | 117-------------------------------------------------------------------------------
Dwww/man/citrun-gl.1.html | 64----------------------------------------------------------------
Dwww/man/citrun-inst.1.html | 76----------------------------------------------------------------------------
Dwww/man/citrun-term.1.html | 82-------------------------------------------------------------------------------
Dwww/man/citrun-wrap.1.html | 132-------------------------------------------------------------------------------
Awww/man/citrun_check.1.html | 117+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Awww/man/citrun_gl.1.html | 64++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Awww/man/citrun_inst.1.html | 76++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Awww/man/citrun_term.1.html | 82+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Awww/man/citrun_wrap.1.html | 132+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
11 files changed, 476 insertions(+), 476 deletions(-)

diff --git a/www/index.html b/www/index.html @@ -20,7 +20,7 @@ can be easily identified and that execution flow can be summarized at a glance. <p> - <img src="citrun-term.png" alt="screenshot of citrun-term" + <img src="citrun-term.png" alt="screenshot of citrun_term" width="100%" height="auto" /> <p> The C/C++ programming languages are supported on UNIX like systems. </p> @@ -40,10 +40,10 @@ relevance: </p> <ul> - <li><a href="man/citrun-wrap.1.html">citrun-wrap(1)</a> - <li><a href="man/citrun-check.1.html">citrun-check(1)</a> - <li><a href="man/citrun-term.1.html">citrun-term(1)</a> - <li><a href="man/citrun-inst.1.html">citrun-inst(1)</a> + <li><a href="man/citrun_wrap.1.html">citrun_wrap(1)</a> + <li><a href="man/citrun_check.1.html">citrun_check(1)</a> + <li><a href="man/citrun_term.1.html">citrun_term(1)</a> + <li><a href="man/citrun_inst.1.html">citrun_inst(1)</a> </ul> </body> diff --git a/www/man/citrun-check.1.html b/www/man/citrun-check.1.html @@ -1,117 +0,0 @@ -<!DOCTYPE html> -<html> -<head> -<meta charset="utf-8"/> -<style> -table.head, table.foot { width: 100%; } -td.head-rtitle, td.foot-os { text-align: right; } -td.head-vol { text-align: center; } -table.foot td { width: 50%; } -table.head td { width: 33%; } -div.spacer { margin: 1em 0; } -</style> -<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> -<title> -CITRUN-CHECK(1)</title> -</head> -<body> -<div class="mandoc"> -<table class="head"> -<tbody> -<tr> -<td class="head-ltitle"> -CITRUN-CHECK(1)</td> -<td class="head-vol"> -General Commands Manual</td> -<td class="head-rtitle"> -CITRUN-CHECK(1)</td> -</tr> -</tbody> -</table> -<div class="section"> -<h1 id="NAME">NAME</h1> <b class="name">citrun-check</b> &#8212; <span class="desc">check for rewrite activity</span></div> -<div class="section"> -<h1 id="SYNOPSIS">SYNOPSIS</h1><table class="synopsis"> -<col style="width: 12.00ex;"/> -<col/> -<tbody> -<tr> -<td> -<b class="name">citrun-check</b></td> -<td> -[<span class="opt"><b class="flag">-o</b> <i class="arg">output</i></span>] [<span class="opt"><i class="arg">dir</i></span>]</td> -</tr> -</tbody> -</table> -</div> -<div class="section"> -<h1 id="DESCRIPTION">DESCRIPTION</h1> The <b class="name">citrun-check</b> utility recursively checks either <i class="arg">dir</i>, if given, or the current working directory for activity logs created by <a class="link-man" href="citrun-wrap.1.html">citrun-wrap(1)</a>.<div class="spacer"> -</div> -If the <b class="flag">-o</b> option is specified then <b class="name">citrun-check</b> will write to <i class="arg">output</i> instead of standard output.<div class="spacer"> -</div> -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"> -Summary: - 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 Function definitions - 1 Return statement values - 3 Total statements</pre> -<div class="spacer"> -</div> -The first section shows how thoroughly the project was instrumented, while the second section contains rewriting totals.</div> -<div class="section"> -<h1 id="SUMMARY_COUNTS">SUMMARY COUNTS</h1> The most important summary events are failures. Source rewriting can fail for a few reasons and is not always a bad thing.<div class="spacer"> -</div> -The following table lists all possible events and describes them:<dl style="margin-top: 0.00em;margin-bottom: 0.00em;" class="list list-tag"> -<dt class="list-tag" style="margin-top: 1.00em;"> -&#8220;Source files used as input&#8221;</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;"> -&#8220;Application link commands&#8221;</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;"> -&#8220;Rewrite successes&#8221;</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;"> -&#8220;Rewrite failures&#8221;</dt> -<dd class="list-tag" style="margin-left: 6.00ex;"> -Rewriting a source file failed. There are two failure cases, either native parsing the original source file also fails, or, only citrun-inst failed parsing the source file.</dd> -<dt class="list-tag" style="margin-top: 1.00em;"> -&#8220;Rewritten source compile successes&#8221;</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;"> -&#8220;Rewritten source compile failures&#8221;</dt> -<dd class="list-tag" style="margin-left: 6.00ex;"> -Compiling the rewritten source file failed. There are two failure cases, either compiling the original source file also fails or only compiling the rewritten source fails.</dd> -</dl> -</div> -<div class="section"> -<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun-check</b> utility exits&#160;0 on success, and&#160;&gt;0 if an error occurs.</div> -<div class="section"> -<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun-wrap.1.html">citrun-wrap(1)</a></div> -<table class="foot"> -<tbody> -<tr> -<td class="foot-date"> -August 3, 2016</td> -<td class="foot-os"> -OpenBSD 6.0</td> -</tr> -</tbody> -</table> -</div> -</body> -</html> - diff --git a/www/man/citrun-gl.1.html b/www/man/citrun-gl.1.html @@ -1,64 +0,0 @@ -<!DOCTYPE html> -<html> -<head> -<meta charset="utf-8"/> -<style> -table.head, table.foot { width: 100%; } -td.head-rtitle, td.foot-os { text-align: right; } -td.head-vol { text-align: center; } -table.foot td { width: 50%; } -table.head td { width: 33%; } -div.spacer { margin: 1em 0; } -</style> -<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> -<title> -CITRUN-GL(1)</title> -</head> -<body> -<div class="mandoc"> -<table class="head"> -<tbody> -<tr> -<td class="head-ltitle"> -CITRUN-GL(1)</td> -<td class="head-vol"> -General Commands Manual</td> -<td class="head-rtitle"> -CITRUN-GL(1)</td> -</tr> -</tbody> -</table> -<div class="section"> -<h1 id="NAME">NAME</h1> <b class="name">citrun-gl</b> &#8212; <span class="desc">OpenGL viewer</span></div> -<div class="section"> -<h1 id="DESCRIPTION">DESCRIPTION</h1> Multiplexes execution data from any running instrumented programs into an OpenGL window.<div class="spacer"> -</div> -Started instrumented programs will try connecting to <b class="name">citrun-gl</b> when it is running. When that succeeds execution data will appear in the viewer window.<div class="spacer"> -</div> -<b class="name">citrun-gl</b> uses process group information from connected programs to aggregate similar processes together.</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;"> -<i class="file">/tmp/citrun.socket</i></dt> -<dd class="list-tag" style="margin-left: 6.00ex;"> -Listen socket.</dd> -</dl> -</div> -<div class="section"> -<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun-gl</b> utility exits&#160;0 on success, and&#160;&gt;0 if an error occurs.</div> -<div class="section"> -<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun-wrap.1.html">citrun-wrap(1)</a>, <a class="link-man" href="citrun-term.1.html">citrun-term(1)</a></div> -<table class="foot"> -<tbody> -<tr> -<td class="foot-date"> -April 9, 2016</td> -<td class="foot-os"> -OpenBSD 6.0</td> -</tr> -</tbody> -</table> -</div> -</body> -</html> - diff --git a/www/man/citrun-inst.1.html b/www/man/citrun-inst.1.html @@ -1,76 +0,0 @@ -<!DOCTYPE html> -<html> -<head> -<meta charset="utf-8"/> -<style> -table.head, table.foot { width: 100%; } -td.head-rtitle, td.foot-os { text-align: right; } -td.head-vol { text-align: center; } -table.foot td { width: 50%; } -table.head td { width: 33%; } -div.spacer { margin: 1em 0; } -</style> -<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> -<title> -CITRUN-INST(1)</title> -</head> -<body> -<div class="mandoc"> -<table class="head"> -<tbody> -<tr> -<td class="head-ltitle"> -CITRUN-INST(1)</td> -<td class="head-vol"> -General Commands Manual</td> -<td class="head-rtitle"> -CITRUN-INST(1)</td> -</tr> -</tbody> -</table> -<div class="section"> -<h1 id="NAME">NAME</h1> <b class="name">citrun-inst</b> &#8212; <span class="desc">rewrite source code</span></div> -<div class="section"> -<h1 id="SYNOPSIS">SYNOPSIS</h1><table class="synopsis"> -<col style="width: 11.00ex;"/> -<col/> -<tbody> -<tr> -<td> -<b class="name">citrun-inst</b></td> -<td> -<i class="arg">compile_cmd</i></td> -</tr> -</tbody> -</table> -</div> -<div class="section"> -<h1 id="DESCRIPTION">DESCRIPTION</h1> Warning: <b class="name">citrun-inst</b> is not usually called directly. Use <a class="link-man" href="citrun-wrap.1.html">citrun-wrap(1)</a> instead.<div class="spacer"> -</div> -The <b class="name">citrun-inst</b> utility performs source code rewriting. It visits statements in source files and adds extra code to some of them.<div class="spacer"> -</div> -<b class="name">citrun-inst</b> should accept any <i class="arg">compile_cmd</i> that the compilers listed in <a class="link-man" href="citrun-wrap.1.html">citrun-wrap(1)</a> would accept.</div> -<div class="section"> -<h1 id="CALLING_DIRECTLY">CALLING DIRECTLY</h1> When <b class="name">citrun-inst</b> is called directly it only performs its source code rewriting step. That means it does not perform its usual call to compile the (possibly) rewritten source file.<div class="spacer"> -</div> -Calling directly is useful for debugging rewrite failures and rewritten source compile failures.<div class="spacer"> -</div> -In this mode, successfully rewritten source files have &#8220;.citrun&#8221; appended to their file name and diagnostic information is printed to both standard output and <i class="file">citrun.log</i>.</div> -<div class="section"> -<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun-inst</b> utility exits&#160;0 on success, and&#160;&gt;0 if an error occurs.</div> -<div class="section"> -<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun-wrap.1.html">citrun-wrap(1)</a></div> -<table class="foot"> -<tbody> -<tr> -<td class="foot-date"> -August 13, 2016</td> -<td class="foot-os"> -OpenBSD 6.0</td> -</tr> -</tbody> -</table> -</div> -</body> -</html> - diff --git a/www/man/citrun-term.1.html b/www/man/citrun-term.1.html @@ -1,82 +0,0 @@ -<!DOCTYPE html> -<html> -<head> -<meta charset="utf-8"/> -<style> -table.head, table.foot { width: 100%; } -td.head-rtitle, td.foot-os { text-align: right; } -td.head-vol { text-align: center; } -table.foot td { width: 50%; } -table.head td { width: 33%; } -div.spacer { margin: 1em 0; } -</style> -<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> -<title> -CITRUN-TERM(1)</title> -</head> -<body> -<div class="mandoc"> -<table class="head"> -<tbody> -<tr> -<td class="head-ltitle"> -CITRUN-TERM(1)</td> -<td class="head-vol"> -General Commands Manual</td> -<td class="head-rtitle"> -CITRUN-TERM(1)</td> -</tr> -</tbody> -</table> -<div class="section"> -<h1 id="NAME">NAME</h1> <b class="name">citrun-term</b> &#8212; <span class="desc">terminal viewer</span></div> -<div class="section"> -<h1 id="DESCRIPTION">DESCRIPTION</h1> Displays live execution data from running instrumented programs. Note only one connection at a time is supported (for now).<div class="spacer"> -</div> -The <b class="name">citrun-term</b> control keys are &#8220;hjkl&#8221; and have the following effects:<div class="spacer"> -</div> -<dl style="margin-top: 0.00em;margin-bottom: 0.00em;margin-left: 6.00ex;" class="list list-tag"> -<dt class="list-tag" style="margin-top: 0.00em;"> -&#8220;j&#8221;</dt> -<dd class="list-tag"> -Scrolls source down one line</dd> -<dt class="list-tag" style="margin-top: 0.00em;"> -&#8220;k&#8221;</dt> -<dd class="list-tag"> -Scrolls source up one line</dd> -<dt class="list-tag" style="margin-top: 0.00em;"> -&#8220;h&#8221;</dt> -<dd class="list-tag"> -Moves to previous translation unit, if possible</dd> -<dt class="list-tag" style="margin-top: 0.00em;"> -&#8220;l&#8221;</dt> -<dd class="list-tag"> -Moves to next translation unit, if possible</dd> -</dl> -</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;"> -<i class="file">/tmp/citrun.socket</i></dt> -<dd class="list-tag" style="margin-left: 6.00ex;"> -Listen socket.</dd> -</dl> -</div> -<div class="section"> -<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun-term</b> utility exits&#160;0 on success, and&#160;&gt;0 if an error occurs.</div> -<div class="section"> -<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun-gl.1.html">citrun-gl(1)</a></div> -<table class="foot"> -<tbody> -<tr> -<td class="foot-date"> -July 19, 2016</td> -<td class="foot-os"> -OpenBSD 6.0</td> -</tr> -</tbody> -</table> -</div> -</body> -</html> - diff --git a/www/man/citrun-wrap.1.html b/www/man/citrun-wrap.1.html @@ -1,132 +0,0 @@ -<!DOCTYPE html> -<html> -<head> -<meta charset="utf-8"/> -<style> -table.head, table.foot { width: 100%; } -td.head-rtitle, td.foot-os { text-align: right; } -td.head-vol { text-align: center; } -table.foot td { width: 50%; } -table.head td { width: 33%; } -div.spacer { margin: 1em 0; } -</style> -<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> -<title> -CITRUN-WRAP(1)</title> -</head> -<body> -<div class="mandoc"> -<table class="head"> -<tbody> -<tr> -<td class="head-ltitle"> -CITRUN-WRAP(1)</td> -<td class="head-vol"> -General Commands Manual</td> -<td class="head-rtitle"> -CITRUN-WRAP(1)</td> -</tr> -</tbody> -</table> -<div class="section"> -<h1 id="NAME">NAME</h1> <b class="name">citrun-wrap</b> &#8212; <span class="desc">enable rewriting on a build command</span></div> -<div class="section"> -<h1 id="SYNOPSIS">SYNOPSIS</h1><table class="synopsis"> -<col style="width: 11.00ex;"/> -<col/> -<tbody> -<tr> -<td> -<b class="name">citrun-wrap</b></td> -<td> -<i class="arg">build_cmd</i> [<span class="opt"><i class="arg">...</i></span>]</td> -</tr> -</tbody> -</table> -</div> -<div class="section"> -<h1 id="DESCRIPTION">DESCRIPTION</h1> C It Run must rewrite source code to add instrumentation. This process happens at compile time.<div class="spacer"> -</div> -The <b class="name">citrun-wrap</b> utility enables source code rewriting on any files compiled during <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 named 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;"> -c++</li> -<li class="list-bul" style="margin-top: 0.00em;"> -cc</li> -<li class="list-bul" style="margin-top: 0.00em;"> -clang</li> -<li class="list-bul" style="margin-top: 0.00em;"> -clang++</li> -<li class="list-bul" style="margin-top: 0.00em;"> -eg++</li> -<li class="list-bul" style="margin-top: 0.00em;"> -egcc</li> -<li class="list-bul" style="margin-top: 0.00em;"> -g++</li> -<li class="list-bul" style="margin-top: 0.00em;"> -gcc</li> -</ul> -<div class="spacer"> -</div> -The warnings and errors from the rewrite tool are indiscernible from the warnings and errors generated by the native compiler, so all rewriting activity is sent to a <i class="file">citrun.log</i> file. Human readable summaries can be generated by <a class="link-man" href="citrun-check.1.html">citrun-check(1)</a>.<div class="spacer"> -</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;"> -<i class="file">citrun.log</i></dt> -<dd class="list-tag" style="margin-left: 6.00ex;"> -Rewrite activity log.</dd> -</dl> -</div> -<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 &#8220;program&#8221; 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;"> -written in C</li> -<li class="list-bul" style="margin-top: 0.00em;"> -compiled with gcc</li> -<li class="list-bul" style="margin-top: 0.00em;"> -built with make and make searches PATH for gcc</li> -</ul> -<div class="spacer"> -</div> -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"> -<code class="lit">$ citrun-wrap make</code></div> -</blockquote> -<div class="spacer"> -</div> -Now see &#8220;program&#8221; run:<div class="spacer"> -</div> -<blockquote style="margin-top: 0.00em;margin-bottom: 0.00em;"> -<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"> -<tbody> -<tr> -<td class="foot-date"> -April 10, 2016</td> -<td class="foot-os"> -OpenBSD 6.0</td> -</tr> -</tbody> -</table> -</div> -</body> -</html> - diff --git a/www/man/citrun_check.1.html b/www/man/citrun_check.1.html @@ -0,0 +1,117 @@ +<!DOCTYPE html> +<html> +<head> +<meta charset="utf-8"/> +<style> +table.head, table.foot { width: 100%; } +td.head-rtitle, td.foot-os { text-align: right; } +td.head-vol { text-align: center; } +table.foot td { width: 50%; } +table.head td { width: 33%; } +div.spacer { margin: 1em 0; } +</style> +<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> +<title> +CITRUN-CHECK(1)</title> +</head> +<body> +<div class="mandoc"> +<table class="head"> +<tbody> +<tr> +<td class="head-ltitle"> +CITRUN-CHECK(1)</td> +<td class="head-vol"> +General Commands Manual</td> +<td class="head-rtitle"> +CITRUN-CHECK(1)</td> +</tr> +</tbody> +</table> +<div class="section"> +<h1 id="NAME">NAME</h1> <b class="name">citrun_check</b> &#8212; <span class="desc">check for rewrite activity</span></div> +<div class="section"> +<h1 id="SYNOPSIS">SYNOPSIS</h1><table class="synopsis"> +<col style="width: 12.00ex;"/> +<col/> +<tbody> +<tr> +<td> +<b class="name">citrun_check</b></td> +<td> +[<span class="opt"><b class="flag">-o</b> <i class="arg">output</i></span>] [<span class="opt"><i class="arg">dir</i></span>]</td> +</tr> +</tbody> +</table> +</div> +<div class="section"> +<h1 id="DESCRIPTION">DESCRIPTION</h1> The <b class="name">citrun_check</b> utility recursively checks either <i class="arg">dir</i>, if given, or the current working directory for activity logs created by <a class="link-man" href="citrun_wrap.1.html">citrun_wrap(1)</a>.<div class="spacer"> +</div> +If the <b class="flag">-o</b> option is specified then <b class="name">citrun_check</b> will write to <i class="arg">output</i> instead of standard output.<div class="spacer"> +</div> +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"> +Summary: + 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 Function definitions + 1 Return statement values + 3 Total statements</pre> +<div class="spacer"> +</div> +The first section shows how thoroughly the project was instrumented, while the second section contains rewriting totals.</div> +<div class="section"> +<h1 id="SUMMARY_COUNTS">SUMMARY COUNTS</h1> The most important summary events are failures. Source rewriting can fail for a few reasons and is not always a bad thing.<div class="spacer"> +</div> +The following table lists all possible events and describes them:<dl style="margin-top: 0.00em;margin-bottom: 0.00em;" class="list list-tag"> +<dt class="list-tag" style="margin-top: 1.00em;"> +&#8220;Source files used as input&#8221;</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;"> +&#8220;Application link commands&#8221;</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;"> +&#8220;Rewrite successes&#8221;</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;"> +&#8220;Rewrite failures&#8221;</dt> +<dd class="list-tag" style="margin-left: 6.00ex;"> +Rewriting a source file failed. There are two failure cases, either native parsing the original source file also fails, or, only citrun_inst failed parsing the source file.</dd> +<dt class="list-tag" style="margin-top: 1.00em;"> +&#8220;Rewritten source compile successes&#8221;</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;"> +&#8220;Rewritten source compile failures&#8221;</dt> +<dd class="list-tag" style="margin-left: 6.00ex;"> +Compiling the rewritten source file failed. There are two failure cases, either compiling the original source file also fails or only compiling the rewritten source fails.</dd> +</dl> +</div> +<div class="section"> +<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun_check</b> utility exits&#160;0 on success, and&#160;&gt;0 if an error occurs.</div> +<div class="section"> +<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun_wrap.1.html">citrun_wrap(1)</a></div> +<table class="foot"> +<tbody> +<tr> +<td class="foot-date"> +August 3, 2016</td> +<td class="foot-os"> +OpenBSD 6.0</td> +</tr> +</tbody> +</table> +</div> +</body> +</html> + diff --git a/www/man/citrun_gl.1.html b/www/man/citrun_gl.1.html @@ -0,0 +1,64 @@ +<!DOCTYPE html> +<html> +<head> +<meta charset="utf-8"/> +<style> +table.head, table.foot { width: 100%; } +td.head-rtitle, td.foot-os { text-align: right; } +td.head-vol { text-align: center; } +table.foot td { width: 50%; } +table.head td { width: 33%; } +div.spacer { margin: 1em 0; } +</style> +<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> +<title> +CITRUN-GL(1)</title> +</head> +<body> +<div class="mandoc"> +<table class="head"> +<tbody> +<tr> +<td class="head-ltitle"> +CITRUN-GL(1)</td> +<td class="head-vol"> +General Commands Manual</td> +<td class="head-rtitle"> +CITRUN-GL(1)</td> +</tr> +</tbody> +</table> +<div class="section"> +<h1 id="NAME">NAME</h1> <b class="name">citrun_gl</b> &#8212; <span class="desc">OpenGL viewer</span></div> +<div class="section"> +<h1 id="DESCRIPTION">DESCRIPTION</h1> Multiplexes execution data from any running instrumented programs into an OpenGL window.<div class="spacer"> +</div> +Started instrumented programs will try connecting to <b class="name">citrun_gl</b> when it is running. When that succeeds execution data will appear in the viewer window.<div class="spacer"> +</div> +<b class="name">citrun_gl</b> uses process group information from connected programs to aggregate similar processes together.</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;"> +<i class="file">/tmp/citrun.socket</i></dt> +<dd class="list-tag" style="margin-left: 6.00ex;"> +Listen socket.</dd> +</dl> +</div> +<div class="section"> +<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun_gl</b> utility exits&#160;0 on success, and&#160;&gt;0 if an error occurs.</div> +<div class="section"> +<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun_wrap.1.html">citrun_wrap(1)</a>, <a class="link-man" href="citrun_term.1.html">citrun_term(1)</a></div> +<table class="foot"> +<tbody> +<tr> +<td class="foot-date"> +April 9, 2016</td> +<td class="foot-os"> +OpenBSD 6.0</td> +</tr> +</tbody> +</table> +</div> +</body> +</html> + diff --git a/www/man/citrun_inst.1.html b/www/man/citrun_inst.1.html @@ -0,0 +1,76 @@ +<!DOCTYPE html> +<html> +<head> +<meta charset="utf-8"/> +<style> +table.head, table.foot { width: 100%; } +td.head-rtitle, td.foot-os { text-align: right; } +td.head-vol { text-align: center; } +table.foot td { width: 50%; } +table.head td { width: 33%; } +div.spacer { margin: 1em 0; } +</style> +<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> +<title> +CITRUN-INST(1)</title> +</head> +<body> +<div class="mandoc"> +<table class="head"> +<tbody> +<tr> +<td class="head-ltitle"> +CITRUN-INST(1)</td> +<td class="head-vol"> +General Commands Manual</td> +<td class="head-rtitle"> +CITRUN-INST(1)</td> +</tr> +</tbody> +</table> +<div class="section"> +<h1 id="NAME">NAME</h1> <b class="name">citrun_inst</b> &#8212; <span class="desc">rewrite source code</span></div> +<div class="section"> +<h1 id="SYNOPSIS">SYNOPSIS</h1><table class="synopsis"> +<col style="width: 11.00ex;"/> +<col/> +<tbody> +<tr> +<td> +<b class="name">citrun_inst</b></td> +<td> +<i class="arg">compile_cmd</i></td> +</tr> +</tbody> +</table> +</div> +<div class="section"> +<h1 id="DESCRIPTION">DESCRIPTION</h1> Warning: <b class="name">citrun_inst</b> is not usually called directly. Use <a class="link-man" href="citrun_wrap.1.html">citrun_wrap(1)</a> instead.<div class="spacer"> +</div> +The <b class="name">citrun_inst</b> utility performs source code rewriting. It visits statements in source files and adds extra code to some of them.<div class="spacer"> +</div> +<b class="name">citrun_inst</b> should accept any <i class="arg">compile_cmd</i> that the compilers listed in <a class="link-man" href="citrun_wrap.1.html">citrun_wrap(1)</a> would accept.</div> +<div class="section"> +<h1 id="CALLING_DIRECTLY">CALLING DIRECTLY</h1> When <b class="name">citrun_inst</b> is called directly it only performs its source code rewriting step. That means it does not perform its usual call to compile the (possibly) rewritten source file.<div class="spacer"> +</div> +Calling directly is useful for debugging rewrite failures and rewritten source compile failures.<div class="spacer"> +</div> +In this mode, successfully rewritten source files have &#8220;.citrun&#8221; appended to their file name and diagnostic information is printed to both standard output and <i class="file">citrun.log</i>.</div> +<div class="section"> +<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun_inst</b> utility exits&#160;0 on success, and&#160;&gt;0 if an error occurs.</div> +<div class="section"> +<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun_wrap.1.html">citrun_wrap(1)</a></div> +<table class="foot"> +<tbody> +<tr> +<td class="foot-date"> +August 13, 2016</td> +<td class="foot-os"> +OpenBSD 6.0</td> +</tr> +</tbody> +</table> +</div> +</body> +</html> + diff --git a/www/man/citrun_term.1.html b/www/man/citrun_term.1.html @@ -0,0 +1,82 @@ +<!DOCTYPE html> +<html> +<head> +<meta charset="utf-8"/> +<style> +table.head, table.foot { width: 100%; } +td.head-rtitle, td.foot-os { text-align: right; } +td.head-vol { text-align: center; } +table.foot td { width: 50%; } +table.head td { width: 33%; } +div.spacer { margin: 1em 0; } +</style> +<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> +<title> +CITRUN-TERM(1)</title> +</head> +<body> +<div class="mandoc"> +<table class="head"> +<tbody> +<tr> +<td class="head-ltitle"> +CITRUN-TERM(1)</td> +<td class="head-vol"> +General Commands Manual</td> +<td class="head-rtitle"> +CITRUN-TERM(1)</td> +</tr> +</tbody> +</table> +<div class="section"> +<h1 id="NAME">NAME</h1> <b class="name">citrun_term</b> &#8212; <span class="desc">terminal viewer</span></div> +<div class="section"> +<h1 id="DESCRIPTION">DESCRIPTION</h1> Displays live execution data from running instrumented programs. Note only one connection at a time is supported (for now).<div class="spacer"> +</div> +The <b class="name">citrun_term</b> control keys are &#8220;hjkl&#8221; and have the following effects:<div class="spacer"> +</div> +<dl style="margin-top: 0.00em;margin-bottom: 0.00em;margin-left: 6.00ex;" class="list list-tag"> +<dt class="list-tag" style="margin-top: 0.00em;"> +&#8220;j&#8221;</dt> +<dd class="list-tag"> +Scrolls source down one line</dd> +<dt class="list-tag" style="margin-top: 0.00em;"> +&#8220;k&#8221;</dt> +<dd class="list-tag"> +Scrolls source up one line</dd> +<dt class="list-tag" style="margin-top: 0.00em;"> +&#8220;h&#8221;</dt> +<dd class="list-tag"> +Moves to previous translation unit, if possible</dd> +<dt class="list-tag" style="margin-top: 0.00em;"> +&#8220;l&#8221;</dt> +<dd class="list-tag"> +Moves to next translation unit, if possible</dd> +</dl> +</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;"> +<i class="file">/tmp/citrun.socket</i></dt> +<dd class="list-tag" style="margin-left: 6.00ex;"> +Listen socket.</dd> +</dl> +</div> +<div class="section"> +<h1 id="EXIT_STATUS">EXIT STATUS</h1> The <b class="utility">citrun_term</b> utility exits&#160;0 on success, and&#160;&gt;0 if an error occurs.</div> +<div class="section"> +<h1 id="SEE_ALSO">SEE ALSO</h1> <a class="link-man" href="citrun_gl.1.html">citrun_gl(1)</a></div> +<table class="foot"> +<tbody> +<tr> +<td class="foot-date"> +July 19, 2016</td> +<td class="foot-os"> +OpenBSD 6.0</td> +</tr> +</tbody> +</table> +</div> +</body> +</html> + diff --git a/www/man/citrun_wrap.1.html b/www/man/citrun_wrap.1.html @@ -0,0 +1,132 @@ +<!DOCTYPE html> +<html> +<head> +<meta charset="utf-8"/> +<style> +table.head, table.foot { width: 100%; } +td.head-rtitle, td.foot-os { text-align: right; } +td.head-vol { text-align: center; } +table.foot td { width: 50%; } +table.head td { width: 33%; } +div.spacer { margin: 1em 0; } +</style> +<link rel="stylesheet" href="/citrun.css" type="text/css" media="all"/> +<title> +CITRUN-WRAP(1)</title> +</head> +<body> +<div class="mandoc"> +<table class="head"> +<tbody> +<tr> +<td class="head-ltitle"> +CITRUN-WRAP(1)</td> +<td class="head-vol"> +General Commands Manual</td> +<td class="head-rtitle"> +CITRUN-WRAP(1)</td> +</tr> +</tbody> +</table> +<div class="section"> +<h1 id="NAME">NAME</h1> <b class="name">citrun_wrap</b> &#8212; <span class="desc">enable rewriting on a build command</span></div> +<div class="section"> +<h1 id="SYNOPSIS">SYNOPSIS</h1><table class="synopsis"> +<col style="width: 11.00ex;"/> +<col/> +<tbody> +<tr> +<td> +<b class="name">citrun_wrap</b></td> +<td> +<i class="arg">build_cmd</i> [<span class="opt"><i class="arg">...</i></span>]</td> +</tr> +</tbody> +</table> +</div> +<div class="section"> +<h1 id="DESCRIPTION">DESCRIPTION</h1> C It Run must rewrite source code to add instrumentation. This process happens at compile time.<div class="spacer"> +</div> +The <b class="name">citrun_wrap</b> utility enables source code rewriting on any files compiled during <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 named 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;"> +c++</li> +<li class="list-bul" style="margin-top: 0.00em;"> +cc</li> +<li class="list-bul" style="margin-top: 0.00em;"> +clang</li> +<li class="list-bul" style="margin-top: 0.00em;"> +clang++</li> +<li class="list-bul" style="margin-top: 0.00em;"> +eg++</li> +<li class="list-bul" style="margin-top: 0.00em;"> +egcc</li> +<li class="list-bul" style="margin-top: 0.00em;"> +g++</li> +<li class="list-bul" style="margin-top: 0.00em;"> +gcc</li> +</ul> +<div class="spacer"> +</div> +The warnings and errors from the rewrite tool are indiscernible from the warnings and errors generated by the native compiler, so all rewriting activity is sent to a <i class="file">citrun.log</i> file. Human readable summaries can be generated by <a class="link-man" href="citrun_check.1.html">citrun_check(1)</a>.<div class="spacer"> +</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;"> +<i class="file">citrun.log</i></dt> +<dd class="list-tag" style="margin-left: 6.00ex;"> +Rewrite activity log.</dd> +</dl> +</div> +<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 &#8220;program&#8221; 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;"> +written in C</li> +<li class="list-bul" style="margin-top: 0.00em;"> +compiled with gcc</li> +<li class="list-bul" style="margin-top: 0.00em;"> +built with make and make searches PATH for gcc</li> +</ul> +<div class="spacer"> +</div> +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"> +<code class="lit">$ citrun_wrap make</code></div> +</blockquote> +<div class="spacer"> +</div> +Now see &#8220;program&#8221; run:<div class="spacer"> +</div> +<blockquote style="margin-top: 0.00em;margin-bottom: 0.00em;"> +<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"> +<tbody> +<tr> +<td class="foot-date"> +April 10, 2016</td> +<td class="foot-os"> +OpenBSD 6.0</td> +</tr> +</tbody> +</table> +</div> +</body> +</html> +