drd-manual.xml: Fix link to libstdc++ manual GLIBCXX_FORCE_NEW reference.
[valgrind.git] / README_DEVELOPERS
blob86f539bb6ffba8c67414cf95044447e8ff7e63b4
1 Building and installing it
2 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3 To build/install from the GIT repository or from a distribution
4 tarball, refer to the section with the same name in README.
6 Building and not installing it
7 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8 To run Valgrind without having to install it, run coregrind/valgrind
9 with the VALGRIND_LIB environment variable set, where <dir> is the root
10 of the source tree (and must be an absolute path).  Eg:
12   VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind 
14 This allows you to compile and run with "make" instead of "make install",
15 saving you time.
17 Or, you can use the 'vg-in-place' script which does that for you.
19 I recommend compiling with "make --quiet" to further reduce the amount of
20 output spewed out during compilation, letting you actually see any errors,
21 warnings, etc.
24 Building a distribution tarball
25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 To build a distribution tarball from the valgrind sources:
28   make dist
30 In addition to compiling, linking and packaging everything up, the command
31 will also attempt to build the documentation.
33 If you only want to test whether the generated tarball is complete and runs
34 regression tests successfully, building documentation is not needed.
36   make dist BUILD_ALL_DOCS=no
38 If you insist on building documentation some embarrassing instructions
39 can be found in docs/README.
42 Running the regression tests
43 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44 To build and run all the regression tests, run "make [--quiet] regtest".
46 To run a subset of the regression tests, execute:
48   perl tests/vg_regtest <name>
50 where <name> is a directory (all tests within will be run) or a single
51 .vgtest test file, or the name of a program which has a like-named .vgtest
52 file.  Eg:
54   perl tests/vg_regtest memcheck
55   perl tests/vg_regtest memcheck/tests/badfree.vgtest
56   perl tests/vg_regtest memcheck/tests/badfree
59 Running the performance tests
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61 To build and run all the performance tests, run "make [--quiet] perf".
63 To run a subset of the performance suite, execute:
65   perl perf/vg_perf <name>
67 where <name> is a directory (all tests within will be run) or a single
68 .vgperf test file, or the name of a program which has a like-named .vgperf
69 file.  Eg:
71   perl perf/vg_perf perf/
72   perl perf/vg_perf perf/bz2.vgperf
73   perl perf/vg_perf perf/bz2
75 To compare multiple versions of Valgrind, use the --vg= option multiple
76 times.  For example, if you have two Valgrinds next to each other, one in
77 trunk1/ and one in trunk2/, from within either trunk1/ or trunk2/ do this to
78 compare them on all the performance tests:
80   perl perf/vg_perf --vg=../trunk1 --vg=../trunk2 perf/
83 Debugging Valgrind with GDB
84 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
85 To debug the valgrind launcher program (<prefix>/bin/valgrind) just
86 run it under gdb in the normal way.
88 Debugging the main body of the valgrind code (and/or the code for
89 a particular tool) requires a bit more trickery but can be achieved
90 without too much problem by following these steps:
92 (1) Set VALGRIND_LAUNCHER to point to the valgrind executable.  Eg:
94       export VALGRIND_LAUNCHER=/usr/local/bin/valgrind
96     or for an uninstalled version in a source directory $DIR:
98       export VALGRIND_LAUNCHER=$DIR/coregrind/valgrind
100 (2) Run gdb on the tool executable.  Eg:
102       gdb /usr/local/lib/valgrind/lackey-ppc32-linux
104     or
106       gdb $DIR/.in_place/memcheck-x86-linux
108 (3) Do "handle SIGSEGV SIGILL nostop noprint" in GDB to prevent GDB from
109     stopping on a SIGSEGV or SIGILL:
111     (gdb) handle SIGILL SIGSEGV nostop noprint
113     If you are using lldb, then the equivalent command is
115     (lldb) pro hand -p true -s false -n false SIGILL SIGSEGV
117 (4) Set any breakpoints you want and proceed as normal for gdb. The
118     macro VG_(FUNC) is expanded to vgPlain_FUNC, so If you want to set
119     a breakpoint VG_(do_exec), you could do like this in GDB:
121     (gdb) b vgPlain_do_exec
123 (5) Run the tool with required options (the --tool option is required
124     for correct setup), e.g.
126     (gdb) run --tool=lackey pwd
128 Steps (1)--(3) can be put in a .gdbinit file, but any directory names must
129 be fully expanded (ie. not an environment variable).
131 A different and possibly easier way is as follows:
133 (1) Run Valgrind as normal, but add the flag --wait-for-gdb=yes.  This
134     puts the tool executable into a wait loop soon after it gains
135     control.  This delays startup for a few seconds.
137 (2) In a different shell, do "gdb /proc/<pid>/exe <pid>", where
138     <pid> you read from the output printed by (1).  This attaches
139     GDB to the tool executable, which should be in the abovementioned
140     wait loop.
142 (3) Do "cont" to continue.  After the loop finishes spinning, startup
143     will continue as normal.  Note that comment (3) above re passing
144     signals applies here too.
147 Self-hosting
148 ~~~~~~~~~~~~
149 This section explains :
150   (A) How to configure Valgrind to run under Valgrind.
151       Such a setup is called self hosting, or outer/inner setup.
152   (B) How to run Valgrind regression tests in a 'self-hosting' mode,
153       e.g. to verify Valgrind has no bugs such as memory leaks.
154   (C) How to run Valgrind performance tests in a 'self-hosting' mode,
155       to analyse and optimise the performance of Valgrind and its tools.
157 (A) How to configure Valgrind to run under Valgrind:
159 (1) Check out 2 trees, "Inner" and "Outer".  Inner runs the app
160     directly.  Outer runs Inner.
162 (2) Configure Inner with --enable-inner and build as usual.
164 (3) Configure Outer normally and build+install as usual.
165     Note: You must use a "make install"-ed valgrind.
166     Do *not* use vg-in-place for the Outer valgrind.
168 (4) Choose a very simple program (date) and try
170     outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes  \
171        --smc-check=all-non-file \
172        --run-libc-freeres=no --tool=cachegrind -v \
173        inner/.../vg-in-place --vgdb-prefix=./inner --tool=none -v prog
175 If you omit the --trace-children=yes, you'll only monitor Inner's launcher
176 program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise
177 it will try to find and run __libc_freeres in the inner, while libc is not
178 used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner
179 gdbserver colliding with outer gdbserver.
180 Currently, inner does *not* use the client request 
181 VALGRIND_DISCARD_TRANSLATIONS for the JITted code or the code patched for
182 translation chaining. So the outer needs --smc-check=all-non-file to
183 detect the modified code.
185 Debugging the whole thing might imply to use up to 3 GDB:
186   * a GDB attached to the Outer valgrind, allowing
187     to examine the state of Outer.
188   * a GDB using Outer gdbserver, allowing to
189     examine the state of Inner.
190   * a GDB using Inner gdbserver, allowing to
191     examine the state of prog.
193 The whole thing is fragile, confusing and slow, but it does work well enough
194 for you to get some useful performance data.  Inner has most of
195 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
196 which helps a lot. However, when running regression tests in an Outer/Inner
197 setup, this prefix causes the reg test diff to fail. Give 
198 --sim-hints=no-inner-prefix to the Inner to disable the production
199 of the prefix in the stdout/stderr output of Inner.
201 The allocators in coregrind/m_mallocfree.c and VEX/priv/main_util.h are
202 annotated with client requests so Memcheck can be used to find leaks
203 and use after free in an Inner Valgrind.
205 The Valgrind "big lock" is annotated with helgrind client requests
206 so Helgrind and DRD can be used to find race conditions in an Inner
207 Valgrind.
209 All this has not been tested much, so don't be surprised if you hit problems.
211 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
212 (on the outer). Otherwise, Callgrind has much higher memory requirements. 
214 (B) Regression tests in an outer/inner setup:
216  To run all the regression tests with an outer memcheck, do :
217    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
218                          --all
220  To run a specific regression tests with an outer memcheck, do:
221    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
222                          none/tests/args.vgtest
224  To run regression tests with another outer tool:
225    perl tests/vg_regtest --outer-valgrind=../outer/.../bin/valgrind \
226                          --outer-tool=helgrind --all
228  --outer-args allows to give specific arguments to the outer tool,
229  replacing the default one provided by vg_regtest.
231 Note: --outer-valgrind must be a "make install"-ed valgrind.
232 Do *not* use vg-in-place.
234 When an outer valgrind runs an inner valgrind, a regression test
235 produces one additional file <testname>.outer.log which contains the
236 errors detected by the outer valgrind.  E.g. for an outer memcheck, it
237 contains the leaks found in the inner, for an outer helgrind or drd,
238 it contains the detected race conditions.
240 The file tests/outer_inner.supp contains suppressions for 
241 the irrelevant or benign errors found in the inner.
243 An regression test running in the inner (e.g. memcheck/tests/badrw) will
244 cause the inner to report an error, which is expected and checked
245 as usual when running the regtests in an outer/inner setup.
246 However, the outer will often also observe an error, e.g. a jump
247 using uninitialised data, or a read/write outside the bounds of a heap
248 block. When the outer reports such an error, it will output the
249 inner host stacktrace. To this stacktrace, it will append the
250 stacktrace of the inner guest program. For example, this is an error
251 reported by the outer when the inner runs the badrw regtest:
252   ==8119== Invalid read of size 2
253   ==8119==    at 0x7F2EFD7AF: ???
254   ==8119==    by 0x7F2C82EAF: ???
255   ==8119==    by 0x7F180867F: ???
256   ==8119==    by 0x40051D: main (badrw.c:5)
257   ==8119==    by 0x7F180867F: ???
258   ==8119==    by 0x1BFF: ???
259   ==8119==    by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332)
260   ==8119==    by 0x40055C: main (badrw.c:22)
261   ==8119==  Address 0x55cd03c is 4 bytes before a block of size 16 alloc'd
262   ==8119==    at 0x2804E26D: vgPlain_arena_malloc (m_mallocfree.c:1914)
263   ==8119==    by 0x2800BAB4: vgMemCheck_new_block (mc_malloc_wrappers.c:368)
264   ==8119==    by 0x2800BC87: vgMemCheck_malloc (mc_malloc_wrappers.c:403)
265   ==8119==    by 0x28097EAE: do_client_request (scheduler.c:1861)
266   ==8119==    by 0x28097EAE: vgPlain_scheduler (scheduler.c:1425)
267   ==8119==    by 0x280A7237: thread_wrapper (syswrap-linux.c:103)
268   ==8119==    by 0x280A7237: run_a_thread_NORETURN (syswrap-linux.c:156)
269   ==8119==    by 0x3803B7F0: _______VVVVVVVV_appended_inner_guest_stack_VVVVVVVV_______ (m_execontext.c:332)
270   ==8119==    by 0x4C294C4: malloc (vg_replace_malloc.c:298)
271   ==8119==    by 0x40051D: main (badrw.c:5)
272 In the above, the first stacktrace starts with the inner host stacktrace,
273 which in this case is some JITted code. Such code sometimes contains IPs
274 that points in the inner guest code (0x40051D: main (badrw.c:5)).
275 After the separator, we have the inner guest stacktrace.
276 The second stacktrace gives the stacktrace where the heap block that was
277 overrun was allocated. We see it was allocated by the inner valgrind
278 in the client arena (first part of the stacktrace). The second part is
279 the guest stacktrace that did the allocation.
282 (C) Performance tests in an outer/inner setup:
284  To run all the performance tests with an outer cachegrind, do :
285     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf
287  To run a specific perf test (e.g. bz2) in this setup, do :
288     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind perf/bz2
290  To run all the performance tests with an outer callgrind, do :
291     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
292                       --outer-tool=callgrind perf
294 Note: --outer-valgrind must be a "make install"-ed valgrind.
295 Do *not* use vg-in-place.
297  To compare the performance of multiple Valgrind versions, do :
298     perl perf/vg_perf --outer-valgrind=../outer/.../bin/valgrind \
299       --outer-tool=callgrind \
300       --vg=../inner_xxxx --vg=../inner_yyyy perf
301   (where inner_xxxx and inner_yyyy are the toplevel directories of
302   the versions to compare).
303   Cachegrind and cg_diff are particularly handy to obtain a delta
304   between the two versions.
306 When the outer tool is callgrind or cachegrind, the following
307 output files will be created for each test:
308    <outertoolname>.out.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
309    <outertoolname>.outer.log.<inner_valgrind_dir>.<tt>.<perftestname>.<pid>
310  (where tt is the two letters abbreviation for the inner tool(s) run).
312 For example, the command
313     perl perf/vg_perf \
314       --outer-valgrind=../outer_trunk/install/bin/valgrind \
315       --outer-tool=callgrind \
316       --vg=../inner_tchain --vg=../inner_trunk perf/many-loss-records
318 produces the files
319     callgrind.out.inner_tchain.no.many-loss-records.18465
320     callgrind.outer.log.inner_tchain.no.many-loss-records.18465
321     callgrind.out.inner_tchain.me.many-loss-records.21899
322     callgrind.outer.log.inner_tchain.me.many-loss-records.21899
323     callgrind.out.inner_trunk.no.many-loss-records.21224
324     callgrind.outer.log.inner_trunk.no.many-loss-records.21224
325     callgrind.out.inner_trunk.me.many-loss-records.22916
326     callgrind.outer.log.inner_trunk.me.many-loss-records.22916
329 Printing out problematic blocks
330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
331 If you want to print out a disassembly of a particular block that
332 causes a crash, do the following.
334 Try running with "--vex-guest-chase=no --trace-flags=10000000
335 --trace-notbelow=999999".  This should print one line for each block
336 translated, and that includes the address.
338 Then re-run with 999999 changed to the highest bb number shown.
339 This will print the one line per block, and also will print a
340 disassembly of the block in which the fault occurred.