
5 November 2003

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

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

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


* You need an x86 box running a Linux 2.4 kernel, with glibc 
  2.2.X or 2.3.X and XFree86 3.X or 4.X.  In practice this means 
  practically any recent Linux distro.

* You need a reasonably fast machine, since programs run 25-100 x
  slower on Valgrind.  I work with a 1133 MHz PIII with 512 M of
  memory.  Interactive programs like kate, konqueror, etc, are
  usable, but in all, the faster your machine, the more useful 
  valgrind will be.

* You need at least 256M of memory for reasonable behaviour.  Valgrind
  inflates the memory use of KDE apps approximately 3-4 x, so (eg) 
  konqueror needs ~ 140M of memory to get started, although to be fair,
  at least 40 M of that is due to reading the debug info -- this is for
  a konqueror and all libraries built with -O -g.

* You need to compile the KDE to be debugged, using a decent gcc/g++:

  - gcc 2.96-*, which comes with Red Hat 7.2, is buggy.  It sometimes
    generates code with reads below %esp, even for simple functions.
    This means you will be flooded with errors which are nothing to
    do with your program.  You can use the --workaround-gcc296-bugs=yes 
    flag to ignore them.  See the manual for details; this is not really 
    a good solution.

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

* Build as much of KDE+Qt as you can with -g and without -O, for 
  the usual reasons.

* Use it!
     /path/to/valgrind $KDEDIR/bin/kate 
  (or whatever).

* If you are debugging KDE apps, be prepared for the fact that
  Valgrind finds bugs in the underlying Qt (qt-copy from CVS) too.

* Please read the Valgrind manual, share/doc/valgrind/manual.html 
  in the installation tree.  It contains considerable details about 
  how to use it, what's really going on, etc.


Have fun!  If you find Valgrind useful in finding and fixing bugs,
our efforts will have been worthwhile.

Julian Seward (jseward@acm.org)
Nick Nethercote (njn25@cam.ac.uk)
Jeremy Fitzhardinge (jeremy@goop.org)