blob: e08d872575a77e62c088c73a32ecb688cc91737a [file] [log] [blame]
njne43d3ae2003-05-05 13:04:49 +00001
njne43d3ae2003-05-05 13:04:49 +00002Building and not installing it
3~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
njn090dc842005-03-12 16:47:07 +00004To run Valgrind without having to install it, run coregrind/valgrind
sewardj45f4e7c2005-09-27 19:20:21 +00005with the VALGRIND_LIB environment variable set, where <dir> is the root
njn090dc842005-03-12 16:47:07 +00006of the source tree (and must be an absolute path). Eg:
7
sewardj45f4e7c2005-09-27 19:20:21 +00008 VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind
njne43d3ae2003-05-05 13:04:49 +00009
10This allows you to compile and run with "make" instead of "make install",
11saving you time.
12
njn7bbc8d62007-02-19 04:09:24 +000013Or, you can use the 'vg-in-place' script which does that for you.
14
njne43d3ae2003-05-05 13:04:49 +000015I 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
20Running the regression tests
21~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22To build and run all the regression tests, run "make [--quiet] regtest".
23
24To run a subset of the regression tests, execute:
25
26 perl tests/vg_regtest <name>
27
28where <name> is a directory (all tests within will be run) or a single
29.vgtest test file, or the name of a program which has a like-named .vgtest
30file. Eg:
31
32 perl tests/vg_regtest memcheck
33 perl tests/vg_regtest memcheck/tests/badfree.vgtest
34 perl tests/vg_regtest memcheck/tests/badfree
35
nethercote16b59ee2004-10-09 15:59:05 +000036
njn6f582492006-06-02 23:59:40 +000037Running the performance tests
njn5359b6f2006-06-02 23:57:22 +000038~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
njn6f582492006-06-02 23:59:40 +000039To build and run all the performance tests, run "make [--quiet] perf".
njn5359b6f2006-06-02 23:57:22 +000040
njn6f582492006-06-02 23:59:40 +000041To run a subset of the performance suite, execute:
njn5359b6f2006-06-02 23:57:22 +000042
43 perl perf/vg_perf <name>
44
45where <name> is a directory (all tests within will be run) or a single
46.vgperf test file, or the name of a program which has a like-named .vgperf
47file. Eg:
48
49 perl perf/vg_perf perf/
50 perl perf/vg_perf perf/bz2.vgperf
51 perl perf/vg_perf perf/bz2
52
njn6f582492006-06-02 23:59:40 +000053To compare multiple versions of Valgrind, use the --vg= option multiple
njn5359b6f2006-06-02 23:57:22 +000054times. For example, if you have two Valgrinds next to each other, one in
njn6f582492006-06-02 23:59:40 +000055trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
56compare them on all the performance tests:
njn5359b6f2006-06-02 23:57:22 +000057
58 perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
59
60
nethercote16b59ee2004-10-09 15:59:05 +000061Debugging Valgrind with GDB
62~~~~~~~~~~~~~~~~~~~~~~~~~~~
tom4a5223b2005-11-17 12:31:12 +000063To debug the valgrind launcher program (<prefix>/bin/valgrind) just
64run it under gdb in the normal way.
nethercote4fffabd2004-11-02 09:13:12 +000065
tom4a5223b2005-11-17 12:31:12 +000066Debugging the main body of the valgrind code (and/or the code for
67a particular tool) requires a bit more trickery but can be achieved
68without too much problem by following these steps:
nethercote16b59ee2004-10-09 15:59:05 +000069
njn90c81922007-09-17 22:35:57 +000070(1) Set VALGRIND_LAUNCHER to point to the valgrind executable. Eg:
nethercote16b59ee2004-10-09 15:59:05 +000071
njn90c81922007-09-17 22:35:57 +000072 export VALGRIND_LAUNCHER=/usr/local/bin/valgrind
nethercote16b59ee2004-10-09 15:59:05 +000073
njn90c81922007-09-17 22:35:57 +000074 or for an uninstalled version in a source directory $DIR:
nethercote16b59ee2004-10-09 15:59:05 +000075
njn90c81922007-09-17 22:35:57 +000076 export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind
77
78(2) Run gdb on the tool executable. Eg:
79
80 gdb /usr/local/lib/valgrind/ppc32-linux/lackey
81
82 or
83
84 gdb $DIR/.in_place/x86-linux/memcheck
nethercote16b59ee2004-10-09 15:59:05 +000085
tom4a5223b2005-11-17 12:31:12 +000086(3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
87 stopping on a SIGSEGV or SIGILL:
88
89 (gdb) handle SIGILL SIGSEGV nostop noprint
90
91(4) Set any breakpoints you want and proceed as normal for gdb. The
92 macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set
93 a breakpoint VG_(do_exec), you could do like this in GDB:
94
95 (gdb) b vgPlain_do_exec
96
97(5) Run the tool with required options:
98
99 (gdb) run pwd
nethercote16b59ee2004-10-09 15:59:05 +0000100
njn90c81922007-09-17 22:35:57 +0000101Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
102be fully expanded (ie. not an environment variable).
njn585b8b32005-10-10 11:36:55 +0000103
njn4be4e2a2009-06-12 23:40:04 +0000104
njn585b8b32005-10-10 11:36:55 +0000105Self-hosting
106~~~~~~~~~~~~
107To run Valgrind under Valgrind:
108
njn801288e2009-08-04 07:02:54 +0000109(1) Check out 2 trees, "Inner" and "Outer". Inner runs the app
110 directly. Outer runs Inner.
njn585b8b32005-10-10 11:36:55 +0000111
112(2) Configure inner with --enable-inner and build/install as
113 usual.
114
njn801288e2009-08-04 07:02:54 +0000115(3) Configure Outer normally and build/install as usual.
njn585b8b32005-10-10 11:36:55 +0000116
117(4) Choose a very simple program (date) and try
118
njn86d68072005-11-12 19:07:45 +0000119 outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes \
njn585b8b32005-10-10 11:36:55 +0000120 --tool=cachegrind -v inner/.../bin/valgrind --tool=none -v prog
121
njn801288e2009-08-04 07:02:54 +0000122If you omit the --trace-children=yes, you'll only monitor Inner's launcher
njn7cce5b82005-11-16 20:12:22 +0000123program, not its stage2.
124
125The whole thing is fragile, confusing and slow, but it does work well enough
njn801288e2009-08-04 07:02:54 +0000126for you to get some useful performance data. Inner has most of
njn7cce5b82005-11-16 20:12:22 +0000127its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
128which helps a lot.
njn15a65632005-10-10 11:43:14 +0000129
130At the time of writing the allocator is not annotated with client requests
131so Memcheck is not as useful as it could be. It also has not been tested
132much, so don't be surprised if you hit problems.
njn0dc09e82005-11-03 16:24:53 +0000133
njn801288e2009-08-04 07:02:54 +0000134When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
135(on the outer). Otherwise, Callgrind has much higher memory requirements.
weidendo10e80e32006-05-01 01:49:28 +0000136
njn0b5efe72005-11-10 03:40:36 +0000137
njn0dc09e82005-11-03 16:24:53 +0000138Printing out problematic blocks
139~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
140If you want to print out a disassembly of a particular block that
141causes a crash, do the following.
142
143Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
144--trace-notbelow=999999". This should print one line for each block
145translated, and that includes the address.
146
147Then re-run with 999999 changed to the highest bb number shown.
148This will print the one line per block, and also will print a
149disassembly of the block in which the fault occurred.