citrun

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

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:
Mbin/Makefile | 7+++----
Abin/citrun_report.1 | 81+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Abin/citrun_wrap.1 | 134+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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