1 2Building and not installing it 3~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4To run Valgrind without having to install it, run coregrind/valgrind 5with the VALGRIND_LIB environment variable set, where <dir> is the root 6of the source tree (and must be an absolute path). Eg: 7 8 VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind 9 10This allows you to compile and run with "make" instead of "make install", 11saving you time. 12 13Or, you can use the 'vg-in-place' script which does that for you. 14 15I recommend compiling with "make --quiet" to further reduce the amount of 16output spewed out during compilation, letting you actually see any errors, 17warnings, etc. 18 19 20Building a distribution tarball 21~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 22To build a distribution tarball from the valgrind sources: 23 24 make dist 25 26In addition to compiling, linking and packaging everything up, the command 27will also build the documentation. Even if all required tools for building the 28documentation are installed, this step may not succeed because of hidden 29dependencies. E.g. on Ubuntu you must have "docbook-xsl" installed. 30Additionally, specific tool versions maybe needed. 31 32If you only want to test whether the generated tarball is complete and runs 33regression tests successfully, building documentation is not needed. 34Edit docs/Makefile.am, search for BUILD_ALL_DOCS and follow instructions there. 35 36 37Running the regression tests 38~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 39To build and run all the regression tests, run "make [--quiet] regtest". 40 41To run a subset of the regression tests, execute: 42 43 perl tests/vg_regtest <name> 44 45where <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 47file. 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 54Running the performance tests 55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 56To build and run all the performance tests, run "make [--quiet] perf". 57 58To run a subset of the performance suite, execute: 59 60 perl perf/vg_perf <name> 61 62where <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 64file. Eg: 65 66 perl perf/vg_perf perf/ 67 perl perf/vg_perf perf/bz2.vgperf 68 perl perf/vg_perf perf/bz2 69 70To compare multiple versions of Valgrind, use the --vg= option multiple 71times. For example, if you have two Valgrinds next to each other, one in 72trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to 73compare them on all the performance tests: 74 75 perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/ 76 77 78Debugging Valgrind with GDB 79~~~~~~~~~~~~~~~~~~~~~~~~~~~ 80To debug the valgrind launcher program (<prefix>/bin/valgrind) just 81run it under gdb in the normal way. 82 83Debugging the main body of the valgrind code (and/or the code for 84a particular tool) requires a bit more trickery but can be achieved 85without 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 118Steps (1)--(3) can be put in a .gdbinit file, but any directory names must 119be fully expanded (ie. not an environment variable). 120 121A 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 137Self-hosting 138~~~~~~~~~~~~ 139To 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 154If you omit the --trace-children=yes, you'll only monitor Inner's launcher 155program, not its stage2. 156 157The whole thing is fragile, confusing and slow, but it does work well enough 158for you to get some useful performance data. Inner has most of 159its output (ie. those lines beginning with "==<pid>==") prefixed with a '>', 160which helps a lot. 161 162At the time of writing the allocator is not annotated with client requests 163so Memcheck is not as useful as it could be. It also has not been tested 164much, so don't be surprised if you hit problems. 165 166When 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 170Printing out problematic blocks 171~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 172If you want to print out a disassembly of a particular block that 173causes a crash, do the following. 174 175Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000 176--trace-notbelow=999999". This should print one line for each block 177translated, and that includes the address. 178 179Then re-run with 999999 changed to the highest bb number shown. 180This will print the one line per block, and also will print a 181disassembly of the block in which the fault occurred. 182