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 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 58 | |
gobry | e721a52 | 2002-03-22 13:38:30 +0000 | [diff] [blame] | 59 | If you install from CVS : |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 60 | |
gobry | e721a52 | 2002-03-22 13:38:30 +0000 | [diff] [blame] | 61 | 0. cd into the source directory |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 62 | |
gobry | e721a52 | 2002-03-22 13:38:30 +0000 | [diff] [blame] | 63 | 1. Run ./autogen.sh to setup the environment (you need the standard |
| 64 | autoconf tools to do so) |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 65 | |
gobry | e721a52 | 2002-03-22 13:38:30 +0000 | [diff] [blame] | 66 | If you install from a tar.gz archive: |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 67 | |
gobry | e721a52 | 2002-03-22 13:38:30 +0000 | [diff] [blame] | 68 | 2. Run ./configure, with some options if you wish. The standard |
| 69 | options are documented in the INSTALL file. |
| 70 | |
| 71 | 3. Do "make" |
| 72 | |
| 73 | 4. As root, do "make install" |
| 74 | |
| 75 | 5. See if it works. Try "valgrind ls -l". Either this works, |
| 76 | or it bombs out complaining it can't find argc/argv/envp. |
| 77 | If this happens, you'll have to futz around with |
| 78 | vg_main.c:710 to vg_main.c:790 to try and find suitable offsets. |
| 79 | It's not hard; many have been successful here. |
| 80 | |
| 81 | Once step 5 is successful, you can now use valgrind. Documentation |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 82 | is in docs/manual.html. The following auxiliary steps may enhance |
| 83 | your valgrinding experience, though. |
| 84 | |
gobry | 69896d5 | 2002-04-05 06:56:07 +0000 | [diff] [blame] | 85 | 6. Create a file containing enough suppressions so that |
gobry | 59528b2 | 2002-04-05 07:02:00 +0000 | [diff] [blame] | 86 | |
| 87 | valgrind xedit |
| 88 | |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 89 | runs without generating any errors. This means you've more |
| 90 | or less suppressed all the scummy errors from the X11 base |
| 91 | libraries and from glibc, which will make it easier to spot |
gobry | 69896d5 | 2002-04-05 06:56:07 +0000 | [diff] [blame] | 92 | genuine errors in your own code. The default.supp file |
| 93 | should contains a good starting point. Do *not* edit this file |
| 94 | however, as it will be overwritten at the next installation of |
gobry | def1bad | 2002-04-11 06:58:55 +0000 | [diff] [blame^] | 95 | valgrind, but create your own local.supp file. |
gobry | 69896d5 | 2002-04-05 06:56:07 +0000 | [diff] [blame] | 96 | |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 97 | |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 98 | Julian Seward (jseward@acm.org) |
| 99 | 15 Feb 2002 |