citrun_wrap.1 (2703B)
1 .\" 2 .\" Copyright (c) 2016 Kyle Milz <kyle@0x30.net> 3 .\" 4 .\" Permission to use, copy, modify, and distribute this software for any 5 .\" purpose with or without fee is hereby granted, provided that the above 6 .\" copyright notice and this permission notice appear in all copies. 7 .\" 8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15 .\" 16 .Dd $Mdocdate: April 10 2016 $ 17 .Dt CITRUN_WRAP 1 18 .Os 19 .Sh NAME 20 .Nm citrun_wrap 21 .Nd add code transformations to a build command 22 .Sh SYNOPSIS 23 .Nm 24 .Ar build_cmd 25 .Op Ar ... 26 .Sh DESCRIPTION 27 To see code run it first must be transformed, or 28 .Qq rewritten , 29 slightly. 30 .Pp 31 The 32 .Nm 33 script tries source code rewriting on any source files compiled during 34 .Ar build_cmd . 35 Ideally 36 .Ar build_cmd 37 will be the top level build command. 38 .Pp 39 For 40 .Nm 41 to detect source files 42 .Ar build_cmd 43 must search the 44 .Ev PATH 45 to find compiler binaries. 46 On Unix-like systems those binaries must have one of the following names: 47 .Pp 48 .Bl -bullet -compact 49 .It 50 c++ 51 .It 52 cc 53 .It 54 clang 55 .It 56 clang++ 57 .It 58 eg++ 59 .It 60 egcc 61 .It 62 g++ 63 .It 64 gcc 65 .El 66 .Pp 67 On Windows compiler binaries must be named one of the following: 68 .Pp 69 .Bl -bullet -compact 70 .It 71 cl 72 .It 73 cl.exe 74 .It 75 link 76 .It 77 link.exe 78 .El 79 .Pp 80 When 81 .Nm 82 finds a potential source file 83 .Xr citrun_inst 1 84 is called to handle it, with rewriting activity output written to a file called 85 .Pa citrun.log . 86 See 87 .Xr citrun_report 1 88 for generating human readable summaries from these files. 89 .Pp 90 Incremental building is supported by 91 .Nm 92 but mixing object files created by different 93 versions of this application is not. 94 .Sh FILES 95 .Bl -tag -width Ds 96 .It Pa citrun.log 97 Rewrite activity log, left all over the place after the build system has its way 98 with the working directory. 99 .El 100 .Sh EXIT STATUS 101 The 102 .Nm 103 utility exits with the same exit code as the build command. 104 .Sh EXAMPLES 105 Suppose a project exists with the following properties: 106 .Pp 107 .Bl -bullet -compact 108 .It 109 written in C 110 .It 111 compiled with cc 112 .It 113 built with make and make searches PATH for cc 114 .El 115 .Pp 116 Prepending 117 .Nm 118 to the build command adds instrumentation: 119 .Pp 120 .Dl $ citrun_wrap make 121 .Dl cc -o program program.c 122 .Pp 123 Now see 124 .Qq program 125 run: 126 .Pp 127 .Dl $ ./program 128 .Pp 129 If no viewer is running then 130 .Xr citrun_gl 1 131 is started. 132 .Sh SEE ALSO 133 .Xr citrun_report 1 , 134 .Xr citrun_gl 1