commit 2b22ade39aa603848e784e04aaf4f7f9e4a0e76f
parent faa1335e7682b01f08e0fed5cd04aecc238c7fce
Author: Kyle Milz <milz@imac.0x30.net>
Date: Wed, 3 Mar 2021 22:24:06 -0800
man: suspicious changes..
Diffstat:
3 files changed, 73 insertions(+), 55 deletions(-)
diff --git a/man/citrun_inst.1 b/man/citrun_inst.1
@@ -32,8 +32,10 @@ instead.
.Pp
The
.Nm
-utility performs source code rewriting. It visits statements in source files and
-adds extra code to some of them.
+utility performs source code rewriting. It visits statements in source files
+adding extra code to some of them.
+.Pp
+When a link command is detected extra arguments are added to the command line.
.Pp
.Nm
should accept any
diff --git a/man/citrun_report.1 b/man/citrun_report.1
@@ -1,5 +1,5 @@
.\"
-.\" Copyright (c) 2016 Kyle Milz <kyle@0x30.net>
+.\" Copyright (c) 2016, 2017 Kyle Milz <kyle@0x30.net>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
@@ -13,61 +13,68 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: August 3 2016 $
-.Dt CITRUN_CHECK 1
+.Dd $Mdocdate: September 18 2017 $
+.Dt CITRUN_REPORT 1
.Os
.Sh NAME
-.Nm citrun_check
-.Nd check for rewrite activity
+.Nm citrun_report
+.Nd create instrumentation reports
.Sh SYNOPSIS
.Nm
-.Op Ar dir
+.Op Ar citrun.log
+.Op Ar ...
.Sh DESCRIPTION
The
.Nm
-utility searches for activity logs created by
-.Xr citrun_wrap 1 .
-If
-.Ar dir
-is given it will be searched instead of the current working
-directory.
-.Pp
-The
-.Nm
-utility will usually output two sections titled
+script outputs an instrumentation report. The script takes input from all files
+listed as arguments, usually
+.Pa citrun.log
+files created by a
+.Xr citrun_wrap 1
+invocation, and typically outputs two sections titled
.Qq Summary
and
-.Qq Totals
-each containing counts of certain events that occurred during
-rewriting.
+.Qq Totals .
.Pp
+When no arguments are given
+.Nm
+uses standard input.
+.Sh SUMMARY
The
.Qq Summary
-section contains at least one of the following events:
+section contains high, project level instrumentation information, its
+output can consist of the following events:
.Pp
.Bl -tag -width Ds
+.It Rewrite tool runs
+Number of times
+.Xr citrun_inst 1
+was invoked.
.It Source files used as input
-The total number of C/C++ source files input for rewriting.
+Number of C/C++ source files that had rewriting attempted.
.It Application link commands
-The number of application link commands detected during rewriting.
+Number of application link commands detected and modified.
.It Successful modified source compiles
-The number of rewritten source files successfully compiled with the native
-compiler.
+Number of source files both rewritten and compiled successfully.
.It Failed modified source compiles
-The number of rewritten source files that failed compilation with the native
-compiler.
+Number of source files rewritten successfully but not compiled.
.Pp
-This can happen for either two reasons:
+This can happen because either:
.Bl -bullet -compact
.It
-Compiling the original source file would have failed too
+The original source file would have failed compilation too
.It
-Only compiling the rewritten source file failed
+The source rewriting was bad and caused compilation to fail
.El
-.Pp
-The current software design does not admit an efficient, automatic method to
-tell the above two cases apart.
.El
+.Sh TOTALS
+The
+.Qq Totals
+section shows how many code transformations have been attempted.
+.Sh EXAMPLES
+.Dl $ citrun_report citrun.log
+.Dl $ citrun_report citrun.log */citrun.log */*/citrun.log
+.Dl $ find\ . -name citrun.log | xargs citrun_report
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
diff --git a/man/citrun_wrap.1 b/man/citrun_wrap.1
@@ -18,28 +18,32 @@
.Os
.Sh NAME
.Nm citrun_wrap
-.Nd add C It Run to a build command
+.Nd add code transformations to a build command
.Sh SYNOPSIS
.Nm
.Ar build_cmd
.Op Ar ...
.Sh DESCRIPTION
-Special information must be added to a programs source code to see it run.
+To see code run it first must be transformed, or
+.Qq rewritten ,
+slightly.
.Pp
The
.Nm
-utility enables source code rewriting on any files compiled during
+script tries source code rewriting on any source files compiled during
.Ar build_cmd .
Ideally
.Ar build_cmd
-is the top level build command.
+will be the top level build command.
.Pp
-The given
+For
+.Nm
+to detect source files
.Ar build_cmd
-must search
+must search the
.Ev PATH
-when finding compiler binaries.
-On UNIX-ish systems compiler binaries must named be one of the following:
+to find compiler binaries.
+On Unix-like systems those binaries must have one of the following names:
.Pp
.Bl -bullet -compact
.It
@@ -73,36 +77,40 @@ link
link.exe
.El
.Pp
-All rewriting activity is written to
-.Pa citrun.log
-files and human readable summaries may be generated by
-.Xr citrun_check 1 .
+When
+.Nm
+finds a potential source file
+.Xr citrun_inst 1
+is called to handle it, with rewriting activity output written to a file called
+.Pa citrun.log .
+See
+.Xr citrun_report 1
+for generating human readable summaries from these files.
.Pp
Incremental building is supported by
.Nm
but mixing object files created by different
-versions of C It Run is not.
+versions of this application is not.
.Sh FILES
.Bl -tag -width Ds
.It Pa citrun.log
-Rewrite activity log.
+Rewrite activity log, left all over the place after the build system has its way
+with the working directory.
.El
.Sh EXIT STATUS
The
.Nm
-utility exits with the build command exit code.
+utility exits with the same exit code as the build command.
.Sh EXAMPLES
-Let
-.Qq program
-be in a project that is:
+Suppose a project exists with the following properties:
.Pp
.Bl -bullet -compact
.It
written in C
.It
-compiled with gcc
+compiled with cc
.It
-built with make and make searches PATH for gcc
+built with make and make searches PATH for cc
.El
.Pp
Prepending
@@ -110,6 +118,7 @@ Prepending
to the build command adds instrumentation:
.Pp
.Dl $ citrun_wrap make
+.Dl cc -o program program.c
.Pp
Now see
.Qq program
@@ -121,5 +130,5 @@ If no viewer is running then
.Xr citrun_gl 1
is started.
.Sh SEE ALSO
-.Xr citrun_check 1 ,
+.Xr citrun_report 1 ,
.Xr citrun_gl 1
