sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame^] | 1 | |
| 2 | Release notes for Valgrind, snapshot 20020217 |
| 3 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 4 | |
| 5 | KDE3 developers: please read also README_KDE3_FOLKS for guidance |
| 6 | about how to debug KDE3 applications with Valgrind. |
| 7 | |
| 8 | For instructions on how to build/install, see the end of this file. |
| 9 | |
| 10 | |
| 11 | Executive Summary |
| 12 | ~~~~~~~~~~~~~~~~~ |
| 13 | Valgrind is a tool to help you find memory-management problems in your |
| 14 | programs. When a program is run under Valgrind's supervision, all |
| 15 | reads and writes of memory are checked, and calls to |
| 16 | malloc/new/free/delete are intercepted. As a result, Valgrind can |
| 17 | detect problems such as: |
| 18 | |
| 19 | Use of uninitialised memory |
| 20 | Reading/writing memory after it has been free'd |
| 21 | Reading/writing off the end of malloc'd blocks |
| 22 | Reading/writing inappropriate areas on the stack |
| 23 | Memory leaks -- where pointers to malloc'd blocks are lost forever |
| 24 | Passing of uninitialised and/or unaddressible memory to system calls |
| 25 | Mismatched use of malloc/new/new [] vs free/delete/delete [] |
| 26 | |
| 27 | Problems like these can be difficult to find by other means, often |
| 28 | lying undetected for long periods, then causing occasional, |
| 29 | difficult-to-diagnose crashes. |
| 30 | |
| 31 | When Valgrind detects such a problem, it can, if you like, attach GDB |
| 32 | to your program, so you can poke around and see what's going on. |
| 33 | |
| 34 | Valgrind is closely tied to details of the CPU, operating system and |
| 35 | to a less extent, compiler and basic C libraries. This makes it |
| 36 | difficult to make it portable, so I have chosen at the outset to |
| 37 | concentrate on what I believe to be a widely used platform: Red Hat |
| 38 | Linux 7.2, on x86s. I believe that it will work without significant |
| 39 | difficulty on other x86 GNU/Linux systems which use the 2.4 kernel and |
| 40 | GNU libc 2.2.X, for example SuSE 7.1 and Mandrake 8.0. Red Hat 6.2 is |
| 41 | also supported. It has worked in the past, and probably still does, |
| 42 | on RedHat 7.1 and 6.2. Note that I haven't compiled it on RedHat 7.1 |
| 43 | and 6.2 for a while, so they may no longer work now. |
| 44 | |
| 45 | Valgrind is licensed under the GNU General Public License, version 2. |
| 46 | Read the file LICENSE in the source distribution for details. |
| 47 | |
| 48 | |
| 49 | Documentation |
| 50 | ~~~~~~~~~~~~~ |
| 51 | A comprehensive user guide is supplied. Point your browser at |
| 52 | docs/index.html. If your browser doesn't like frames, point it |
| 53 | instead at docs/manual.html. |
| 54 | |
| 55 | |
| 56 | Building and installing it |
| 57 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 58 | At the moment, very rudimentary. |
| 59 | |
| 60 | This tarball is set up for a standard Red Hat 7.2 machine. No |
| 61 | configure script, no autoconf, no nothing. Do the following: |
| 62 | |
| 63 | 0. Unpack the sources and cd into the source directory. |
| 64 | |
| 65 | 1. Do "make" |
| 66 | |
| 67 | 2. See if it works. Try "./valgrind ls -l". Either this works, |
| 68 | or it bombs out complaining it can't find argc/argv/envp. |
| 69 | If this happens, you'll have to futz around with |
| 70 | vg_main.c:710 to vg_main.c:790 to try and find suitable offsets. |
| 71 | It's not hard; many have been successful here. |
| 72 | |
| 73 | Once step 2 is successful, you can now use valgrind. Documentation |
| 74 | is in docs/manual.html. The following auxiliary steps may enhance |
| 75 | your valgrinding experience, though. |
| 76 | |
| 77 | 3. Add enough suppressions to the default suppression file |
| 78 | (linux24.supp) so that |
| 79 | ./valgrind xedit |
| 80 | runs without generating any errors. This means you've more |
| 81 | or less suppressed all the scummy errors from the X11 base |
| 82 | libraries and from glibc, which will make it easier to spot |
| 83 | genuine errors in your own code. |
| 84 | |
| 85 | If you are using a machine with a 2.2 kernel (RedHat 6.2, |
| 86 | or Debian) you probably will want to edit the "valgrind" |
| 87 | shell script, to select the linux22.supp suppression file |
| 88 | (uncomment line 13; comment out line 14) |
| 89 | |
| 90 | If any kind soul would like to contribute a basic autoconf-style |
| 91 | configuration/install mechanism (the usual autoconf ; ./configure ; |
| 92 | make ; make install deal), that would be very much appreciated. I |
| 93 | will get round to it eventually, but there are only 24 hours in each |
| 94 | day. |
| 95 | |
| 96 | If you want to install it somewhere other than the build directory: |
| 97 | the files needed for installation are: valgrind.so, valgrinq.so, |
| 98 | valgrind, VERSION, linux24.supp. You can copy these to any directory |
| 99 | you like. |
| 100 | |
| 101 | I find it simplest to symlink <build_dir>/valgrind to somewhere |
| 102 | else in my path, so I can use it in-place. No need to "install" |
| 103 | really. |
| 104 | |
| 105 | Julian Seward (jseward@acm.org) |
| 106 | 15 Feb 2002 |