8th May 2003

The purpose of this small doc is to guide you in using Valgrind to
find and fix memory management bugs in WINE.

           ---------------------------------------------------

Here's a getting-started-quickly checklist.  It might sound daunting,
but once set up things work fairly well.

* You need Linux kernel 2.4 on x86.

* You need a fast machine, since programs run 25-100 x
  slower on Valgrind.  A 2600MHz machine is fairly usable.

* You need plenty of memory - at least 256Mb.

* You will need either a current CVS version of WINE, or any snapshot from
  20030408 onward.

* Build WINE for debugging:
    CFLAGS=-g ./configure
    make depend
    make install

* Build valgrind -- see the README file.  It's the standard
  ./configure ; make ; make install deal.

* Use it!
   1) Copy the program you want to test (and any related DLLs) somewhere
      WINE can get to them (make sure that the program runs under WINE
      first!).
   2) Copy any PDB (MSVC debugging) files into the same directory.
   3) valgrind --workaround-gcc296-bugs=yes --num-callers=30 wine myprogram.exe

  You can also use --gdb-attach=yes, but GDB won't be able to identify
  functions from MSVC built code - this is still useful for tracking bugs
  in WINE itself.

  The best way to find a bug in MSVC compiled code is to run the program in
  parallel under valgrind and WINE, and also under MSVC on a Windows box.

  When valgrind reports a bug in a function, set a breakpoint in the same
  place in MSVC. The fault is usually obvious - one of the variables in the
  statement at the breakpoint will have a garbage value in it.

* There is no point in using --leak-check=yes; it won't work since programs
  under WINE don't call the normal malloc/free etc.

* If you are debugging an MSVC compiled app, be prepared for the fact
  that Valgrind finds bugs in the underlying WINE too.

* Please read the Valgrind manual, docs/index.html.  It contains 
  considerable details about how to use it, what's really going on, 
  etc.

* If you have trouble with it, please let me know (arg@cyberscience.com)
  and I'll see if I can help you out - however - all the enhancements to
  valgrind are provided (with the gracious permission of Cyberscience) with no
  warranty or support commitments.

Adam Gundy (arg@cyberscience.com)
