1 2 Building and not installing it 3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4 To run Valgrind without having to install it, run coregrind/valgrind 5 with the VALGRIND_LIB environment variable set, where <dir> is the root 6 of the source tree (and must be an absolute path). Eg: 7 8 VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind 9 10 This allows you to compile and run with "make" instead of "make install", 11 saving you time. 12 13 Or, you can use the 'vg-in-place' script which does that for you. 14 15 I recommend compiling with "make --quiet" to further reduce the amount of 16 output spewed out during compilation, letting you actually see any errors, 17 warnings, etc. 18 19 20 Building a distribution tarball 21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 22 To build a distribution tarball from the valgrind sources: 23 24 make dist 25 26 In addition to compiling, linking and packaging everything up, the command 27 will also build the documentation. Even if all required tools for building the 28 documentation are installed, this step may not succeed because of hidden 29 dependencies. E.g. on Ubuntu you must have "docbook-xsl" installed. 30 Additionally, specific tool versions maybe needed. 31 32 If you only want to test whether the generated tarball is complete and runs 33 regression tests successfully, building documentation is not needed. 34 Edit docs/Makefile.am, search for BUILD_ALL_DOCS and follow instructions there. 35 36 37 Running the regression tests 38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 39 To build and run all the regression tests, run "make [--quiet] regtest". 40 41 To run a subset of the regression tests, execute: 42 43 perl tests/vg_regtest <name> 44 45 where <name> is a directory (all tests within will be run) or a single 46 .vgtest test file, or the name of a program which has a like-named .vgtest 47 file. Eg: 48 49 perl tests/vg_regtest memcheck 50 perl tests/vg_regtest memcheck/tests/badfree.vgtest 51 perl tests/vg_regtest memcheck/tests/badfree 52 53 54 Running the performance tests 55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 56 To build and run all the performance tests, run "make [--quiet] perf". 57 58 To run a subset of the performance suite, execute: 59 60 perl perf/vg_perf <name> 61 62 where <name> is a directory (all tests within will be run) or a single 63 .vgperf test file, or the name of a program which has a like-named .vgperf 64 file. Eg: 65 66 perl perf/vg_perf perf/ 67 perl perf/vg_perf perf/bz2.vgperf 68 perl perf/vg_perf perf/bz2 69 70 To compare multiple versions of Valgrind, use the --vg= option multiple 71 times. For example, if you have two Valgrinds next to each other, one in 72 trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to 73 compare them on all the performance tests: 74 75 perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/ 76 77 78 Debugging Valgrind with GDB 79 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 80 To debug the valgrind launcher program (<prefix>/bin/valgrind) just 81 run it under gdb in the normal way. 82 83 Debugging the main body of the valgrind code (and/or the code for 84 a particular tool) requires a bit more trickery but can be achieved 85 without too much problem by following these steps: 86 87 (1) Set VALGRIND_LAUNCHER to point to the valgrind executable. Eg: 88 89 export VALGRIND_LAUNCHER=/usr/local/bin/valgrind 90 91 or for an uninstalled version in a source directory $DIR: 92 93 export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind 94 95 (2) Run gdb on the tool executable. Eg: 96 97 gdb /usr/local/lib/valgrind/ppc32-linux/lackey 98 99 or 100 101 gdb $DIR/.in_place/x86-linux/memcheck 102 103 (3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from 104 stopping on a SIGSEGV or SIGILL: 105 106 (gdb) handle SIGILL SIGSEGV nostop noprint 107 108 (4) Set any breakpoints you want and proceed as normal for gdb. The 109 macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set 110 a breakpoint VG_(do_exec), you could do like this in GDB: 111 112 (gdb) b vgPlain_do_exec 113 114 (5) Run the tool with required options: 115 116 (gdb) run pwd 117 118 Steps (1)--(3) can be put in a .gdbinit file, but any directory names must 119 be fully expanded (ie. not an environment variable). 120 121 A different and possibly easier way is as follows: 122 123 (1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes. This 124 puts the tool executable into a wait loop soon after it gains 125 control. This delays startup for a few seconds. 126 127 (2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where 128 <pid> you read from the output printed by (1). This attaches 129 GDB to the tool executable, which should be in the abovementioned 130 wait loop. 131 132 (3) Do "cont" to continue. After the loop finishes spinning, startup 133 will continue as normal. Note that comment (3) above re passing 134 signals applies here too. 135 136 137 Self-hosting 138 ~~~~~~~~~~~~ 139 To run Valgrind under Valgrind: 140 141 (1) Check out 2 trees, "Inner" and "Outer". Inner runs the app 142 directly. Outer runs Inner. 143 144 (2) Configure inner with --enable-inner and build/install as 145 usual. 146 147 (3) Configure Outer normally and build/install as usual. 148 149 (4) Choose a very simple program (date) and try 150 151 outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes \ 152 --tool=cachegrind -v inner/.../bin/valgrind --tool=none -v prog 153 154 If you omit the --trace-children=yes, you'll only monitor Inner's launcher 155 program, not its stage2. 156 157 The whole thing is fragile, confusing and slow, but it does work well enough 158 for you to get some useful performance data. Inner has most of 159 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>', 160 which helps a lot. 161 162 At the time of writing the allocator is not annotated with client requests 163 so Memcheck is not as useful as it could be. It also has not been tested 164 much, so don't be surprised if you hit problems. 165 166 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump' 167 (on the outer). Otherwise, Callgrind has much higher memory requirements. 168 169 170 Printing out problematic blocks 171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 172 If you want to print out a disassembly of a particular block that 173 causes a crash, do the following. 174 175 Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000 176 --trace-notbelow=999999". This should print one line for each block 177 translated, and that includes the address. 178 179 Then re-run with 999999 changed to the highest bb number shown. 180 This will print the one line per block, and also will print a 181 disassembly of the block in which the fault occurred. 182
