README_DEVELOPERS

Building and not installing it
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To run Valgrind without having to install it, run coregrind/valgrind
with the VALGRIND_LIB environment variable set, where <dir> is the root
of the source tree (and must be an absolute path).  Eg:

  VALGRIND_LIB=~/grind/head4/.in_place ~/grind/head4/coregrind/valgrind 

This allows you to compile and run with "make" instead of "make install",
saving you time.

I recommend compiling with "make --quiet" to further reduce the amount of
output spewed out during compilation, letting you actually see any errors,
warnings, etc.


Running the regression tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To build and run all the regression tests, run "make [--quiet] regtest".

To run a subset of the regression tests, execute:

  perl tests/vg_regtest <name>

where <name> is a directory (all tests within will be run) or a single
.vgtest test file, or the name of a program which has a like-named .vgtest
file.  Eg:

  perl tests/vg_regtest memcheck
  perl tests/vg_regtest memcheck/tests/badfree.vgtest
  perl tests/vg_regtest memcheck/tests/badfree


Debugging Valgrind with GDB
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To debug stage 1 just run it under GDB in the normal way.

To debug Valgrind proper (stage 2) with GDB, start Valgrind like this:

  valgrind --tool=none --wait-for-gdb=yes <prog>

Then start gdb like this in another terminal:

  gdb /usr/lib/valgrind/stage2 <pid>

Where <pid> is the pid valgrind printed. Then set whatever breakpoints
you want and do this in gdb:

  jump *$eip


Self-hosting
~~~~~~~~~~~~
To run Valgrind under Valgrind:

(1) Check out 2 trees, "inner" and "outer".  "inner" runs the app
    directly and is what you will be profiling.  "outer" does the
    profiling.

(2) Configure inner with --enable-inner and build/install as
    usual.

(3) Configure outer normally and build/install as usual.

(4) Choose a very simple program (date) and try

    outer/.../bin/valgrind --sim-hints=enable-outer --trace-children=yes  \
       --tool=cachegrind -v inner/.../bin/valgrind --tool=none -v prog

If you omit the --trace-children=yes, you'll only monitor inner's launcher
program, not its stage2.

The whole thing is fragile, confusing and slow, but it does work well enough
for you to get some useful performance data.  The inner Valgrind has most of
its output (ie. those lines beginning with "==<pid>==") prefixed with a '>',
which helps a lot.

At the time of writing the allocator is not annotated with client requests
so Memcheck is not as useful as it could be.  It also has not been tested
much, so don't be surprised if you hit problems.


Printing out problematic blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to print out a disassembly of a particular block that
causes a crash, do the following.

Try running with "--vex-guest-chase-thresh=0 --trace-flags=10000000
--trace-notbelow=999999".  This should print one line for each block
translated, and that includes the address.

Then re-run with 999999 changed to the highest bb number shown.
This will print the one line per block, and also will print a
disassembly of the block in which the fault occurred.