sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 1 | |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 2 | Release notes for Valgrind |
| 3 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 4 | If you are building a binary package of Valgrind for distribution, |
| 5 | please read README_PACKAGERS. It contains some important information. |
sewardj | 365a851 | 2002-07-01 08:30:05 +0000 | [diff] [blame] | 6 | |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 7 | If you are developing Valgrind, please read README_DEVELOPERS. It contains |
| 8 | some useful information. |
| 9 | |
| 10 | For instructions on how to build/install, see the end of this file. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 11 | |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 12 | Valgrind works on most, reasonably recent Linux setups. If you have |
| 13 | problems, consult FAQ.txt to see if there are workarounds. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 14 | |
| 15 | Executive Summary |
| 16 | ~~~~~~~~~~~~~~~~~ |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 17 | Valgrind is a GPL'd system for debugging and profiling x86-Linux programs. |
| 18 | With the tools that come with Valgrind, you can automatically detect |
| 19 | many memory management and threading bugs, avoiding hours of frustrating |
| 20 | bug-hunting, making your programs more stable. You can also perform |
| 21 | detailed profiling to help speed up your programs. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 22 | |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 23 | The Valgrind distribution includes four tools: two memory error |
nethercote | 075a102 | 2004-04-10 00:36:25 +0000 | [diff] [blame] | 24 | detectors, a thread error detector, a cache profiler and a heap profiler. |
| 25 | Several other tools have been built with Valgrind. |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 26 | |
| 27 | To give you an idea of what Valgrind tools do, when a program is run |
| 28 | under the supervision of the first memory error detector tool, all reads |
| 29 | and writes of memory are checked, and calls to malloc/new/free/delete |
| 30 | are intercepted. As a result, it can detect problems such as: |
| 31 | |
| 32 | Use of uninitialised memory |
| 33 | Reading/writing memory after it has been free'd |
| 34 | Reading/writing off the end of malloc'd blocks |
| 35 | Reading/writing inappropriate areas on the stack |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 36 | Memory leaks -- where pointers to malloc'd blocks are lost forever |
| 37 | Passing of uninitialised and/or unaddressible memory to system calls |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 38 | Mismatched use of malloc/new/new [] vs free/delete/delete [] |
| 39 | Overlaps of arguments to strcpy() and related functions |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 40 | Some abuses of the POSIX pthread API |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 41 | |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 42 | Problems like these can be difficult to find by other means, often |
| 43 | lying undetected for long periods, then causing occasional, |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 44 | difficult-to-diagnose crashes. When one of these errors occurs, you can |
| 45 | attach GDB to your program, so you can poke around and see what's going |
| 46 | on. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 47 | |
| 48 | Valgrind is closely tied to details of the CPU, operating system and |
| 49 | to a less extent, compiler and basic C libraries. This makes it |
| 50 | difficult to make it portable, so I have chosen at the outset to |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 51 | concentrate on what I believe to be a widely used platform: x86/Linux. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 52 | |
| 53 | Valgrind is licensed under the GNU General Public License, version 2. |
njn25 | e49d8e7 | 2002-09-23 09:36:25 +0000 | [diff] [blame] | 54 | Read the file COPYING in the source distribution for details. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 55 | |
| 56 | |
| 57 | Documentation |
| 58 | ~~~~~~~~~~~~~ |
| 59 | A comprehensive user guide is supplied. Point your browser at |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 60 | $PREFIX/share/doc/valgrind/manual.html, where $PREFIX is whatever you |
| 61 | specified with --prefix= when building. |
sewardj | de4a1d0 | 2002-03-22 01:27:54 +0000 | [diff] [blame] | 62 | |
| 63 | |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 64 | Building and installing it |
| 65 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 66 | To install from CVS : |
| 67 | |
| 68 | 0. Check out the code from CVS, following the instructions at |
| 69 | http://developer.kde.org/source/anoncvs.html. The 'modulename' is |
| 70 | "valgrind". |
| 71 | |
| 72 | 1. cd into the source directory. |
| 73 | |
| 74 | 2. Run ./autogen.sh to setup the environment (you need the standard |
| 75 | autoconf tools to do so). |
| 76 | |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 77 | To install from a tar.bz2 distribution: |
nethercote | ed7e073 | 2003-12-02 15:30:28 +0000 | [diff] [blame] | 78 | |
| 79 | 3. Run ./configure, with some options if you wish. The standard |
| 80 | options are documented in the INSTALL file. The only interesting |
| 81 | one is the usual --prefix=/where/you/want/it/installed. |
| 82 | |
| 83 | 4. Do "make". |
| 84 | |
| 85 | 5. Do "make install", possibly as root if the destination permissions |
| 86 | require that. |
| 87 | |
| 88 | 6. See if it works. Try "valgrind ls -l". Either this works, |
| 89 | or it bombs out complaining it can't find argc/argv/envp. |
| 90 | In that case, mail me a bug report. |
| 91 | |
| 92 | Important! Do not move the valgrind installation into a place |
| 93 | different from that specified by --prefix at build time. This will |
| 94 | cause things to break in subtle ways, mostly when Valgrind handles |
| 95 | fork/exec calls. |
| 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) |
nethercote | 5da1e17 | 2003-12-03 21:44:45 +0000 | [diff] [blame] | 99 | Nick Nethercote (njn25@cam.ac.uk) |
| 100 | Jeremy Fitzhardinge (jeremy@goop.org) |