README_DEVELOPERS

   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        --run-libc-freeres=no --tool=cachegrind -v \
 153        inner/.../bin/valgrind --vgdb-prefix=./inner --tool=none -v prog
 154
 155 If you omit the --trace-children=yes, you'll only monitor Inner's launcher
 156 program, not its stage2. Outer needs --run-libc-freeres=no, as otherwise
 157 it will try to find and run __libc_freeres in the inner, while libc is not
 158 used by the inner. Inner needs --vgdb-prefix=./inner to avoid inner
 159 gdbserver colliding with outer gdbserver.
 160
 161 Debugging the whole thing might imply to use up to 3 GDB:
 162   * a GDB attached to the Outer valgrind, allowing
 163     to examine the state of Outer.
 164   * a GDB using Outer gdbserver, allowing to
 165     examine the state of Inner.
 166   * a GDB using Inner gdbserver, allowing to
 167     examine the state of prog.
 168
 169 The whole thing is fragile, confusing and slow, but it does work well enough
 170 for you to get some useful performance data.  Inner has most of
 171 its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
 172 which helps a lot.
 173
 174 At the time of writing the allocator is not annotated with client requests
 175 so Memcheck is not as useful as it could be.  It also has not been tested
 176 much, so don't be surprised if you hit problems.
 177
 178 When using self-hosting with an outer Callgrind tool, use '--pop-on-jump'
 179 (on the outer). Otherwise, Callgrind has much higher memory requirements.
 180
 181
 182 Printing out problematic blocks
 183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 184 If you want to print out a disassembly of a particular block that
 185 causes a crash, do the following.
 186
 187 Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
 188 --trace-notbelow=999999".  This should print one line for each block
 189 translated, and that includes the address.
 190
 191 Then re-run with 999999 changed to the highest bb number shown.
 192 This will print the one line per block, and also will print a
 193 disassembly of the block in which the fault occurred.