regression tests: Remove superfluous backticks
[valgrind.git] / README_DEVELOPERS
blobfdd70b507eddf77312b1cdb06d6ac1f3a1e351b1
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:
8   VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind 
10 This allows you to compile and run with "make" instead of "make install",
11 saving you time.
13 Or, you can use the 'vg-in-place' script which does that for you.
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.
20 Building a distribution tarball
21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22 To build a distribution tarball from the valgrind sources:
24   make dist
26 In addition to compiling, linking and packaging everything up, the command
27 will also attempt to build the documentation.
29 If you only want to test whether the generated tarball is complete and runs
30 regression tests successfully, building documentation is not needed.
32   make dist BUILD_ALL_DOCS=no
34 If you insist on building documentation some embarrassing instructions
35 can be found in docs/README.
38 Running the regression tests
39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40 To build and run all the regression tests, run "make [--quiet] regtest".
42 To run a subset of the regression tests, execute:
44   perl tests/vg_regtest <name>
46 where <name> is a directory (all tests within will be run) or a single
47 .vgtest test file, or the name of a program which has a like-named .vgtest
48 file.  Eg:
50   perl tests/vg_regtest memcheck
51   perl tests/vg_regtest memcheck/tests/badfree.vgtest
52   perl tests/vg_regtest memcheck/tests/badfree
55 Running the performance tests
56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57 To build and run all the performance tests, run "make [--quiet] perf".
59 To run a subset of the performance suite, execute:
61   perl perf/vg_perf <name>
63 where <name> is a directory (all tests within will be run) or a single
64 .vgperf test file, or the name of a program which has a like-named .vgperf
65 file.  Eg:
67   perl perf/vg_perf perf/
68   perl perf/vg_perf perf/bz2.vgperf
69   perl perf/vg_perf perf/bz2
71 To compare multiple versions of Valgrind, use the --vg= option multiple
72 times.  For example, if you have two Valgrinds next to each other, one in
73 trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
74 compare them on all the performance tests:
76   perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
79 Debugging Valgrind with GDB
80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
81 To debug the valgrind launcher program (<prefix>/bin/valgrind) just
82 run it under gdb in the normal way.
84 Debugging the main body of the valgrind code (and/or the code for
85 a particular tool) requires a bit more trickery but can be achieved
86 without too much problem by following these steps:
88 (1) Set VALGRIND_LAUNCHER to point to the valgrind executable.  Eg:
90       export VALGRIND_LAUNCHER=/usr/local/bin/valgrind
92     or for an uninstalled version in a source directory $DIR:
94       export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind
96 (2) Run gdb on the tool executable.  Eg:
98       gdb /usr/local/lib/valgrind/ppc32-linux/lackey
100     or
102       gdb $DIR/.in_place/x86-linux/memcheck
104 (3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
105     stopping on a SIGSEGV or SIGILL:
107     (gdb) handle SIGILL SIGSEGV nostop noprint
109 (4) Set any breakpoints you want and proceed as normal for gdb. The
110     macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set
111     a breakpoint VG_(do_exec), you could do like this in GDB:
113     (gdb) b vgPlain_do_exec
115 (5) Run the tool with required options (the --tool option is required
116     for correct setup), e.g.
118     (gdb) run --tool=lackey pwd
120 Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
121 be fully expanded (ie. not an environment variable).
123 A different and possibly easier way is as follows:
125 (1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes.  This
126     puts the tool executable into a wait loop soon after it gains
127     control.  This delays startup for a few seconds.
129 (2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where
130     <pid> you read from the output printed by (1).  This attaches
131     GDB to the tool executable, which should be in the abovementioned
132     wait loop.
134 (3) Do "cont" to continue.  After the loop finishes spinning, startup
135     will continue as normal.  Note that comment (3) above re passing
136     signals applies here too.
139 Self-hosting
140 ~~~~~~~~~~~~
141 This section explains :
142   (A) How to configure Valgrind to run under Valgrind.
143       Such a setup is called self hosting, or outer/inner setup.
144   (B) How to run Valgrind regression tests in a 'self-hosting' mode,
145       e.g. to verify Valgrind has no bugs such as memory leaks.
146   (C) How to run Valgrind performance tests in a 'self-hosting' mode,
147       to analyse and optimise the performance of Valgrind and its tools.
149 (A) How to configure Valgrind to run under Valgrind:
151 (1) Check out 2 trees, "Inner" and "Outer".  Inner runs the app
152     directly.  Outer runs Inner.
154 (2) Configure inner with --enable-inner and build/install as usual.
156 (3) Configure Outer normally and build/install as usual.
158 (4) Choose a very simple program (date) and try
160     outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes  \
161        --smc-check=all-non-file \
162        --run-libc-freeres=no --tool=cachegrind -v \
163        inner/.../bin/valgrind --vgdb-prefix=./inner --tool=none -v prog
165 Note: You must use a "make install"-ed valgrind.
166 Do *not* use vg-in-place for the outer valgrind.
168 If you omit the --trace-children=yes, you'll only monitor Inner's launcher
169 program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise
170 it will try to find and run __libc_freeres in the inner, while libc is not
171 used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner
172 gdbserver colliding with outer gdbserver.
173 Currently, inner does *not* use the client request 
174 VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for
175 translation chaining. So the outer needs --smc-check=all-non-file to
176 detect the modified code.
178 Debugging the whole thing might imply to use up to 3 GDB:
179   * a GDB attached to the Outer valgrind, allowing
180     to examine the state of Outer.
181   * a GDB using Outer gdbserver, allowing to
182     examine the state of Inner.
183   * a GDB using Inner gdbserver, allowing to
184     examine the state of prog.
186 The whole thing is fragile, confusing and slow, but it does work well enough
187 for you to get some useful performance data.  Inner has most of
188 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
189 which helps a lot. However, when running regression tests in an Outer/Inner
190 setup, this prefix causes the reg test diff to fail. Give 
191 --sim-hints=no-inner-prefix to the Inner to disable the production
192 of the prefix in the stdout/stderr output of Inner.
194 The allocator (coregrind/m_mallocfree.c) is annotated with client requests
195 so Memcheck can be used to find leaks and use after free in an Inner
196 Valgrind.
198 The Valgrind "big lock" is annotated with helgrind client requests
199 so helgrind and drd can be used to find race conditions in an Inner
200 Valgrind.
202 All this has not been tested much, so don't be surprised if you hit problems.
204 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
205 (on the outer). Otherwise, Callgrind has much higher memory requirements. 
207 (B) Regression tests in an outer/inner setup:
209  To run all the regression tests with an outer memcheck, do :
210    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
211                          --all
213  To run a specific regression tests with an outer memcheck, do:
214    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
215                          none/tests/args.vgtest
217  To run regression tests with another outer tool:
218    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
219                          --outer-tool=helgrind --all
221  --outer-args allows to give specific arguments to the outer tool,
222  replacing the default one provided by vg_regtest.
224 Note: --outer-valgrind must be a "make install"-ed valgrind.
225 Do *not* use vg-in-place.
227 When an outer valgrind runs an inner valgrind, a regression test
228 produces one additional file <testname>.outer.log which contains the
229 errors detected by the outer valgrind.  E.g. for an outer memcheck, it
230 contains the leaks found in the inner, for an outer helgrind or drd,
231 it contains the detected race conditions.
233 The file tests/outer_inner.supp contains suppressions for 
234 the irrelevant or benign errors found in the inner.
236 (C) Performance tests in an outer/inner setup:
238  To run all the performance tests with an outer cachegrind, do :
239     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf
241  To run a specific perf test (e.g. bz2) in this setup, do :
242     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2
244  To run all the performance tests with an outer callgrind, do :
245     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
246                       --outer-tool=callgrind perf
248 Note: --outer-valgrind must be a "make install"-ed valgrind.
249 Do *not* use vg-in-place.
251  To compare the performance of multiple Valgrind versions, do :
252     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
253       --outer-tool=callgrind \
254       --vg=../inner_xxxx --vg=../inner_yyyy perf
255   (where inner_xxxx and inner_yyyy are the toplevel directories of
256   the versions to compare).
257   Cachegrind and cg_diff are particularly handy to obtain a delta
258   between the two versions.
260 When the outer tool is callgrind or cachegrind, the following
261 output files will be created for each test:
262    <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
263    <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
264  (where tt is the two letters abbreviation for the inner tool(s) run).
266 For example, the command
267     perl perf/vg_perf \
268       --outer-valgrind=../outer_trunk/install/bin/valgrind \
269       --outer-tool=callgrind \
270       --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records
272 produces the files
273     callgrind.out.inner_tchain.no.many-loss-records.18465
274     callgrind.outer.log.inner_tchain.no.many-loss-records.18465
275     callgrind.out.inner_tchain.me.many-loss-records.21899
276     callgrind.outer.log.inner_tchain.me.many-loss-records.21899
277     callgrind.out.inner_trunk.no.many-loss-records.21224
278     callgrind.outer.log.inner_trunk.no.many-loss-records.21224
279     callgrind.out.inner_trunk.me.many-loss-records.22916
280     callgrind.outer.log.inner_trunk.me.many-loss-records.22916
283 Printing out problematic blocks
284 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
285 If you want to print out a disassembly of a particular block that
286 causes a crash, do the following.
288 Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
289 --trace-notbelow=999999".  This should print one line for each block
290 translated, and that includes the address.
292 Then re-run with 999999 changed to the highest bb number shown.
293 This will print the one line per block, and also will print a
294 disassembly of the block in which the fault occurred.