commit f7c3e31c75dca5e99e1c1bd4993c6d5fead59d46
parent 12e912a9ec9311fe979ab3abbb0dd9a030061ea1
Author: Kyle Milz <kyle@0x30.net>
Date: Sun, 14 Aug 2016 00:41:03 -0600
man: introduce why citrun-wrap is necessary
Diffstat:
1 file changed, 33 insertions(+), 17 deletions(-)
diff --git a/man/citrun-wrap.1 b/man/citrun-wrap.1
@@ -23,35 +23,47 @@
.Nm
.Ar build_cmd
.Sh DESCRIPTION
-Add instrumentation to any source files compiled by
+C It Run uses source code rewriting, also called instrumentation. The only time
+rewriting can succeed is at software compilation time.
+.Pp
+The
+.Nm
+utility enables rewriting on any source files compiled by
.Ar build_cmd .
-The build command must search
+.Pp
+An important caveat is that
+.Ar build_cmd
+must search
.Ev PATH
when finding compiler executables, which must be one of the following:
.Pp
.Bl -bullet -compact
.It
-clang or clang++
+clang
+.It
+clang++
+.It
+egcc
.It
-egcc or eg++
+eg++
.It
-gcc or g++
+gcc
.It
-cc or c++
+g++
+.It
+cc
+.It
+c++
.El
.Pp
-All instrumentation activity is logged to
-.Pa citrun.log .
-Instrumentation summaries can be generated by the
+All rewriting activity is logged to the
+.Pa citrun.log
+file.
+Human readable summaries can be generated by the
.Xr citrun-check 1
script.
.Pp
-Incremental building is supported. If
-.Ar build_cmd
-fails, fix the problem
-and rerun
-.Nm
-.Ar build_cmd .
+Incremental building is supported.
.Sh FILES
.Bl -tag -width Ds
.It Pa citrun.log
@@ -64,7 +76,7 @@ utility exits with the build command exit code.
.Sh EXAMPLES
Let
.Qq program
-exist. It is:
+be in a project that is:
.Pp
.Bl -bullet -compact
.It
@@ -77,7 +89,7 @@ built with make and make searches PATH for gcc
.Pp
Prepending
.Nm
-to the build command adds instrumentation:
+to the projects build command adds instrumentation:
.Pp
.Dl $ citrun-wrap make
.Pp
@@ -86,6 +98,10 @@ Now see
run:
.Pp
.Dl $ ./program
+.Pp
+If no viewer is running then
+.Xr citrun-gl 1
+is started.
.Sh SEE ALSO
.Xr citrun-check 1 ,
.Xr citrun-term 1
