commit 7a6ab13c7716dc73a96bf77be8bd4129fbe2afbc
parent faa0c5553541f0bafa361af8d2b4e21b6ee42e06
Author: Kyle Milz <milz@sparc.0x30.net>
Date: Thu, 4 Mar 2021 11:26:23 +0000
bin: use bsd.prog.mk
Diffstat:
3 files changed, 218 insertions(+), 4 deletions(-)
diff --git a/bin/Makefile b/bin/Makefile
@@ -1,6 +1,7 @@
PROGS= citrun_report citrun_wrap
-all: ${PROGS}
+SRCS_citrun_report= report.awk
+SRCS_citrun_wrap= wrap.sh
citrun_wrap: wrap.sh
sed -e "s, PREFIX ,$(PREFIX)," ${.CURDIR}/wrap.sh > $@
@@ -11,8 +12,6 @@ citrun_report: report.awk
cat ${.CURDIR}/report.awk >> $@
chmod +x $@
-clean:
- rm -f ${PROGS}
-
.include "../Makefile.in"
+.include <bsd.prog.mk>
diff --git a/bin/citrun_report.1 b/bin/citrun_report.1
@@ -0,0 +1,81 @@
+.\"
+.\" 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: September 18 2017 $
+.Dt CITRUN_REPORT 1
+.Os
+.Sh NAME
+.Nm citrun_report
+.Nd create instrumentation reports
+.Sh SYNOPSIS
+.Nm
+.Op Ar citrun.log
+.Op Ar ...
+.Sh DESCRIPTION
+The
+.Nm
+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 .
+.Pp
+When no arguments are given
+.Nm
+uses standard input.
+.Sh SUMMARY
+The
+.Qq Summary
+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
+Number of C/C++ source files that had rewriting attempted.
+.It Application link commands
+Number of application link commands detected and modified.
+.It Successful modified source compiles
+Number of source files both rewritten and compiled successfully.
+.It Failed modified source compiles
+Number of source files rewritten successfully but not compiled.
+.Pp
+This can happen because either:
+.Bl -bullet -compact
+.It
+The original source file would have failed compilation too
+.It
+The source rewriting was bad and caused compilation to fail
+.El
+.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
+.Xr citrun_wrap 1
diff --git a/bin/citrun_wrap.1 b/bin/citrun_wrap.1
@@ -0,0 +1,134 @@
+.\"
+.\" Copyright (c) 2016 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: April 10 2016 $
+.Dt CITRUN_WRAP 1
+.Os
+.Sh NAME
+.Nm citrun_wrap
+.Nd add code transformations to a build command
+.Sh SYNOPSIS
+.Nm
+.Ar build_cmd
+.Op Ar ...
+.Sh DESCRIPTION
+To see code run it first must be transformed, or
+.Qq rewritten ,
+slightly.
+.Pp
+The
+.Nm
+script tries source code rewriting on any source files compiled during
+.Ar build_cmd .
+Ideally
+.Ar build_cmd
+will be the top level build command.
+.Pp
+For
+.Nm
+to detect source files
+.Ar build_cmd
+must search the
+.Ev PATH
+to find compiler binaries.
+On Unix-like systems those binaries must have one of the following names:
+.Pp
+.Bl -bullet -compact
+.It
+c++
+.It
+cc
+.It
+clang
+.It
+clang++
+.It
+eg++
+.It
+egcc
+.It
+g++
+.It
+gcc
+.El
+.Pp
+On Windows compiler binaries must be named one of the following:
+.Pp
+.Bl -bullet -compact
+.It
+cl
+.It
+cl.exe
+.It
+link
+.It
+link.exe
+.El
+.Pp
+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 this application is not.
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa citrun.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 same exit code as the build command.
+.Sh EXAMPLES
+Suppose a project exists with the following properties:
+.Pp
+.Bl -bullet -compact
+.It
+written in C
+.It
+compiled with cc
+.It
+built with make and make searches PATH for cc
+.El
+.Pp
+Prepending
+.Nm
+to the build command adds instrumentation:
+.Pp
+.Dl $ citrun_wrap make
+.Dl cc -o program program.c
+.Pp
+Now see
+.Qq program
+run:
+.Pp
+.Dl $ ./program
+.Pp
+If no viewer is running then
+.Xr citrun_gl 1
+is started.
+.Sh SEE ALSO
+.Xr citrun_report 1 ,
+.Xr citrun_gl 1